Markdown-Only Mode

Relevant source files

• README.md
• build-docs.sh

Purpose and Scope

This document describes the Markdown-Only Mode feature, which provides a fast-path execution mode that bypasses Phase 3 of the processing pipeline. This mode is primarily used for debugging content extraction and diagram placement without waiting for the full mdBook HTML build. For information about the complete three-phase pipeline, see Three-Phase Pipeline. For details about the full output structure, see Output Structure.

Overview

Markdown-Only Mode is a configuration option that terminates the build process after completing Phase 1 (Markdown Extraction) and Phase 2 (Diagram Enhancement), skipping the computationally expensive Phase 3 (mdBook Build). This mode produces only the enhanced Markdown files without generating the final HTML documentation site.

The mode is controlled by the MARKDOWN_ONLY environment variable, which defaults to false for complete builds.

Sources: README.md:55-72 build-docs.sh26

Configuration

The mode is activated by setting the MARKDOWN_ONLY environment variable to "true":

Sources: build-docs.sh26 README.md:45-51

Processing Pipeline Comparison

Full Build vs. Markdown-Only Mode Decision Flow

Sources: build-docs.sh:1-206

Phase Execution Matrix

Both modes execute the Python scraper deepwiki-scraper.py identically. The difference occurs after scraping completes, where the shell orchestrator makes a conditional decision based on the MARKDOWN_ONLY variable.

Sources: build-docs.sh:58-76 README.md:123-145

Implementation Details

Conditional Logic in build-docs.sh

The markdown-only mode implementation consists of a simple conditional branch in the shell orchestrator:

graph TD
    ScraperCall["python3 /usr/local/bin/deepwiki-scraper.py\n[build-docs.sh:58]"]
CheckVar{"if [ '$MARKDOWN_ONLY' = 'true' ]\n[build-docs.sh:61]"}
subgraph "Markdown-Only Path [lines 63-76]"
        MkdirOut["mkdir -p $OUTPUT_DIR/markdown"]
CpMarkdown["cp -r $WIKI_DIR/* $OUTPUT_DIR/markdown/"]
EchoSuccess["Echo success message"]
Exit0["exit 0"]
end
    
    subgraph "Full Build Path [lines 78-206]"
        MkdirBook["mkdir -p $BOOK_DIR"]
CreateToml["Create book.toml"]
CreateSummary["Generate SUMMARY.md"]
CopySrcFiles["Copy markdown to src/"]
MdbookMermaid["mdbook-mermaid install"]
MdbookBuild["mdbook build"]
CopyAll["Copy to /output"]
end
    
 
   ScraperCall --> CheckVar
 
   CheckVar -->|true| MkdirOut
 
   MkdirOut --> CpMarkdown
 
   CpMarkdown --> EchoSuccess
 
   EchoSuccess --> Exit0
    
 
   CheckVar -->|false| MkdirBook
 
   MkdirBook --> CreateToml
 
   CreateToml --> CreateSummary
 
   CreateSummary --> CopySrcFiles
 
   CopySrcFiles --> MdbookMermaid
 
   MdbookMermaid --> MdbookBuild
 
   MdbookBuild --> CopyAll

The implementation performs an early exit at build-docs.sh75 when markdown-only mode is enabled, preventing execution of the entire mdBook build pipeline.

Sources: build-docs.sh:60-76

Variable Reading and Default Value

The MARKDOWN_ONLY variable is read with a default value of "false":

This line at build-docs.sh26 uses bash parameter expansion to set the variable to "false" if it is unset or empty. The string comparison at build-docs.sh61 checks for exact equality with "true", meaning any other value (including "false", "", or "1") results in a full build.

Sources: build-docs.sh26 build-docs.sh61

Output Structure Comparison

Markdown-Only Mode Output

When MARKDOWN_ONLY="true", the output directory contains:

/output/
└── markdown/
    ├── 1-overview.md
    ├── 2-quick-start.md
    ├── 3-configuration-reference.md
    ├── section-4/
    │   ├── 4-1-three-phase-pipeline.md
    │   └── 4-2-docker-multi-stage-build.md
    └── ...

