Skip to content

forge Documentation Site — Design Spec

Date: 2026-03-16 Status: Approved Goal: Replace the stagnant hdoc-based API docs with a modern Doxide + MkDocs Material documentation site that serves as the project website.

Toolchain

  • Doxide (v0.9.x) — Parses C++ source via Tree-sitter, generates Markdown pages per namespace/class. No Doxygen, no compilation database required.
  • MkDocs + Material for MkDocs — Static site generator with the Material theme. Produces attractive, responsive docs with dark/light mode, search, and navigation tabs.
  • Build command: doxide build && mkdocs build
  • Dev server: doxide build && mkdocs serve

Top-level tabs (Crow-style):

Home  |  Getting Started  |  Guides  |  API Reference

Home (Custom Hero Page)

Custom landing page via docs/overrides/home.html (extends main.html):

  • forge-studio logo (blue-gold gradient square with brain hemisphere)
  • Tagline: "Fast, Optimized Reconstruction via Gridding Engine"
  • Feature cards:
  • NUFFT Gridding (Kaiser-Bessel gridding with LUT)
  • Metal & CUDA GPU Acceleration
  • SENSE / pcSENSE Multi-coil Reconstruction
  • forgeview TUI Monitoring
  • Quick install code snippet (CMake)
  • Link to FORGE Studio (when available)
  • GitHub link

Getting Started

Page Content Source
installation.md README.md — platform requirements, dependencies
building.md README.md — CMake commands for macOS, Linux NVIDIA, Linux CPU, Docker
first-reconstruction.md README.md — CLI usage examples (forgeSense, forgePcSense, forgeview piping)

Guides

Page Content Source
operators-and-solvers.md docs/pages/index.md + CLAUDE.md operator tables — operator conventions, class index (including pcSENSE, pcSenseTimeSeg, TimeSegmentation), solver overview. Note: docs/pages/index.md is incomplete — CLAUDE.md is the authoritative operator list.
forge-types.md docs/pgcol-pgmat-guide.md — forgeCol/forgeMat developer guide
metal-backend.md docs/metal-backend.md — Metal GPU backend architecture
forgeview.md README.md + CLAUDE.md — JSONL protocol, TUI features, CLI flags
mpi.md README.md — MPI distributed reconstruction

Note: first-reconstruction.md should also cover NIfTI orientation metadata (--voxel-size, --no-orient flags) from README.md.

API Reference

Doxide-generated Markdown pages integrated directly into MkDocs:

  • One page per namespace
  • One page per class/struct
  • Functions and variables on their parent's page
  • Searchable via MkDocs built-in search
  • Same sidebar navigation as the rest of the site

Color Scheme

