Updating the Documentation

This guide explains how to serve, build, and extend the Knowledge Platform documentation using MkDocs with Mermaid-enabled fenced code blocks.

Prerequisites

The documentation tools are included in the dev optional dependencies. Install them with:

# From the project root
pip install -e ".[dev]"

This installs mkdocs, mkdocstrings[python], and pymdown-extensions (required for Mermaid diagram rendering).

Verify the installation:

mkdocs --version
# MkDocs, version 1.x.x

Directory Structure

mkdocs.yml lives at the project root. All mkdocs commands are run from there. The Markdown source files live under docs/.

knowledge-platform/         ← project root (run all mkdocs commands here)
├── mkdocs.yml              ← site configuration and navigation
├── DESIGN.md               ← architecture notes (not in MkDocs nav; view on GitHub)
├── src/                    ← Python source (mkdocstrings reads from here)
├── site/                   ← built output (git-ignored)
└── docs/                   ← docs_dir: all Markdown source
    ├── index.md            ← home page
├── guides/
│   ├── user-guide.md
│   ├── outline-module.md
│   ├── use-cases.md
│   └── working-with-mkdocs.md   ← you are here
├── development/
│   └── module-development.md
└── api/
    ├── core.md
    ├── domain.md
    ├── persistence.md
    ├── services.md
    ├── workspace.md
    ├── core/
    │   ├── identifiers.md
    │   ├── node.md
    │   ├── edge.md
    │   ├── graph.md
    │   ├── transaction.md
    │   └── engine.md
    ├── domain/
    │   ├── graph_type.md
    │   └── registry.md
    ├── services/
    │   ├── interfaces.md
    │   ├── graph_service.md
    │   └── workspace_service.md
    ├── persistence/
    │   └── store.md
    ├── modules/
    │   ├── base.md
    │   ├── registry.md
    │   └── outline.md
    └── ui/
        ├── events.md
        └── app.md

The site/ directory (built output) is in .gitignore — never commit it.

Serving the Docs Locally

To preview the documentation with live-reload:

# From the project root
mkdocs serve

Open your browser at http://127.0.0.1:8000. The site reloads automatically when you save any .md file or the mkdocs.yml.

Building the Static Site

To produce the full static site in site/:

mkdocs build

# With strict mode (fails on warnings — recommended for CI)
mkdocs build --strict

The output directory (site/) can be deployed to any static hosting service: GitHub Pages, Netlify, S3, etc.

Editing the Navigation

The navigation tree is defined in the nav: section of mkdocs.yml. Each entry is Display Name: path/to/file.md relative to docs/:

nav:
  - Home: index.md
  - User Guides:
    - Working with Graphs: guides/user-guide.md
    - Outline Module: guides/outline-module.md

To add a new page:

  1. Create the Markdown file under docs/.
  2. Add an entry to the nav: section.
  3. Save mkdocs.yml — the dev server reloads automatically.

Adding a New Documentation Page

1. Create the file

touch docs/guides/my-new-guide.md

2. Write the content

# My New Guide

Introduction paragraph...

## Section One

Content here.

3. Register in nav

# mkdocs.yml
nav:
  - User Guides:
    - Working with Graphs: guides/user-guide.md
    - My New Guide: guides/my-new-guide.md   # ← add this line

Writing API Reference Pages with mkdocstrings

The mkdocstrings plugin renders Python docstrings directly into the documentation. Use the ::: directive:

## MyClass

::: knowledge_platform.some.module.MyClass
    options:
      heading_level: 3
      show_source: true

This pulls the class's docstring, all its method signatures, and their docstrings into the page.

Available Options

Option Default Description
heading_level 2 HTML heading level for the class name
show_source true Show "Source" link/expand button
show_root_heading true Show the class/function name as a heading
show_signature_annotations true Include type annotations in signatures
separate_signature true Put signature on its own line

Documenting a Function

::: knowledge_platform.core.transaction.transaction
    options:
      heading_level: 3

Documenting an Entire Module

::: knowledge_platform.core.identifiers
    options:
      heading_level: 3

Using Mermaid Diagrams

The configuration includes pymdownx.superfences for fenced code blocks. Mermaid diagrams are written as fenced code blocks with the mermaid language tag:

```mermaid
graph LR
    A --> B --> C
```

Enabling Rendered Mermaid Diagrams

Rendered Mermaid diagrams are already enabled in the root mkdocs.yml with pymdownx.superfences plus a small JavaScript bootstrap loaded by the site theme.

The relevant configuration looks like this:

markdown_extensions:
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format
extra_javascript:
  - https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.min.js
  - javascripts/mermaid.js

YAML language server

The !!python/name: tag causes a false-positive error in some YAML language servers (e.g. the VS Code YAML extension). The configuration is valid for MkDocs — you can safely ignore the warning or disable YAML validation for mkdocs.yml.

Diagram Types Reference

Diagram Keyword Use for
Flowchart graph TD or graph LR Architecture, data flow
Sequence sequenceDiagram Interaction between components
Class classDiagram Object model, inheritance
State stateDiagram-v2 Lifecycle, state machines
ER erDiagram Database schema
Gantt gantt Roadmaps, timelines

Example sequence diagram:

```mermaid
sequenceDiagram
    participant UI
    participant Service
    participant Engine
    UI->>Service: add_node(graph_id, type, attrs)
    Service->>Engine: add_node(node)
    Engine-->>Service: OK
    Service-->>UI: node
```

Admonitions

Use admonitions to highlight important information:

!!! note "Optional title"
    This is a note.

!!! warning
    This is a warning.

!!! danger "Critical"
    This is dangerous.

??? tip "Click to expand"
    This content is collapsed by default.

Types: note, tip, info, warning, danger, success, question, failure, bug, example, quote.

Code Blocks

Use language tags for syntax highlighting:

```python
from knowledge_platform.core.node import Node
node = Node.create(graph_id, "OutlineItem", {"title": "Hello"})
```

```bash
pytest tests/unit --no-cov
```

```yaml
nav:
  - Home: index.md
```

Deploying to GitHub Pages

mkdocs gh-deploy

This builds the site and pushes it to the gh-pages branch of the repository. Configure GitHub Pages to serve from that branch in your repository settings.

Configuration Reference (mkdocs.yml)

Key Description
site_name Title shown in the browser tab and header
docs_dir Root directory for Markdown source files
site_dir Output directory for the built site
theme.name Currently mkdocs (built-in MkDocs theme)
plugins search (built-in) + mkdocstrings
nav The navigation tree
markdown_extensions PyMdown extensions for enhanced Markdown

The full configuration lives in the repository root at mkdocs.yml.