mdBook Integration

Relevant source files

• Dockerfile
• README.md
• build-docs.sh

Purpose and Scope

This document explains how the DeepWiki-to-mdBook Converter integrates with mdBook and its plugins to generate the final HTML documentation. It covers the configuration file generation, table of contents assembly, build orchestration, and diagram rendering setup. For details about the earlier phases that produce the markdown input files, see Phase 1: Markdown Extraction and Phase 2: Diagram Enhancement. For specifics on the build process flow, see Phase 3: mdBook Build.

Overview

The system integrates mdBook as the final transformation stage, converting enhanced Markdown files into a searchable, navigable HTML documentation site. This integration is orchestrated by the build-docs.sh script and uses two Rust-based tools compiled during the Docker build:

The integration is optional and can be bypassed by setting MARKDOWN_ONLY=true, which produces only the enhanced Markdown files without the HTML build.

Sources: build-docs.sh:60-76 Dockerfile:1-5 Dockerfile:19-21

Integration Architecture

The following diagram shows how mdBook is integrated into the three-phase pipeline and what files it consumes and produces:

Sources: build-docs.sh:60-206 README.md:138-144

graph TB
    subgraph "Phase 1 & 2 Output"
        WikiDir["$WIKI_DIR\n(Scraped Markdown)"]
RootMD["*.md files\n(Root pages)"]
SectionDirs["section-N/\n(Subsection pages)"]
WikiDir --> RootMD
 
       WikiDir --> SectionDirs
    end
    
    subgraph "build-docs.sh Orchestrator"
        CheckMode{"MARKDOWN_ONLY\ncheck"}
GenConfig["Generate book.toml\n(lines 84-103)"]
GenSummary["Generate SUMMARY.md\n(lines 108-159)"]
CopyFiles["Copy to src/\n(line 166)"]
InstallAssets["mdbook-mermaid install\n(line 171)"]
BuildCmd["mdbook build\n(line 176)"]
end
    
    subgraph "mdBook Process"
        ParseConfig["Parse book.toml"]
ParseSummary["Parse SUMMARY.md"]
ProcessMD["Process Markdown files"]
MermaidPreproc["mdbook-mermaid\npreprocessor"]
RenderHTML["Render HTML pages"]
end
    
    subgraph "Output Directory"
        BookHTML["$OUTPUT_DIR/book/\n(HTML site)"]
BookToml["$OUTPUT_DIR/book.toml\n(Config copy)"]
MarkdownCopy["$OUTPUT_DIR/markdown/\n(Source copy)"]
end
    
 
   WikiDir --> CheckMode
 
   CheckMode -->|false| GenConfig
 
   CheckMode -->|true| MarkdownCopy
    
 
   GenConfig --> GenSummary
 
   GenSummary --> CopyFiles
 
   CopyFiles --> InstallAssets
 
   InstallAssets --> BuildCmd
    
 
   BuildCmd --> ParseConfig
 
   BuildCmd --> ParseSummary
 
   ParseConfig --> ProcessMD
 
   ParseSummary --> ProcessMD
 
   ProcessMD --> MermaidPreproc
 
   MermaidPreproc --> RenderHTML
    
 
   RenderHTML --> BookHTML
 
   GenConfig -.->|copy| BookToml
 
   WikiDir -.->|copy| MarkdownCopy

Configuration Generation (book.toml)

The build-docs.sh script dynamically generates the book.toml configuration file using environment variables. This generation occurs in build-docs.sh:84-103 and produces a TOML file with three main sections:

Configuration Structure

Configuration Fields

The generated configuration includes:

Sources: build-docs.sh:84-103 build-docs.sh:39-45

Table of Contents Generation (SUMMARY.md)

The system automatically generates SUMMARY.md from the scraped file structure, discovering the hierarchy from filename patterns and directory organization. This logic is implemented in build-docs.sh:108-159

Generation Algorithm

File Structure Detection

The algorithm detects the hierarchical structure using these conventions:

The algorithm extracts the section number from the filename using grep -oE '^[0-9]+' and checks for the existence of a corresponding section-N directory. If found, it writes the main section as a header followed by indented subsections.

Sources: build-docs.sh:108-159 build-docs.sh:117-123 build-docs.sh:126-158

Build Process Orchestration

The build process follows a specific sequence of operations coordinated by build-docs.sh:

Sources: build-docs.sh:78-191

sequenceDiagram
    participant Script as build-docs.sh
    participant FS as File System
    participant MdBook as mdbook binary
    participant Mermaid as mdbook-mermaid binary
    
    Note over Script: Step 2: Initialize\n(lines 78-82)
    Script->>FS: mkdir -p $BOOK_DIR
    Script->>Script: cd $BOOK_DIR
    
    Note over Script: Generate Config\n(lines 84-103)
    Script->>FS: Write book.toml
    Script->>FS: mkdir -p src
    
    Note over Script: Step 3: Generate TOC\n(lines 108-159)
    Script->>FS: Read $WIKI_DIR/*.md files
    Script->>FS: Read section-*/*.md files
    Script->>FS: Write src/SUMMARY.md
    
    Note over Script: Step 4: Copy Files\n(lines 164-166)
    Script->>FS: cp -r $WIKI_DIR/* src/
    
    Note over Script: Step 5: Install Assets\n(lines 169-171)
    Script->>Mermaid: mdbook-mermaid install $BOOK_DIR
    Mermaid->>FS: Install mermaid.min.js
    Mermaid->>FS: Install mermaid-init.js
    Mermaid->>FS: Update book.toml
    
    Note over Script: Step 6: Build\n(lines 174-176)
    Script->>MdBook: mdbook build
    MdBook->>FS: Read book.toml
    MdBook->>FS: Read src/SUMMARY.md
    MdBook->>FS: Read src/*.md files
    MdBook->>Mermaid: Preprocess (mermaid blocks)
    Mermaid-->>MdBook: Transformed Markdown
    MdBook->>FS: Write book/ directory
    
    Note over Script: Step 7: Copy Outputs\n(lines 179-191)
    Script->>FS: cp -r book $OUTPUT_DIR/
    Script->>FS: cp book.toml $OUTPUT_DIR/
    Script->>FS: cp -r $WIKI_DIR/* $OUTPUT_DIR/markdown/

mdbook-mermaid Integration

The system uses the mdbook-mermaid preprocessor to enable Mermaid diagram rendering in the final HTML output. This integration involves three steps:

Installation and Configuration

The mdbook-mermaid binary is compiled during the Docker build stage:

Preprocessor Configuration

The preprocessor is configured in the generated book.toml:

This configuration tells mdBook to run mdbook-mermaid as a preprocessor before rendering HTML. The preprocessor scans all Markdown files for code blocks with the mermaid language tag and transforms them into HTML containers that the Mermaid JavaScript library can render.

Asset Installation

The mdbook-mermaid install command (executed at build-docs.sh171) installs required JavaScript and CSS assets:

These assets are installed into the book's theme directory and are automatically included in all generated HTML pages.

Sources: Dockerfile5 Dockerfile21 build-docs.sh:169-171 build-docs.sh:97-98

Output Structure

After the mdBook build completes, the system produces three output artifacts:

HTML Site Features

The generated HTML site includes:

Sources: build-docs.sh:179-191 README.md:93-104

Binary Requirements

The integration requires two Rust binaries to be available at runtime:

Both binaries are compiled during the Docker multi-stage build and copied to the final image. The compilation occurs in Dockerfile:1-5 using cargo install, and the binaries are extracted in Dockerfile:19-21 from the build stage.

Sources: Dockerfile:1-21 build-docs.sh171 build-docs.sh176