SUMMARY.md Generation

Relevant source files

• build-docs.sh

Purpose and Scope

This document explains how the SUMMARY.md file is dynamically generated from the scraped markdown content structure. The SUMMARY.md file serves as mdBook's table of contents, defining the navigation structure and page hierarchy for the generated HTML documentation.

For information about how the markdown files are initially organized during scraping, see Wiki Structure Discovery. For details about the overall mdBook build configuration, see Configuration Generation.

SUMMARY.md in mdBook

The SUMMARY.md file is mdBook's primary navigation document. It defines:

• The order of pages in the documentation
• The hierarchical structure (chapters and sub-chapters)
• The titles displayed in the navigation sidebar
• Which markdown files map to which sections

mdBook parses SUMMARY.md to construct the entire book structure. Pages not listed in SUMMARY.md will not be included in the generated documentation.

Sources: build-docs.sh:108-161

Generation Process Overview

The SUMMARY.md generation occurs in Step 3 of the build pipeline, after markdown extraction is complete but before the mdBook build begins. The generation algorithm automatically discovers the file structure and constructs an appropriate table of contents.

Diagram: SUMMARY.md Generation Workflow

flowchart TD
    Start["Start: SUMMARY.md Generation\n(build-docs.sh:110)"]
Init["Initialize Output\nEcho '# Summary'"]
FindFirst["Find First Page\nls $WIKI_DIR/*.md /head -1"]
ExtractFirst["Extract Title head -1 $file/ sed 's/^# //'"]
AddFirst["Add as Introduction\n[title](filename)"]
LoopStart["Iterate: $WIKI_DIR/*.md"]
Skip{"Is first_page?"}
ExtractTitle["Extract Title from First Line\nhead -1 $file /sed 's/^# //'"]
GetSectionNum["Extract section_num grep -oE '^[0-9]+'"]
CheckDir{"Directory Exists? section-$section_num/"}
MainWithSub["Output Section Header # $title - [$title] $filename"]
IterateSub["Iterate: section-$section_num/*.md"]
AddSub["Add Subsection - [$subtitle] section-N/$subfilename"]
Standalone["Output Standalone - [$title] $filename"]
LoopEnd{"More Files?"}
Complete["Write to src/SUMMARY.md"]
End["End: SUMMARY.md Generated"]
Start --> Init
 Init --> FindFirst
 FindFirst --> ExtractFirst
 ExtractFirst --> AddFirst
 AddFirst --> LoopStart
 LoopStart --> Skip
 Skip -->|Yes|LoopEnd
 Skip -->|No|ExtractTitle
 ExtractTitle --> GetSectionNum
 GetSectionNum --> CheckDir
 CheckDir -->|Yes|MainWithSub
 MainWithSub --> IterateSub
 IterateSub --> AddSub
 AddSub --> LoopEnd
 CheckDir -->|No|Standalone
 Standalone --> LoopEnd
 LoopEnd -->|Yes|LoopStart
 LoopEnd -->|No| Complete
 
   Complete --> End

Sources: build-docs.sh:108-161

Algorithm Components

Step 1: Introduction Page Selection

The first markdown file in the wiki directory is designated as the introduction page. This ensures the documentation has a clear entry point.

Diagram: First Page Processing Pipeline

flowchart LR
    ListFiles["ls $WIKI_DIR/*.md"]
TakeFirst["head -1"]
GetBasename["basename"]
StoreName["first_page variable"]
ExtractTitle["head -1 $WIKI_DIR/$first_page"]
RemoveHash["sed 's/^# //'"]
StoreTitle["title variable"]
WriteEntry["echo '[${title}]($first_page)'"]
ToSummary[">> src/SUMMARY.md"]
ListFiles --> TakeFirst
 
   TakeFirst --> GetBasename
 
   GetBasename --> StoreName
    
 
   StoreName --> ExtractTitle
 
   ExtractTitle --> RemoveHash
 
   RemoveHash --> StoreTitle
    
 
   StoreTitle --> WriteEntry
 
   WriteEntry --> ToSummary

The implementation uses shell command chaining:

• ls "$WIKI_DIR"/*.md 2>/dev/null | head -1 | xargs basename extracts the first filename
• head -1 "$WIKI_DIR/$first_page" | sed 's/^# //' extracts the title by removing the leading # from the first line

Sources: build-docs.sh:118-123

Step 2: Main Page Iteration

All markdown files in the root wiki directory are processed sequentially. Each file represents either a standalone page or a main section with subsections.

Sources: build-docs.sh:126-135

Step 3: Subsection Detection

The algorithm determines whether a main page has subsections by:

1. Extracting the numeric prefix from the filename (e.g., 5 from 5-component-reference.md)
2. Checking if a corresponding section-N/ directory exists
3. If found, treating the page as a main section with nested subsections

flowchart TD
    MainPage["Main Page File\ne.g., 5-component-reference.md"]
ExtractNum["Extract section_num\necho $filename /grep -oE '^[0-9]+'"]
HasNum{"Numeric Prefix?"}
BuildPath["Construct section_dir $WIKI_DIR/section-$section_num"]
CheckDir["Check Directory [ -d $section_dir ]"]
DirExists{"Directory Exists?"}
OutputHeader["Output Section Header # $title"]
OutputMain["Output Main Link - [$title] $filename"]
IterateSubs["for subfile in $section_dir/*.md"]
ExtractSubTitle["head -1 $subfile/ sed 's/^# //'"]
OutputSub["Output Subsection\n - [$subtitle](section-N/$subfilename)"]
OutputStandalone["Output Standalone\n- [$title]($filename)"]
MainPage --> ExtractNum
 
   ExtractNum --> HasNum
    
 
   HasNum -->|Yes| BuildPath
 
   HasNum -->|No| OutputStandalone
    
 
   BuildPath --> CheckDir
 
   CheckDir --> DirExists
    
 
   DirExists -->|Yes| OutputHeader
 
   OutputHeader --> OutputMain
 
   OutputMain --> IterateSubs
 
   IterateSubs --> ExtractSubTitle
 
   ExtractSubTitle --> OutputSub
    
 
   DirExists -->|No| OutputStandalone

Diagram: Subsection Detection and Nesting Logic

Sources: build-docs.sh:137-158

Step 4: Subsection Processing

When a section-N/ directory is detected, all markdown files within it are processed as subsections:

Key aspects:

• Subsections use two-space indentation: - <FileRef file-url="https://github.com/jzombie/deepwiki-to-mdbook/blob/135bed35/$subtitle" undefined file-path="$subtitle">Hii</FileRef>
• File paths include the section-N/ directory prefix
• Each subsection's title is extracted using the same pattern as main pages

Sources: build-docs.sh:147-152

File Structure Conventions

The generation algorithm depends on the file structure created during markdown extraction (see Wiki Structure Discovery):

Diagram: File Structure Conventions for SUMMARY.md Generation

Sources: build-docs.sh:126-158

Title Extraction Method

All page titles are extracted using a consistent pattern:

This assumes that every markdown file begins with a level-1 heading (# Title). The sed command removes the # prefix, leaving only the title text.

Extraction Pipeline:

Sources: build-docs.sh120 build-docs.sh134 build-docs.sh150

Output Format

The generated SUMMARY.md follows mdBook's syntax:

Format Rules:

Sources: build-docs.sh:113-159

Implementation Code Mapping

The following table maps the algorithm steps to specific code locations:

Diagram: Code Location Mapping for SUMMARY.md Generation

Sources: build-docs.sh:108-161

Generation Statistics

After generation completes, the script logs the number of entries created: