Publishing admin docs to the knowledge base

KCWorks administrator how-tos in this documentation set can be synced into the MESH knowledge-base repository using kc-knowledge-base-sync (the kb-sync CLI).

The tool lives in its own repository and is included in kcworks-next as a git submodule at site/kcworks/dependencies/kc-knowledge-base-sync, installed as a dev-only Python dependency.

Setup

From the kcworks-next repository root:

git submodule update --init site/kcworks/dependencies/kc-knowledge-base-sync
uv sync --group dev
cp docs/knowledge_base_sync/config.example.yaml docs/knowledge_base_sync/config.yaml

Edit docs/knowledge_base_sync/config.yaml for your local paths (kcworks-next root, knowledge-base clone, and optional LM Studio host). That file is gitignored.

You also need a local clone of the knowledge-base repository.

Usage

Run from the kcworks-next root. The default config is docs/knowledge_base_sync/config.yaml, so --config is optional:

uv run kb-sync --dry-run
uv run kb-sync --force
uv run kb-sync --force --commit --pr

Flag

Purpose

--dry-run

Show planned output paths without writing files

--force

Overwrite existing knowledge-base articles

--use-llm

Format with LM Studio instead of the built-in converter

--commit

Rebuild indexes and commit in the knowledge-base repo

--pr

Push and open a GitHub pull request (requires --commit)

See the package README for the full flag list and configuration reference.

Which sections are synced

By default, only headings that match How do I …? (levels 2–4) are extracted. That pattern is used throughout the Administrator’s Guide.

To include a section with a different heading, place an HTML comment on the line immediately above it:

<!-- kb-sync -->
## Deploy a hotfix without downtime

Optional article title override:

<!-- kb-sync: Deploy a hotfix -->
## Internal procedure (staging only)

Generated knowledge-base filenames use a slug derived from the title. Apostrophes are stripped from slugs (user's → users), so related articles stay consistently named.

Configuring sources

docs/knowledge_base_sync/config.yaml maps documentation directories to knowledge-base topic folders. The default example syncs selected files from docs/source/admin_guide into internal/works-maintenance in the knowledge-base.

Adjust sources when adding new admin-guide pages or targeting a different KB topic.

Further reading