John Lancaster
161 lines
4.1 KiB
Markdown
161 lines
4.1 KiB
Markdown
# Static Docs Hosting Pattern
|
|
|
|
## Purpose
|
|
|
|
This document describes the completed layout and runtime pattern used to host a pre-built static documentation site from the same FastAPI app process that runs the FastMCP server.
|
|
|
|
This design intentionally avoids runtime docs rendering and avoids a separate docs hosting service.
|
|
|
|
It also treats Markdown as the single source of truth for both MCP resources and published docs.
|
|
|
|
## Completed-State Layout
|
|
|
|
```mermaid
|
|
---
|
|
config:
|
|
treeView:
|
|
rowIndent: 40
|
|
lineThickness: 2
|
|
themeVariables:
|
|
treeView:
|
|
labelColor: '#FFFFFF'
|
|
lineColor: '#FFFFFF'
|
|
---
|
|
treeView-beta
|
|
"project-root"
|
|
"pyproject.toml"
|
|
"uv.lock"
|
|
"zensical.toml"
|
|
"docs"
|
|
"index.md"
|
|
"architecture.md"
|
|
"mcp_layout.md"
|
|
"site"
|
|
"static build output"
|
|
"skills"
|
|
"pytest-scaffolding"
|
|
"SKILL.md"
|
|
"references"
|
|
"python-logging-dictconfig"
|
|
"SKILL.md"
|
|
"references"
|
|
"fastapi-uv-docker"
|
|
"SKILL.md"
|
|
"references"
|
|
"src"
|
|
"personal_mcp"
|
|
"main.py"
|
|
"web"
|
|
"app.py"
|
|
"docs_mount.py"
|
|
"catalog"
|
|
"server.py"
|
|
"skills"
|
|
"pytest_scaffolding"
|
|
"python_logging_dictconfig"
|
|
"fastapi_uv_docker"
|
|
```
|
|
|
|
Notes:
|
|
|
|
1. docs contains project-authored pages.
|
|
2. site contains static build output only.
|
|
3. skills contains canonical skill Markdown and reference Markdown.
|
|
4. MCP resources and docs site read from the same Markdown sources.
|
|
|
|
## Runtime Composition
|
|
|
|
The runtime process serves two surfaces:
|
|
|
|
1. MCP protocol surface from FastMCP
|
|
2. Static docs surface from FastAPI static mount
|
|
|
|
```mermaid
|
|
flowchart TD
|
|
A[FastMCP Root Server] --> B[MCP Transport]
|
|
A --> C[FastAPI Application]
|
|
C --> D[Static Mount /docs]
|
|
D --> E[Zensical site output directory]
|
|
```
|
|
|
|
## Build and Publish Flow
|
|
|
|
The docs flow is pre-build only.
|
|
|
|
1. Read authored docs pages and skill markdown sources.
|
|
2. Build static site with Zensical into site.
|
|
3. Start app and serve site directory as static files.
|
|
|
|
No runtime markdown conversion is required.
|
|
|
|
## Content Merge Pattern
|
|
|
|
The published docs site always contains both:
|
|
|
|
1. Project-authored docs pages
|
|
2. Skill Markdown content from skills/*/SKILL.md and references
|
|
|
|
This ensures the public docs reflect architectural guidance and the exact Markdown served by MCP.
|
|
|
|
## Markdown-to-Resource Mapping
|
|
|
|
MCP resources map directly to canonical Markdown documents.
|
|
|
|
Example mapping model:
|
|
|
|
1. skills/<slug>/SKILL.md -> resource://skills/<id>/document
|
|
2. skills/<slug>/references/*.md -> referenced sections or linked companion documents
|
|
|
|
Catalog resources provide discovery metadata and stable identifiers.
|
|
|
|
## Why This Pattern
|
|
|
|
### Operational Simplicity
|
|
|
|
One application process serves both protocol and static docs surfaces.
|
|
|
|
### Deterministic Docs
|
|
|
|
Published docs are immutable static assets for a given build.
|
|
|
|
### Documentation Fidelity
|
|
|
|
The docs site and MCP resources resolve from the same Markdown sources.
|
|
|
|
### Maintainer Experience
|
|
|
|
Authors continue to work in markdown while resource contracts remain machine-consumable.
|
|
|
|
## FastAPI Static Mount Expectations
|
|
|
|
The FastAPI app is expected to:
|
|
|
|
1. Mount static directory containing Zensical output.
|
|
2. Serve index and asset files from that directory.
|
|
3. Keep docs route stable across releases.
|
|
|
|
Recommended route conventions:
|
|
|
|
1. /docs for static site root
|
|
2. /docs/* for static assets and page routes
|
|
|
|
## Update Lifecycle
|
|
|
|
For each documentation update:
|
|
|
|
1. Edit authored docs and skill markdown content.
|
|
2. Rebuild static site.
|
|
3. Restart runtime if needed.
|
|
|
|
This keeps docs publication explicit and predictable.
|
|
|
|
## Example Source Material
|
|
|
|
Existing reference docs remain valid content inputs in this pattern:
|
|
|
|
1. ../skills/pytest-scaffolding/references/pytest-docs.md
|
|
2. ../skills/python-logging-dictconfig/references/python-logging-docs.md
|
|
3. ../skills/fastapi-uv-docker/references/fastapi-best-practices.md
|
|
|
|
These are source documents, not deployment artifacts.
|