30 · Bringing the user guide into the KB

The platform user guide is authored as Markdown files in /opt/docs/user-guide/*.md. Out of the box those files only live on disk — they're not in your KB module, so you can't search or share them from /admin/kb.

To fix that, the admin KB page has a 📥 Sync platform user guide button (top-right). Clicking it imports every doc into the KB under a new category called Platform user guide.

Where to find it

/admin/kb → 📥 Sync platform user guide (admin only).

📷 Screenshot placeholder: screenshots/admin-kb-sync.png

What it does

For each *.md in /opt/docs/user-guide/:

1. Derive the title from the file's first # H1 (with leading numbering like "01 · " stripped).
2. Slug the article as ug-<filename-without-extension> so they don't collide with hand-authored articles.
3. Derive an excerpt from the first paragraph after the H1.
4. Create or update a published KbArticle under the Platform user guide category (the category is created on first run if it doesn't exist).

The importer is idempotent — re-run after every docs update and existing articles get their title, body, and excerpt refreshed in place. The README.md index file is skipped, as are empty or unreadable files. The endpoint returns a JSON report of how many articles were created, updated, and skipped.

Articles deleted from disk between runs are not auto-removed — clean up stale articles manually in the KB UI.

Result

After the first sync you'll see one article per .md file (currently ~34, every chapter of this guide) in /admin/kb → Platform user guide, covering:

• Getting started, Portal overview
• Helpdesk, CRM, RMM, Projects, Customers, KB, E-Sign, Messaging, Meetings, Assets, Marketing, Billing, Files & vault, Design studio, Quick-support
• Admin chapters: Tenants, Users, Licence, Helpdesk config, Assets config, Projects config, RMM config, Integrations, Platform health
• Glossary, Timesheets, Contractors / Vendors

Each article is imported with status Published.

⚠️ Caution. The KB does not separate "internal" and "public" articles — every Published article is reachable on the customer-facing kb.kwgroup.uk help centre (under its category slug). Because the importer publishes the user-guide articles, they will appear on the public KB once synced. If that's not wanted, change their status to Draft (or Archived) in the KB UI after importing — but note the next sync will re-publish them.

⚠️ Caution. If you edit an article inside the KB UI, the next sync will overwrite its title, body, and excerpt with the on-disk markdown. Treat the KB copies as read-only mirrors; edit the source .md files instead, then re-run the sync.

Future enhancement

A scheduled cron (every commit, or nightly) could call this endpoint automatically. For now it's manual — the import is fast (well under a second for the full guide).

See also

• Knowledge base