Configuration Generation

Relevant source files

• build-docs.sh

Purpose and Scope

This document details how the book.toml configuration file is dynamically generated during Phase 3 of the build process. The configuration generation occurs in build-docs.sh:78-103 and uses environment variables, Git repository metadata, and computed defaults to produce a complete mdBook configuration.

For information about how the generated configuration is used by mdBook to build the documentation site, see mdBook Integration. For details about the SUMMARY.md generation that happens after configuration generation, see SUMMARY.md Generation.

Sources: build-docs.sh:1-206

Configuration Flow Overview

The configuration generation process transforms user-provided environment variables and auto-detected repository information into a complete book.toml file that controls all aspects of the mdBook build.

Configuration Data Flow

flowchart TB
    subgraph "Input Sources"
        ENV_REPO["Environment Variable:\nREPO"]
ENV_TITLE["Environment Variable:\nBOOK_TITLE"]
ENV_AUTHORS["Environment Variable:\nBOOK_AUTHORS"]
ENV_URL["Environment Variable:\nGIT_REPO_URL"]
GIT["Git Remote:\norigin URL"]
end
    
    subgraph "Processing in build-docs.sh"
        AUTO_DETECT["Auto-Detection Logic\n[8-19]"]
VAR_INIT["Variable Initialization\n[21-26]"]
VALIDATION["Repository Validation\n[32-37]"]
DEFAULTS["Default Computation\n[39-45]"]
end
    
    subgraph "Computed Values"
        FINAL_REPO["REPO:\nowner/repo"]
FINAL_TITLE["BOOK_TITLE:\nDocumentation"]
FINAL_AUTHORS["BOOK_AUTHORS:\nrepo owner"]
FINAL_URL["GIT_REPO_URL:\nhttps://github.com/owner/repo"]
REPO_PARTS["REPO_OWNER, REPO_NAME"]
end
    
    subgraph "book.toml Generation"
        BOOK_SECTION["[book] section\n[86-91]"]
HTML_SECTION["[output.html] section\n[93-95]"]
PREPROC_SECTION["[preprocessor.mermaid]\n[97-98]"]
FOLD_SECTION["[output.html.fold]\n[100-102]"]
end
    
    OUTPUT["book.toml file\nwritten to /workspace/book/"]
GIT -->|if REPO not set| AUTO_DETECT
 
   ENV_REPO -->|or explicit| AUTO_DETECT
 
   AUTO_DETECT --> VAR_INIT
    
 
   ENV_TITLE --> VAR_INIT
 
   ENV_AUTHORS --> VAR_INIT
 
   ENV_URL --> VAR_INIT
    
 
   VAR_INIT --> VALIDATION
 
   VALIDATION --> DEFAULTS
 
   VALIDATION --> REPO_PARTS
    
 
   DEFAULTS --> FINAL_REPO
 
   DEFAULTS --> FINAL_TITLE
 
   DEFAULTS --> FINAL_AUTHORS
 
   DEFAULTS --> FINAL_URL
 
   REPO_PARTS --> FINAL_AUTHORS
 
   REPO_PARTS --> FINAL_URL
    
 
   FINAL_TITLE --> BOOK_SECTION
 
   FINAL_AUTHORS --> BOOK_SECTION
 
   FINAL_URL --> HTML_SECTION
    
 
   BOOK_SECTION --> OUTPUT
 
   HTML_SECTION --> OUTPUT
 
   PREPROC_SECTION --> OUTPUT
 
   FOLD_SECTION --> OUTPUT

Sources: build-docs.sh:8-103

Environment Variables and Defaults

The configuration generation system processes five primary environment variables, each with intelligent defaults computed from the repository context.

Environment Variable Processing

Sources: build-docs.sh:21-45

Variable Initialization Code Structure

Sources: build-docs.sh:21-45

Auto-Detection Logic

When the REPO environment variable is not explicitly provided, the system attempts to auto-detect it from the Git repository configuration. This enables zero-configuration usage in CI/CD environments.

Git Remote URL Extraction

The auto-detection logic in build-docs.sh:8-19 performs the following steps:

1. Check if running in a Git repository: Uses git rev-parse --git-dir to verify
2. Extract remote URL: Retrieves remote.origin.url from Git config
3. Parse GitHub URL: Uses sed regex to extract owner/repo from various URL formats

Supported GitHub URL Formats:

• HTTPS: https://github.com/owner/repo.git
• SSH: git@github.com:owner/repo.git
• Without .git suffix: https://github.com/owner/repo

Auto-Detection Algorithm

Sources: build-docs.sh:8-19

Regex Pattern Details

The sed command at build-docs.sh16 uses this regex pattern:

s#.*github\.com<FileRef file-url="https://github.com/jzombie/deepwiki-to-mdbook/blob/135bed35/#LNaN-LNaN" NaN  file-path="">Hii</FileRef>(\.git)?.*#\1#

This pattern:

• Matches github.com followed by either : (SSH) or / (HTTPS)
• Captures the owner/repo portion: ([^/]+/[^/\.]+)
• Optionally matches .git suffix: (\.git)?
• Extracts only the owner/repo portion as the replacement

Sources: build-docs.sh16

book.toml Structure

The generated book.toml file contains four configuration sections that control mdBook's behavior. The file is created at build-docs.sh:84-103 using a here-document.

Configuration Sections

Sources: build-docs.sh:84-103

Section Details

[book] Section

Located at build-docs.sh:86-91 this section defines core book metadata:

