john/prompts
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs

Browse Source
This commit is contained in:
John Lancaster
2026-06-18 20:29:52 -05:00
parent c915c1846d
commit d1c80d4737
2 changed files with 45 additions and 51 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/mcp_layout.md
+30 -26
View File
@@ -6,6 +6,8 @@ This document describes the completed layout and runtime pattern used to host a
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
```text
@@ -19,16 +21,21 @@ project-root/
| |- index.md
| |- architecture.md
| |- mcp_layout.md
| |- generated/
| |- patterns/
| |- index.md
| |- pytest-scaffolding.md
| |- python-logging-dictconfig.md
| |- fastapi-uv-docker.md
|
|- site/
| |- ... static files built by zensical ...
|
|- skills/
| |- pytest-scaffolding/
| | |- SKILL.md
| | |- references/
| |- python-logging-dictconfig/
| | |- SKILL.md
| | |- references/
| |- fastapi-uv-docker/
| |- SKILL.md
| |- references/
|
|- src/
|- personal_mcp/
|- main.py
@@ -45,9 +52,10 @@ project-root/
Notes:
1. docs contains authored pages and generated markdown pages.
1. docs contains project-authored pages.
2. site contains static build output only.
3. MCP resources and docs generation share the same content contract.
3. skills contains canonical skill Markdown and reference Markdown.
4. MCP resources and docs site read from the same Markdown sources.
## Runtime Composition
@@ -68,10 +76,9 @@ flowchart TD
The docs flow is pre-build only.
1. Read module resources and catalog metadata.
2. Generate docs markdown pages into docs/generated.
3. Build static site with Zensical into site.
4. Start app and serve site directory as static files.
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.
@@ -80,22 +87,20 @@ No runtime markdown conversion is required.
The published docs site always contains both:
1. Project-authored docs pages
2. Resource-derived pattern pages
2. Skill Markdown content from skills/*/SKILL.md and references
This ensures the public docs reflect both architectural guidance and live pattern knowledge.
This ensures the public docs reflect architectural guidance and the exact Markdown served by MCP.
## Resource-to-Docs Mapping
## Markdown-to-Resource Mapping
Pattern resources map directly to docs sections.
MCP resources map directly to canonical Markdown documents.
Example mapping model:
1. resource://skills/<id>/overview -> docs/generated/patterns/<id>.md section Overview
2. resource://skills/<id>/rules -> docs/generated/patterns/<id>.md section Rules
3. resource://skills/<id>/checklist -> docs/generated/patterns/<id>.md section Checklist
4. resource://skills/<id>/references -> docs/generated/patterns/<id>.md section References
1. skills/<slug>/SKILL.md -> resource://skills/<id>/document
2. skills/<slug>/references/*.md -> referenced sections or linked companion documents
Catalog resources generate index pages and navigation pages.
Catalog resources provide discovery metadata and stable identifiers.
## Why This Pattern
@@ -109,7 +114,7 @@ Published docs are immutable static assets for a given build.
### Documentation Fidelity
Resource-derived pages align docs with the exact methodology contracts exposed to agents.
The docs site and MCP resources resolve from the same Markdown sources.
### Maintainer Experience
@@ -132,10 +137,9 @@ Recommended route conventions:
For each documentation update:
1. Edit authored markdown and resource content.
2. Regenerate docs markdown from resources.
3. Rebuild static site.
4. Restart runtime if needed.
1. Edit authored docs and skill markdown content.
2. Rebuild static site.
3. Restart runtime if needed.
This keeps docs publication explicit and predictable.