Custom Templates

Loading…

Custom Templates

Relevant source files

• README.md
• templates/README.md

This page explains how to provide custom header and footer templates for the DeepWiki-to-mdBook converter through Docker volume mounts. Custom templates allow you to control the HTML content injected at the beginning and end of every generated markdown file, enabling branding, navigation elements, and custom styling.

For information about the variables available for use within templates, see Template Variables. For comprehensive details about the template system architecture and processing logic, see Template System.

Purpose and Scope

The template system supports customization through two mechanisms:

1. Volume Mounts : Replace default templates by mounting custom files into the container
2. Environment Variables : Override default template file paths

This page documents both mechanisms and provides practical examples for common customization scenarios.

Sources: README.md:39-51 templates/README.md:42-56

Default Template Architecture

The system includes two default templates that are baked into the Docker image:

graph LR
    subgraph "Container Filesystem"
        DefaultTemplates["/workspace/templates/\nheader.html\nfooter.html"]
CustomMount["/workspace/templates/\n(volume mount)"]
end
    
    subgraph "Resolution Logic"
        CheckMount{"Custom\ntemplates\nmounted?"}
UseDefault["Use default\ntemplates"]
UseCustom["Use custom\ntemplates"]
end
    
    subgraph "Processing Pipeline"
        ProcessTemplate["process-template.py\nVariable substitution\nConditional rendering"]
MarkdownFiles["markdown/*.md"]
InjectedContent["Markdown with\ninjected headers/footers"]
end
    
 
   DefaultTemplates --> CheckMount
 
   CustomMount --> CheckMount
 
   CheckMount -->|No| UseDefault
 
   CheckMount -->|Yes| UseCustom
 
   UseDefault --> ProcessTemplate
 
   UseCustom --> ProcessTemplate
 
   ProcessTemplate --> MarkdownFiles
 
   MarkdownFiles --> InjectedContent

These defaults provide basic documentation metadata including repository links, DeepWiki badges, and generation timestamps. Custom templates completely replace these defaults when mounted.

Template Processing Flow:

Diagram: Template Resolution and Processing Pipeline

The system checks for mounted templates at container startup. If custom templates are found at the mount point, they replace the defaults entirely. The selected templates are then processed by process-template.py for variable substitution and conditional rendering before being injected into each markdown file.

Sources: templates/README.md:5-8 README.md:39-51

Volume Mount Strategies

Full Directory Mount

The recommended approach is to mount an entire directory containing both custom templates:

Directory Structure:

my-templates/
├── header.html
└── footer.html

This strategy provides clean separation between your custom templates and the system, and allows you to version control both templates together.

Individual File Mounts

For granular control, mount individual template files:

This approach is useful when:

• You only want to customize one template (header or footer)
• Your templates are stored in different locations
• You’re testing template changes without modifying a template directory

Partial Customization

You can mount only one template file, and the system will use the default for the other:

Sources: README.md:44-49 templates/README.md:46-51

Environment Variable Configuration

The template system exposes three environment variables for advanced path customization:

Custom Template Directory

Override the entire template directory location:

Custom Template Paths

Override individual template file paths:

This advanced configuration is rarely needed but provides maximum flexibility for non-standard deployment scenarios.

Sources: templates/README.md:53-56

Template Processing Implementation

The template injection mechanism is implemented in process-template.py, which is invoked by the main orchestrator during Phase 2 of the build pipeline.

Template Processing Code Flow:

graph TB
    subgraph "build-docs.sh Orchestration"
        BuildScript["build-docs.sh"]
Phase2["Phase 2: Enhancement"]
end
    
    subgraph "process-template.py"
        LoadTemplate["load_template()\nRead header/footer files"]
ParseVars["Variable Substitution\n{{VAR}} → value"]
ParseCond["Conditional Rendering\n{{#if VAR}}...{{/if}}"]
StripComments["strip_html_comments()\nRemove <!-- ... -->"]
ProcessFile["process_file()\nInject into markdown"]
end
    
    subgraph "File System"
        TemplateFiles["/workspace/templates/\nheader.html\nfooter.html"]