Sources: build-docs.sh:64-74 README.md:106-114

Full Build Mode Output

When MARKDOWN_ONLY="false" (default), the output directory contains:

/output/
├── book/
│   ├── index.html
│   ├── print.html
│   ├── searchindex.js
│   ├── css/
│   ├── FontAwesome/
│   └── ...
├── markdown/
│   ├── 1-overview.md
│   ├── 2-quick-start.md
│   └── ...
└── book.toml

Sources: build-docs.sh:179-201 README.md:89-105

Use Cases

Debugging Diagram Placement

Markdown-only mode is particularly useful when debugging the fuzzy diagram matching algorithm (see Fuzzy Diagram Matching Algorithm). Developers can rapidly iterate on diagram placement logic without waiting for mdBook compilation:

This workflow allows inspection of the exact markdown output, including where diagrams were injected, without the overhead of HTML generation.

Sources: README.md:55-72 README.md:168-169

Content Extraction Verification

When verifying that HTML-to-Markdown conversion is working correctly (see HTML to Markdown Conversion), markdown-only mode provides quick feedback:

Sources: README.md:55-72

CI/CD Pipeline Intermediate Artifacts

In continuous integration pipelines, markdown-only mode can be used as an intermediate step to produce version-controlled markdown artifacts without generating the full HTML site:

Sources: README.md:228-232

Performance Characteristics

Build Time Comparison

The markdown-only mode provides approximately 33% faster execution by eliminating:

• mdBook binary initialization
• book.toml generation
• SUMMARY.md generation
• Markdown file copying to src/
• mdbook-mermaid asset installation
• HTML compilation and asset generation

Note: Actual times vary based on repository size, number of diagrams, and system resources.

Sources: build-docs.sh:78-176 README.md:71-72

Resource Consumption

Sources: README.md175

Common Workflows

Iterative Debugging Workflow

This workflow minimizes iteration time during development by using markdown-only mode for rapid feedback loops, only running the full build when markdown output is verified correct.

Sources: README.md:55-72 README.md177

Markdown Extraction for Other Tools

Markdown-only mode can extract clean markdown files for use with documentation tools other than mdBook:

The extracted markdown files contain properly rewritten internal links and enhanced diagrams, making them suitable for any markdown-compatible documentation system.

Sources: README.md:106-114 README.md:218-232

Console Output Differences

Markdown-Only Mode Output

When MARKDOWN_ONLY="true", the console output terminates after Phase 2:

Step 1: Scraping wiki from DeepWiki...
[... scraping progress ...]

Step 2: Copying markdown files to output (markdown-only mode)...

================================================================================
✓ Markdown extraction complete!
================================================================================

Outputs:
  - Markdown files:  /output/markdown/

The script exits at build-docs.sh75 with exit code 0.

Sources: build-docs.sh:63-75

Full Build Mode Output

When MARKDOWN_ONLY="false", the console output continues through all phases:

Step 1: Scraping wiki from DeepWiki...
[... scraping progress ...]

Step 2: Initializing mdBook structure...
Step 3: Generating SUMMARY.md from scraped content...
Step 4: Copying markdown files to book...
Step 5: Installing mdbook-mermaid assets...
Step 6: Building mdBook...
Step 7: Copying outputs to /output...

================================================================================
✓ Documentation build complete!
================================================================================

Outputs:
  - HTML book:       /output/book/
  - Markdown files:  /output/markdown/
  - Book config:     /output/book.toml

Sources: build-docs.sh:193-205

Summary

Markdown-Only Mode provides a fast-path execution option controlled by the MARKDOWN_ONLY environment variable. It executes Phases 1 and 2 of the pipeline but bypasses Phase 3, producing only enhanced markdown files without HTML documentation. This mode is essential for:

• Debugging : Rapid iteration on content extraction and diagram placement
• Performance : 33% faster execution when HTML output is not needed
• Flexibility : Extract markdown for use with other documentation tools

The implementation is straightforward: a single conditional check at build-docs.sh61 determines whether to execute the mdBook build pipeline or exit early with only markdown artifacts.

Sources: build-docs.sh:60-76 README.md:55-72 README.md:106-114