Handbook

Documentation authoring

Updated

  • Source: narrative docs live in this repository under docs/; the static site is built from forge-lcdl-website (submodule + generator/build-site.py). See Website publishing.
  • Frontmatter: use title, description, optional audience, learning_level, handbook_area, status, nav_order, tags, hide_from_nav.
  • layout_type: declare one of landing, hub, tutorial, howto, reference, enterprise, or concept (see Documentation design system). Use longform_ok: true plus longform_reason: only when a page must exceed the usual word budget.
  • Bulk helper: python3 scripts/ensure_handbook_frontmatter.py --apply fills missing title/description on nested IA pages (review generated YAML).
  • Strict audit: python3 scripts/audit_docs_site.py --strict requires title + description on handbook paths (see script’s _needs_frontmatter logic).
  • UX warnings (non-fatal): python3 scripts/audit_docs_site.py --ux-warnings prints layout/table/word-count hints (see docs/design/lcdl-page-layout-taxonomy.md).
  • Diagrams: do not add Mermaid to handbook-bound pages (workspace policy). For Kitchen Sink tiles use fenced ```blueprint-diagram (see Kitchen Sink README — blueprint diagram fences); key: must match catalog types (linear, swimlane, …). Keep an ASCII or text fallback where needed.
  • Links: use relative links between docs; after moves, run python3 scripts/fix_docs_internal_links.py to normalize legacy docs/FOO.md hrefs when needed.
  • Task catalog draft: python3 scripts/generate_task_catalog_md.py --write docs/reference/task-catalog.generated.md refreshes the generated table; python3 scripts/generate_task_catalog_md.py --check fails CI when the committed file is stale.
  • Quality gates: python3 scripts/audit_contract_docs.py --strict --strict-md (JSON sidecars + contract Markdown heuristic for all catalog tasks). python3 scripts/audit_docs_site.py checks handbook relative links; --strict also enforces frontmatter on nested IA pages—expect failures until legacy stubs are migrated. Optional --strict-md-only id1,id2 targets a subset when triaging.