mdBook Integration

Loading…

mdBook Integration

Relevant source files

• README.md
• scripts/build-docs.sh

Purpose and Scope

This page documents how the system integrates with mdBook and mdbook-mermaid to generate the final HTML documentation. It covers the configuration generation process, automatic table of contents creation, mermaid diagram support installation, and the build execution. For information about the overall three-phase pipeline, see Three-Phase Pipeline. For template injection specifics, see Template Injection.

mdBook and mdbook-mermaid Tools

The system uses two Rust-based tools compiled during the Docker build:

Both tools are compiled from source in the Rust builder stage of the Docker image and copied to the final Python-based runtime container for size optimization.

mdBook Build Pipeline

graph TB
    subgraph "Input_Preparation"
        WikiDir["/workspace/wiki/\nEnhanced markdown files"]
Templates["Processed templates\nHEADER_HTML, FOOTER_HTML"]
end
    
    subgraph "Configuration_Generation"
        BookToml["book.toml generation\n[scripts/build-docs.sh:102-119]"]
SummaryGen["SUMMARY.md generation\n[scripts/build-docs.sh:124-186]"]
EnvVars["Environment variables:\nBOOK_TITLE, BOOK_AUTHORS\nGIT_REPO_URL"]
end
    
    subgraph "Structure_Creation"
        BookDir["/workspace/book/\nmdBook project root"]
SrcDir["/workspace/book/src/\nMarkdown source"]
CopyFiles["Copy wiki files to src/\n[scripts/build-docs.sh:237]"]
InjectTemplates["Inject header/footer\n[scripts/build-docs.sh:239-261]"]
end
    
    subgraph "mdBook_Processing"
        MermaidInstall["mdbook-mermaid install\n[scripts/build-docs.sh:266]"]
MdBookBuild["mdbook build\n[scripts/build-docs.sh:271]"]
Preprocessor["mdbook-mermaid preprocessor\nConverts ```mermaid blocks"]
end
    
    subgraph "Output"
        BookHTML["/workspace/book/book/\nBuilt HTML documentation"]
OutputCopy["Copy to /output/book/\n[scripts/build-docs.sh:279]"]
end
    
 
   EnvVars --> BookToml
 
   EnvVars --> SummaryGen
 
   WikiDir --> CopyFiles
 
   Templates --> InjectTemplates
    
 
   BookToml --> BookDir
 
   SummaryGen --> SrcDir
 
   CopyFiles --> SrcDir
 
   InjectTemplates --> SrcDir
    
 
   BookDir --> MermaidInstall
 
   MermaidInstall --> MdBookBuild
 
   SrcDir --> MdBookBuild
 
   MdBookBuild --> Preprocessor
 
   Preprocessor --> BookHTML
 
   BookHTML --> OutputCopy

Sources: scripts/build-docs.sh:95-295

Configuration Generation (book.toml)

The book.toml configuration file is dynamically generated at scripts/build-docs.sh:102-119 using environment variables.

book.toml Structure

Sources: scripts/build-docs.sh:102-119

Configuration Sections

