Output Structure

Loading…

Output Structure

Relevant source files

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

This page documents the structure and contents of the /output directory produced by the DeepWiki-to-mdBook converter. The output structure varies depending on whether the system runs in full build mode or markdown-only mode. For information about enabling markdown-only mode, see Markdown-Only Mode.

Output Directory Overview

The system writes all artifacts to the /output directory, which is typically mounted as a Docker volume. The contents of this directory depend on the MARKDOWN_ONLY environment variable:

Output Mode Decision Logic

graph TD
    Start["build-docs.sh execution"]
CheckMode{MARKDOWN_ONLY\nenvironment variable}
FullBuild["Full Build Path"]
MarkdownOnly["Markdown-Only Path"]
OutputBook["/output/book/\nHTML documentation"]
OutputMarkdown["/output/markdown/\nSource .md files"]
OutputToml["/output/book.toml\nConfiguration"]
Start --> CheckMode
 
   CheckMode -->|false default| FullBuild
 
   CheckMode -->|true| MarkdownOnly
    
 
   FullBuild --> OutputBook
 
   FullBuild --> OutputMarkdown
 
   FullBuild --> OutputToml
    
 
   MarkdownOnly --> OutputMarkdown

Sources: build-docs.sh26 build-docs.sh:60-76

Full Build Mode Output

When MARKDOWN_ONLY is not set or is false, the system produces three distinct outputs:

graph TD
    Output["/output/"]
Book["book/\nComplete HTML site"]
Markdown["markdown/\nSource files"]
BookToml["book.toml\nConfiguration"]
BookIndex["index.html"]
BookCSS["css/"]
BookJS["FontAwesome/"]
BookSearchJS["searchindex.js"]
BookMermaid["mermaid-init.js"]
BookPages["*.html pages"]
MarkdownRoot["*.md files\n(main pages)"]
MarkdownSections["section-N/\n(subsection dirs)"]
Output --> Book
 
   Output --> Markdown
 
   Output --> BookToml
    
 
   Book --> BookIndex
 
   Book --> BookCSS
 
   Book --> BookJS
 
   Book --> BookSearchJS
 
   Book --> BookMermaid
 
   Book --> BookPages
    
 
   Markdown --> MarkdownRoot
 
   Markdown --> MarkdownSections

Directory Structure

Full Build Output Structure

Sources: build-docs.sh:178-192 README.md:92-104

/output/book/ Directory

The book/ directory contains the complete HTML documentation site generated by mdBook. This is a self-contained static website that can be hosted on any web server or opened directly in a browser.

The HTML site includes:

• Responsive navigation sidebar with hierarchical structure
• Full-text search functionality
• Syntax highlighting for code blocks
• Working Mermaid diagram rendering
• “Edit this page” links pointing to GIT_REPO_URL
• Collapsible sections in the navigation

Sources: build-docs.sh:173-176 build-docs.sh:94-95 README.md:95-99

/output/markdown/ Directory

The markdown/ directory contains the source Markdown files extracted from DeepWiki and enhanced with Mermaid diagrams. These files follow a specific naming convention and organizational structure.

File Naming Convention:

<page-number>-<page-title-slug>.md

Examples from actual output:

• 1-overview.md
• 2-1-workspace-and-crates.md
• 3-2-sql-parser.md

Subsection Organization:

Pages with subsections have their children organized into directories:

section-N/
  N-1-first-subsection.md
  N-2-second-subsection.md
  ...

For example, if page 4-architecture.md has subsections, they appear in:

section-4/
  4-1-overview.md
  4-2-components.md

This organization is reflected in the mdBook SUMMARY.md generation logic at build-docs.sh:125-159

Sources: README.md:100-119 build-docs.sh:163-166 build-docs.sh:186-188

/output/book.toml File

The book.toml file is a copy of the mdBook configuration used to generate the HTML site. It contains:

This file can be used to:

• Understand the configuration used for the build
• Regenerate the book with different settings
• Debug mdBook configuration issues

Sources: build-docs.sh:84-103 build-docs.sh:190-191

