Skip to content

title: Docs Maintenance

Docs Maintenance

How to preview, update, and publish this manual.

Preview locally (Windows)

  1. Install Python 3 (if not installed).
  2. Install MkDocs and Material:
    • pip install mkdocs mkdocs-material
  3. Start the local server:
    • mkdocs serve
  4. Open the URL shown in the terminal (usually http://127.0.0.1:8000).

Editing tips

  • Keep pages task-focused and concise.
  • Use admonitions:
    • Note, Tip, Warning, Info
  • Prefer headings that match UI labels.
  • Add screenshots under docs/assets/images/ and reference them with relative paths.
  • All pages must be listed under the nav tree in mkdocs.yml.

  • Indentation is critical. Use 2 spaces per level. Example:

    nav:

    • Programs:
      • Overview: programs/index.md
      • Dashboard: programs/dashboard.md
      • Development: programs/development.md
      • Implementation:
        • Overview: programs/implementation/index.md
        • Details (Lifecycle): programs/implementation/details.md
        • Initiation: programs/implementation/initiation.md
        • Planning: programs/implementation/planning.md
        • Activities: programs/implementation/activities.md
        • Progress: programs/implementation/progress.md
        • Indicators: programs/implementation/indicators.md
        • Execution: programs/implementation/execution.md
        • Progress Reports: programs/implementation/progress-reports.md
        • Gantt Chart: programs/implementation/gantt-chart.md

  • Common YAML errors and fixes:

    • mapping values are not allowed here → A line is mis-indented or mixed tabs/spaces. Ensure 2-space indentation only.
    • expected , but found '-' → A list item is placed where a map value is expected; align it under the correct parent.
  • Place images under docs/assets/...; prefer docs/assets/programs for Programs screenshots and docs/assets/images for general images.
  • Use relative links that end with index.md for section overviews. Examples:
    • logistics/fleet/index.md (not just logistics/fleet/)
    • ../inventory/index.md (not ../inventory/)
  • If you see warnings like “target ... not found among documentation files,” either fix the path or add the missing image.

Build and validation

Quick build

  • mkdocs build
    • Builds static site into site/. Fix any YAML errors first.

Live preview

  • mkdocs serve
    • Auto-reloads on save. Use this while editing.
  • Watch the terminal output for unrecognized links suggestions like “Did you mean '.../index.md'?” and update the docs accordingly.

Optional: PDF export

  • We can add mkdocs-with-pdf and a one-liner to build a single PDF manual if needed.