Forge Content System
Reference for the documentation site’s content system: page generation, content inclusion, writing conventions, and key files.
Project Page Generation
A TypeScript generator (Forge/Skills/Manage_Pages/generate_view_pages.ts) runs before every Astro build. It reads config from Forge/Skills/Manage_Pages/view_folder_config.json and produces:
| Category | What it generates | Committed? |
|---|---|---|
| File-view pages | Readable Markdown pages for non-Markdown source files (.ts, .json, .py, etc.) | No (gitignored) |
| MEDIA.md pages | Gallery pages for folders containing images | Yes |
The generator is driven by a project holder folder model: any immediate subdirectory of a project holder folder is treated as a project and gets a README.md and AGENTS.md. Current holders: */Projects and */Skills.
Supported file types for file-view pages
.ts, .tsx, .js, .jsx, .json, .yaml, .yml, .py, .sh, .sql, .txt, .csv, .css, .html
Files exceeding 500 lines are truncated with a GitHub source link.
File-view page structure
Each auto-generated file-view page contains:
- File name as the page title
- Full repository path to the file
- File type or extension
- Link to the project README (labeled “Parent folder”)
- Link to edit or view the source file in GitHub
- Full file contents in a syntax-highlighted code block (truncated if too large)
- An indicator that the page is auto-generated from the source file
MEDIA.md structure
Each auto-generated MEDIA.md page for an image-containing folder contains:
- Folder name as the page title
- Full repository path to the folder
- Link to the project README (labeled “Parent folder”)
- Preview for each image
- Download link for each image
Link behavior
Every clickable file entry in a project README resolves to one of:
| Target type | Resolves to |
|---|---|
Markdown page (.md) | The original rendered page |
| Supported non-Markdown file | Auto-generated file-view page (.view.md) |
| Image-containing folder | Generated MEDIA.md page |
SKILL.md
SKILL.md files are included directly as regular content pages with combined frontmatter (both Agent Skills name/description and Starlight title/visibility/status/owner). No special exclusion or .generated/ wrappers needed.
Content Inclusion
Controlled by glob patterns in .internal/src/content.config.ts:
Pattern: **/*.md (all markdown) + !.internal/** (exclude internal) + .generated/**/*.view.md (re-include file-view wrappers for non-.md files)
All markdown files are included directly. No per-department or per-directory special-casing. Non-Markdown files are displayed via auto-generated file-view pages in .generated/.
Writing Conventions
Markdown features
Standard markdown plus: Mermaid diagrams (```mermaid blocks), Asides (:::note, :::tip, :::caution, :::danger), Tabs (Starlight <Tabs>/<TabItem>, requires MDX), Code blocks (Expressive Code with file names, line highlighting, diff markers).
Typography
Curly quotes (“ ” and ‘ ’), curly apostrophes (’), em dashes to add emphasis to parenthetical information (—) and en dashes (–) to mean “to”, for example 9–5.
Internal links
Use relative file-path links with the .md extension, or absolute paths. The Remark plugin remark-resolve-relative-links rewrites them to Starlight route URLs at build time.
You must include the .md extension — the plugin only processes links matching \.mdx?. Links without it (e.g. ./other-page) won’t be transformed and will break.
| Style | Syntax | Example |
|---|---|---|
| Same folder | ./Sibling_Page.md | [Spec](./Taxonomy_Spec.md) |
| Parent folder | ../Sibling.md | [README](../README.md) |
| Deeper path | ../../Other/Dir/File.md | [Setup](../../Knowledge/Setup.md) |
| Absolute | /forge/taxonomy/taxonomy_spec/ | [Spec](/forge/taxonomy/taxonomy_spec/) |
| With anchor | ./File.md#section | [Plan](./Taxonomy_Plan.md#phase-2) |
Internal links populate the Site Graph widget.
Revision hygiene
When a concept is removed (not just modified), sweep ALL outputs for remnants. Common remnants: (1) “Do NOT do X” warnings the system wouldn’t need — reveals the old assumption lingers. (2) References to data/inputs the recipient can’t access. (3) Placeholders tied to the removed concept. Test: read the output as if the wrong version never existed.
Links must be clickable
Always format URLs as markdown links — text — never bare URLs in backticks/code blocks (not clickable).
Paste content in code blocks
Present paste-into-conversation content in fenced code blocks — never blockquotes (no copy button). Use txt as language hint for plain-text.
Key Files
| File | Purpose |
|---|---|
.internal/astro.config.mjs | Sidebar, plugins, site metadata |
.internal/src/content.config.ts | Glob patterns, .generated/ handling, slug transform |
.internal/src/styles/custom.css | Theme colors, fonts |
Forge/Skills/Manage_Pages/view_folder_config.json | Generator config |
Forge/Skills/Manage_Pages/generate_view_pages.ts | Generator script |
.gitignore | Includes .generated/ exclusion |