Sources: build-docs.sh:86-91

[output.html] Section

Located at build-docs.sh:93-95 this section configures HTML output:

Sources: build-docs.sh:93-95

[preprocessor.mermaid] Section

Located at build-docs.sh:97-98 this section enables Mermaid diagram rendering:

This preprocessor is executed before mdBook processes the Markdown files, transforming Mermaid code blocks into rendered diagrams. The preprocessor binary is installed during the Docker build and its assets are installed at build-docs.sh:170-171

Sources: build-docs.sh:97-98

[output.html.fold] Section

Located at build-docs.sh:100-102 this section configures navigation behavior:

Sources: build-docs.sh:100-102

Configuration Generation Process

The complete configuration generation process occurs within the orchestration logic of build-docs.sh. This diagram maps the process to specific code locations.

Code Execution Sequence

sequenceDiagram
    participant ENV as Environment Variables
    participant AUTO as Auto-Detection [8-19]
    participant INIT as Initialization [21-26]
    participant VAL as Validation [32-37]
    participant PARSE as Parsing [39-41]
    participant DEF as Defaults [44-45]
    participant LOG as Logging [47-53]
    participant GEN as Generation [84-103]
    participant FILE as book.toml
    
    ENV->>AUTO: Check if REPO set
    AUTO->>AUTO: Try git config
    AUTO->>INIT: Return REPO (or empty)
    
    INIT->>INIT: Set variable defaults
    INIT->>VAL: Pass to validation
    
    VAL->>VAL: Check REPO not empty
    alt REPO is empty
        VAL-->>ENV: Exit with error
    end
    
    VAL->>PARSE: Continue with valid REPO
    PARSE->>PARSE: Extract REPO_OWNER
    PARSE->>PARSE: Extract REPO_NAME
    
    PARSE->>DEF: Pass extracted parts
    DEF->>DEF: Compute BOOK_AUTHORS
    DEF->>DEF: Compute GIT_REPO_URL
    
    DEF->>LOG: Pass final config
    LOG->>LOG: Echo configuration
    
    Note over LOG,GEN: Scraper runs here [58]
    
    LOG->>GEN: Proceed to book.toml
    GEN->>GEN: Create [book] section
    GEN->>GEN: Create [output.html]
    GEN->>GEN: Create [preprocessor.mermaid]
    GEN->>GEN: Create [output.html.fold]
    
    GEN->>FILE: Write complete file

Sources: build-docs.sh:8-103

Template Interpolation

The book.toml file is generated using shell variable interpolation within a here-document (heredoc). This technique allows dynamic insertion of computed values into the template.

Here-Document Structure

The generation code at build-docs.sh:85-103 uses this structure:

cat > book.toml <<EOF
[book]
title = "$BOOK_TITLE"
authors = ["$BOOK_AUTHORS"]
...
EOF

The <<EOF syntax creates a here-document that:

1. Allows multi-line content with preserved formatting
2. Performs shell variable expansion (using $VARIABLE syntax)
3. Writes the result to book.toml via redirection

Variable Interpolation Points

The quotes around variable names ensure that values containing spaces are properly handled in the TOML format.

Sources: build-docs.sh:85-103

Output Location and Usage

The generated book.toml file is written to /workspace/book/book.toml within the Docker container. This location is significant because:

1. Working Directory: The script changes to $BOOK_DIR at build-docs.sh82
2. mdBook Convention: mdBook expects book.toml in the project root
3. Build Process: The mdbook build command at build-docs.sh176 reads this file

File Lifecycle

The file is also copied to the output directory at build-docs.sh191 for user reference and debugging purposes.

Sources: build-docs.sh:82-191

Error Handling

Configuration generation includes validation to ensure required values are present before proceeding with the build.

Repository Validation

The validation logic at build-docs.sh:32-37 checks that REPO has a value:

stateDiagram-v2
    [*] --> AutoDetect : Script starts
    AutoDetect --> CheckEmpty : Lines 8-19
    CheckEmpty --> Error : REPO still empty
    CheckEmpty --> ParseRepo : REPO has value
    
    Error --> [*] : Exit code 1
    
    ParseRepo --> ComputeDefaults : Lines 39-45
    ComputeDefaults --> LogConfig : Lines 47-53
    LogConfig --> GenerateConfig : Lines 84-103
    GenerateConfig --> [*] : Continue build

This validation occurs after auto-detection attempts, so the error message guides users to either:

1. Set the REPO environment variable explicitly, or
2. Run the command from within a Git repository with a GitHub remote configured

Validation Timing

Sources: build-docs.sh:32-37

Configuration Output Example

Based on the generation logic, here is an example of a complete generated book.toml file when processing the repository jzombie/deepwiki-to-mdbook:

This example demonstrates:

• Default title when BOOK_TITLE is not set
• Author extracted from repository owner
• Computed Git repository URL
• All static configuration values

Sources: build-docs.sh:84-103

Integration with mdBook Build

The generated configuration is consumed by mdBook during the build process. The integration points are:

1. mdbook-mermaid install at build-docs.sh171 reads [preprocessor.mermaid]
2. mdbook build at build-docs.sh176 reads all sections
3. HTML output uses [output.html] settings for theming and repository links
4. Navigation rendering uses [output.html.fold] for sidebar behavior

Configuration-Driven Features

For details on how mdBook processes this configuration to build the final documentation site, see mdBook Integration.

Sources: build-docs.sh:84-176