The git-repository-url setting automatically adds an “Edit on GitHub” button to the top-right of each page, pointing to the repository specified in $GIT_REPO_URL (defaults to https://github.com/$REPO).

Sources: scripts/build-docs.sh:102-119

SUMMARY.md Generation

The table of contents is automatically generated by analyzing the file structure in /workspace/wiki/. The algorithm at scripts/build-docs.sh:124-186 creates a hierarchical navigation structure.

SUMMARY.md Generation Algorithm

graph TB
    subgraph "File_Discovery"
        WikiDir["/workspace/wiki/"]
ListFiles["ls *.md\n[scripts/build-docs.sh:135]"]
FilterNumeric["grep -E '^[0-9]'\n[scripts/build-docs.sh:150]"]
NumericSort["sort -t- -k1 -n\n[scripts/build-docs.sh:151]"]
end
    
    subgraph "Overview_Detection"
        OverviewFile["Find non-numeric file\n[scripts/build-docs.sh:138]"]
ExtractTitle["head -1 /sed 's/^# //' [scripts/build-docs.sh:140]"]
WriteOverview["Write [Title] filename [scripts/build-docs.sh:141]"]
end subgraph "Main_Page_Processing" IteratePages["Iterate main pages [scripts/build-docs.sh:158-185]"]
ExtractPageTitle["Extract '# Title' from file [scripts/build-docs.sh:163]"]
CheckSubsections["Check section-N directory [scripts/build-docs.sh:166-169]"]
end subgraph "Subsection_Handling" ListSubsections["ls section-N/*.md [scripts/build-docs.sh:174]"]
SortSubsections["sort -t- -k1 -n [scripts/build-docs.sh:174]"]
ExtractSubTitle["Extract '# Title' from subfile [scripts/build-docs.sh:178]"]
WriteSubsection["Write ' - [Title] section-N/file ' [scripts/build-docs.sh:179]"]
end subgraph "Output" SummaryMd["/workspace/book/src/SUMMARY.md"]
end
 WikiDir --> ListFiles
 ListFiles --> OverviewFile
 OverviewFile --> ExtractTitle
 ExtractTitle --> WriteOverview
 ListFiles --> FilterNumeric
 FilterNumeric --> NumericSort
 NumericSort --> IteratePages
 IteratePages --> ExtractPageTitle
 ExtractPageTitle --> CheckSubsections
 CheckSubsections -->|Has subsections|ListSubsections
 ListSubsections --> SortSubsections
 SortSubsections --> ExtractSubTitle
 ExtractSubTitle --> WriteSubsection
 CheckSubsections -->|No subsections| WriteStandalone["Write '- [Title](file)'"]
WriteOverview --> SummaryMd
 
   WriteSubsection --> SummaryMd
 
   WriteStandalone --> SummaryMd

Sources: scripts/build-docs.sh:124-186

SUMMARY.md Structure

The generated SUMMARY.md follows this format:

Generation Logic

1. Overview Detection scripts/build-docs.sh:136-144: Finds the first non-numeric markdown file and writes it as the top-level overview link.

2. Main Page Sorting scripts/build-docs.sh:147-155: Extracts numeric prefixes (e.g., 1, 2, 10) and sorts numerically using sort -t- -k1 -n, ensuring 10-file.md comes after 2-file.md.

3. Subsection Detection scripts/build-docs.sh:166-180: For each main page with numeric prefix N, checks if directory section-N/ exists. If found, lists and sorts subsection files, writing them indented with two spaces.

4. Title Extraction scripts/build-docs.sh:163-178: Reads the first line of each markdown file and removes the # prefix using sed 's/^# //'.

Sources: scripts/build-docs.sh:124-186

mdbook-mermaid Installation

Before building the book, the mermaid preprocessor assets must be installed. This is performed by mdbook-mermaid install at scripts/build-docs.sh266

mdbook-mermaid Installation Process

Sources: scripts/build-docs.sh:263-266

The mdbook-mermaid install command:

1. Downloads the mermaid.js library (version compatible with Mermaid 11)
2. Creates initialization scripts to configure mermaid rendering
3. Adds CSS stylesheets for diagram theming
4. Modifies the HTML templates to include the necessary <script> tags

During the subsequent mdbook build, the mermaid preprocessor:

1. Detects code blocks with ````mermaid` fence
2. Wraps them in <pre class="mermaid"> tags
3. Leaves the mermaid syntax intact for client-side rendering

Sources: scripts/build-docs.sh:263-271

Build Execution

The actual mdBook build occurs at scripts/build-docs.sh271 with a simple mdbook build command.

mdBook Build Process

Sources: scripts/build-docs.sh:268-271

Build Steps

1. Configuration Parsing : mdBook reads book.toml to load title, authors, theme, and preprocessor configuration.

2. Chapter Loading : mdBook parses SUMMARY.md to determine navigation structure and file order.

3. Markdown Processing : Each markdown file is read from the src/ directory.

4. Preprocessor Execution : The mdbook-mermaid preprocessor transforms mermaid code blocks into render-ready HTML.

5. Theme Application : The rust theme provides CSS styling, JavaScript functionality, and HTML templates.

6. Search Index : mdBook generates a searchable index from all content, enabling the built-in search feature.

7. Output Generation : HTML files are written to the book/ subdirectory within the project root.

Sources: scripts/build-docs.sh:268-271

Output Structure

After the build completes, the system copies outputs to /output/ at scripts/build-docs.sh:274-295

Output Directory Structure

Sources: scripts/build-docs.sh:274-295

Output Artifacts

The book/ directory contains:

• index.html - Main entry point with navigation sidebar
• print.html - Single-page version for printing
• *.html - Individual chapter pages
• searchindex.json - Search index data
• searchindex.js - Search functionality
• CSS and JavaScript assets for theming and interactivity

Sources: scripts/build-docs.sh:274-295 README.md:53-58

Local Serving

The generated HTML can be served locally using Python’s built-in HTTP server, as documented in README.md26:

This serves the documentation at http://localhost:8000, providing:

• Full-text search functionality
• Interactive navigation sidebar
• Rendered Mermaid diagrams (client-side rendering)
• Theme switching (light/dark/rust/coal/navy/ayu)
• Print-friendly single-page view

Sources: README.md:26-29 scripts/build-docs.sh:307-308

Dismiss

Refresh this wiki

Enter email to refresh