Markdown-Only Mode Output

When MARKDOWN_ONLY=true, the system produces only the /output/markdown/ directory. This mode skips the mdBook build phase entirely.

Markdown-Only Mode Data Flow

graph LR
    Scraper["deepwiki-scraper.py"]
TempDir["/workspace/wiki/\nTemporary directory"]
OutputMarkdown["/output/markdown/\nFinal output"]
Scraper -->|Writes enhanced .md files| TempDir
 
   TempDir -->|cp -r| OutputMarkdown

The output structure is identical to the markdown/ directory in full build mode, but the book/ and book.toml artifacts are not created.

Sources: build-docs.sh:60-76 README.md:106-113

graph TD
    subgraph "Phase 1: Scraping"
        Scraper["deepwiki-scraper.py"]
WikiDir["/workspace/wiki/"]
end
    
    subgraph "Phase 2: Decision Point"
        CheckMode{MARKDOWN_ONLY\ncheck}
end
    
    subgraph "Phase 3: mdBook Build (conditional)"
        BookInit["Initialize /workspace/book/"]
GenToml["Generate book.toml"]
GenSummary["Generate SUMMARY.md"]
CopyToSrc["cp wiki/* book/src/"]
MermaidInstall["mdbook-mermaid install"]
MdBookBuild["mdbook build"]
BuildOutput["/workspace/book/book/"]
end
    
    subgraph "Phase 4: Copy to Output"
        CopyBook["cp -r book /output/"]
CopyMarkdown["cp -r wiki /output/markdown/"]
CopyToml["cp book.toml /output/"]
end
    
 
   Scraper -->|Writes to| WikiDir
 
   WikiDir --> CheckMode
    
 
   CheckMode -->|false| BookInit
 
   CheckMode -->|true| CopyMarkdown
    
 
   BookInit --> GenToml
 
   GenToml --> GenSummary
 
   GenSummary --> CopyToSrc
 
   CopyToSrc --> MermaidInstall
 
   MermaidInstall --> MdBookBuild
 
   MdBookBuild --> BuildOutput
    
 
   BuildOutput --> CopyBook
 
   WikiDir --> CopyMarkdown
 
   GenToml --> CopyToml

Output Generation Process

The following diagram shows how each output artifact is generated during the build process:

Complete Output Generation Pipeline

Sources: build-docs.sh:55-205

File Naming Examples

The following table shows actual filename patterns produced by the system:

The system automatically detects which pages have subsections by examining the numeric prefix and checking for corresponding section-N/ directories during SUMMARY.md generation.

Sources: build-docs.sh:125-159 README.md:115-119

Volume Mounting

The /output directory is designed to be mounted as a Docker volume. The typical Docker run command specifies:

This mounts the host’s ./output directory to the container’s /output directory, making all generated artifacts accessible on the host filesystem after the container exits.

Sources: README.md:34-38 README.md:83-86

Output Size Characteristics

The output directory typically contains:

• Markdown files : 10-500 KB per page depending on content length and diagram count
• HTML book : 5-50 MB total depending on page count and assets
• book.toml : ~500 bytes

For a typical repository with 20-30 documentation pages, expect:

• markdown/: 5-15 MB
• book/: 10-30 MB (includes all HTML, CSS, JS, and search index)
• book.toml: < 1 KB

The HTML book is significantly larger than the markdown source because it includes:

• Complete mdBook framework (CSS, JavaScript)
• Search index (searchindex.js)
• Mermaid rendering library (mermaid.min.js)
• Font assets (FontAwesome)
• Generated HTML for each page with navigation

Sources: build-docs.sh:178-205

Serving the Output

The HTML documentation in /output/book/ can be served using any static web server:

The markdown files in /output/markdown/ can be:

• Committed to a Git repository
• Used as input for other documentation systems
• Edited and re-processed through mdBook manually
• Served directly by markdown-aware platforms like GitHub

Sources: README.md:83-86 build-docs.sh:203-204

Dismiss

Refresh this wiki

Enter email to refresh