MarkdownDir["markdown/*.md"]
EnhancedMD["Enhanced markdown\nwith headers/footers"]
end
    
 
   BuildScript --> Phase2
 
   Phase2 --> LoadTemplate
 
   TemplateFiles --> LoadTemplate
 
   LoadTemplate --> ParseVars
 
   ParseVars --> ParseCond
 
   ParseCond --> StripComments
 
   StripComments --> ProcessFile
 
   MarkdownDir --> ProcessFile
 
   ProcessFile --> EnhancedMD

Diagram: Template Processing Implementation Flow

The process-template.py script is executed by build-docs.sh during Phase 2. It loads the template files from the configured paths, performs variable substitution and conditional rendering, strips HTML comments, and injects the processed content into each markdown file.

Key Functions in process-template.py:

Sources: templates/README.md:24-28 README.md51

Practical Examples

Minimal Custom Header

Replace the default header with a simple title banner:

File:my-templates/header.html

File:my-templates/footer.html

Usage:

Branded Documentation

Add company branding and navigation:

File:custom/header.html

File:custom/footer.html

Badge-Based Navigation

Create a navigation header using badges:

File:badges/header.html

Sources: templates/README.md:60-76

graph TB
    subgraph "Phase 1: Extraction"
        Scrape["deepwiki-scraper.py\nExtract wiki content"]
RawMD["raw_markdown/"]
end
    
    subgraph "Phase 2: Enhancement"
        DiagramInject["Inject Mermaid diagrams"]
CheckTemplates{"Custom\ntemplates\nmounted?"}
LoadDefaults["Load default templates\n/workspace/templates/"]
LoadCustom["Load custom templates\n(volume mount)"]
ProcessTemplates["process-template.py\nInject headers/footers"]
EnhancedMD["markdown/"]
end
    
    subgraph "Phase 3: Build"
        GenSummary["Generate SUMMARY.md"]
MDBookBuild["mdbook build"]
FinalHTML["book/"]
end
    
 
   Scrape --> RawMD
 
   RawMD --> DiagramInject
 
   DiagramInject --> CheckTemplates
 
   CheckTemplates -->|No| LoadDefaults
 
   CheckTemplates -->|Yes| LoadCustom
 
   LoadDefaults --> ProcessTemplates
 
   LoadCustom --> ProcessTemplates
 
   ProcessTemplates --> EnhancedMD
 
   EnhancedMD --> GenSummary
 
   GenSummary --> MDBookBuild
 
   MDBookBuild --> FinalHTML

Integration with Build Pipeline

Custom templates are integrated at a specific point in the three-phase build pipeline:

Diagram: Custom Templates in Build Pipeline Context

Template customization occurs in Phase 2, after diagram injection but before mdBook structure generation. This ensures that custom headers and footers are present in the markdown files when SUMMARY.md is generated and mdBook performs its final build. The template selection happens once at the beginning of Phase 2, and the same templates are applied consistently to all markdown files.

Sources: README.md:72-76

Advanced Customization Patterns

Conditional Content Based on Environment

Use conditionals to show different content in different contexts:

Testing Template Changes Locally

Workflow for iterating on custom templates:

1. Create template directory: mkdir -p ./test-templates

2. Add custom templates: vim ./test-templates/header.html

3. Run container with mounted templates:

4. View results: cd output && python3 -m http.server --directory book 8000

5. Iterate by editing templates and re-running step 3

Template Debugging

When templates don’t render as expected:

1. Check file paths : Verify templates are mounted correctly

2. Inspect raw markdown : Check output/markdown/ files to see injected content

3. Verify variable availability : Ensure variables used in templates are set

   • Check environment variables passed to container
   • Review Template Variables for available variables

4. Test HTML syntax : Validate HTML before mounting

Sources: templates/README.md:1-77 README.md:39-51

Template Mount Configuration Matrix

Sources: templates/README.md:42-56 README.md:44-49

Dismiss

Refresh this wiki

Enter email to refresh