Dogfooding Showcase: Building & Publishing This Manual with qwiki-builder

This manual (home.qwiki.wiki/manual/) is itself a live demonstration of eating our own dogfood: every category, nested folder, Markdown chapter, Mermaid diagram, and UI screenshot you are reading is managed and published by qwiki-builder against Standalone Qwiki's api/publish.php.

End-to-End qwiki-builder Pipeline

flowchart LR
    Init["1. qwiki-builder init . --template blank"] --> Author["2. Author docs/ & docs/assets/images/"]
    Author --> Validate["3. qwiki-builder validate"]
    Validate -->|"Zero errors/warnings"| DryRun["4. qwiki-builder publish --dry-run"]
    DryRun --> Publish["5. qwiki-builder publish"]
    Publish --> Categories["Create top & nested categories (parentId)"]
    Publish --> Assets["Upload PNG/SVG/MP4 & rewrite paths"]
    Publish --> Chapters["Upsert chapters with stable slugs"]

How This Manual Is Structured (qwiki-project.json)

The project manifest declares top-level categories (manual-welcome, manual-user-guide, manual-admin-guide, manual-technical-reference, manual-ai-automation), nested sub-categories via "parent", and all 37 chapters:

{
  "name": "Standalone Qwiki Manual",
  "slug": "manual",
  "docs_dir": "docs",
  "assets_dir": "docs/assets",
  "default_status": "published",
  "categories": [
    { "id": "manual-user-guide", "title": "User Guide" },
    {
      "id": "manual-user-authoring",
      "title": "Authoring & Content Formats",
      "parent": "manual-user-guide"
    }
  ],
  "documents": [
    {
      "file": "02-user-guide/authoring/01-markdown-and-editor.md",
      "category": "manual-user-authoring",
      "slug": "user-markdown-and-editor",
      "title": "Writing Markdown & Using the Inline Editor",
      "type": "markdown",
      "status": "published"
    }
  ]
}

Step-by-Step Workflow Commands

1. Scaffold cleanly:

   qwiki-builder init standalone-qwiki-user-manual --template blank --name "Standalone Qwiki Manual"

2. Validate before touching the server:

   qwiki-builder validate

   Verifies every file exists, slugs are unique, categories are declared, local screenshots/videos exist on disk, and Mermaid labels with parentheses are properly quoted.

3. Configure target sub-wiki credentials:

   qwiki-builder config --url https://home.qwiki.wiki/manual --key qwk_llm_your_token

4. Preview and publish:

   qwiki-builder publish --dry-run
   qwiki-builder publish

   During publish, qwiki-builder automatically:

   • Calls create_category (passing parentId for nested folders).
   • Uploads screenshots from docs/assets/images/ via upload_asset and rewrites relative Markdown paths (../assets/images/...) to live remote URLs.
   • Rewrites relative .md cross-links into canonical <category>/<slug> links.
   • Upserts every chapter in place (update_doc) while preserving slugs and share keys.

Ongoing Maintenance Commands