Custom Material theme palette derived from the forge-studio logo (#3B82F6 blue, #D4A843 gold):

Role Light Mode Dark Mode
Primary (nav, links) #3B82F6 #60a5fa
Background #f8fafc #0f172a
Surface/cards #ffffff #1e293b
Text primary #1e293b #e2e8f0
Text secondary #64748b #94a3b8
Header accent bar gradient #3B82F6 → #D4A843 gradient #60a5fa → #e8c05a

Implemented by using Material's built-in default and slate schemes with CSS custom property overrides (--md-primary-fg-color, --md-accent-fg-color, etc.) in docs/stylesheets/extra.css. The gradient header accent bar requires a custom CSS rule targeting .md-header or .md-tabs. Auto-switching based on prefers-color-scheme with a manual sun/moon toggle.

File Layout

forge/
├── doxide.yaml                        # Doxide config
├── mkdocs.yml                         # MkDocs Material config
├── docs/
│   ├── overrides/
│   │   └── home.html                  # Custom hero landing page
│   ├── stylesheets/
│   │   └── extra.css                  # Custom color schemes, gradient accent
│   ├── assets/
│   │   └── logo.svg                   # forge-studio logo
│   ├── index.md                       # Minimal — triggers home.html override
│   ├── getting-started/
│   │   ├── installation.md
│   │   ├── building.md
│   │   └── first-reconstruction.md
│   └── guides/
│       ├── operators-and-solvers.md
│       ├── forge-types.md
│       ├── metal-backend.md
│       ├── forgeview.md
│       └── mpi.md

Doxide generates API reference Markdown into docs/api/ at build time. Generated files are .gitignore'd (build artifacts, not committed). A hand-authored docs/api/index.md stub is committed as a fallback landing page for the API Reference tab in case Doxide doesn't generate one.

Doxide Configuration (doxide.yaml)

title: forge
description: Fast, Optimized Reconstruction via Gridding Engine
output: docs/api

files:
  - "forge/**/*.hpp"
  - "forge/**/*.h"
  - "forge/**/*.cpp"

exclude:
  - "forge/Tests/"
  - "forge/Tutorials/"
  - "forge/Microbenchmarks/"
  - "Support/"

MkDocs Configuration (mkdocs.yml)

site_name: forge
site_url: https://mechneurolab.github.io/forge/
repo_name: mechneurolab/forge
repo_url: https://github.com/mechneurolab/forge

theme:
  name: material
  custom_dir: docs/overrides
  logo: assets/logo.svg
  favicon: assets/logo.svg
  icon:
    repo: fontawesome/brands/square-github
  features:
    - navigation.tabs
    - navigation.sections
    - navigation.top
    - content.code.copy
    - content.code.annotate
  palette:
    - media: "(prefers-color-scheme: light)"
      scheme: default
      toggle:
        icon: fontawesome/solid/sun
        name: Switch to dark mode
    - media: "(prefers-color-scheme: dark)"
      scheme: slate
      toggle:
        icon: fontawesome/solid/moon
        name: Switch to light mode

nav:
  - Home: index.md
  - Getting Started:
    - Installation: getting-started/installation.md
    - Building from Source: getting-started/building.md
    - Your First Reconstruction: getting-started/first-reconstruction.md
  - Guides:
    - Operators & Solvers: guides/operators-and-solvers.md
    - forge Types (forgeCol/forgeMat): guides/forge-types.md
    - Metal GPU Backend: guides/metal-backend.md
    - forgeview TUI: guides/forgeview.md
    - MPI Distributed Reconstruction: guides/mpi.md
  - API Reference: api/

markdown_extensions:
  - toc:
      permalink: true
  - admonition
  - pymdownx.details
  - pymdownx.highlight
  - pymdownx.superfences
  - pymdownx.tabbed:
      alternate_style: true
  - pymdownx.inlinehilite
  - attr_list
  - pymdownx.emoji:
      emoji_index: !!python/name:material.extensions.emoji.twemoji
      emoji_generator: !!python/name:material.extensions.emoji.to_svg

extra_css:
  - stylesheets/extra.css

plugins:
  - search

Home Page Override

docs/index.md uses front-matter to hide nav/toc for the hero layout:

---
template: home.html
hide:
  - navigation
  - toc
---

docs/overrides/home.html extends main.html, overrides {% block content %} with the hero layout (logo, tagline, feature cards grid, install snippet, CTA buttons).

Copy logo.svg from /Users/acerjanic/Developer/forge-studio/resources/logo.svg to docs/assets/logo.svg. The SVG is used directly (no PNG conversion needed).

Material Theme Features

From mkdocs.yml:

  • navigation.tabs — top-level tab bar
  • navigation.sections — sidebar sections with headers
  • navigation.top — back-to-top button
  • content.code.copy — copy button on code blocks
  • content.code.annotate — inline code annotations
  • Search plugin (built-in)
  • Dark/light toggle with prefers-color-scheme auto-detection

Markdown Extensions

  • admonition + pymdownx.details — collapsible note/warning/tip boxes
  • pymdownx.highlight + pymdownx.superfences — syntax highlighting with fenced blocks
  • pymdownx.tabbed — tabbed content (e.g., macOS vs Linux install)
  • toc with permalink anchors
  • attr_list — HTML attributes on Markdown elements
  • pymdownx.emoji — icon support

Files to Remove

File Reason
.hdoc.toml Replaced by doxide.yaml
scripts/generate-docs.sh Replaced by doxide build && mkdocs build
docker/forge-hdoc/Dockerfile No longer needed — Doxide has no LLVM/Clang dependency

Dependencies to Install

Tool Install
Doxide brew install doxide (macOS) or download binary
MkDocs pip install mkdocs
Material for MkDocs pip install mkdocs-material

A docs/requirements.txt pins the Python dependencies:

mkdocs>=1.6
mkdocs-material>=9.5

.gitignore Additions

# Doxide-generated API reference (build artifact)
docs/api/

Out of Scope

  • Version selector (mike) — can add later
  • CI/CD deployment (GitHub Pages) — can add later
  • Custom search ranking
  • Blog section