Template Variables

Loading…

Template Variables

Relevant source files

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

Purpose and Scope

This page provides a complete reference for all template variables available in the deepwiki-to-mdbook template system. Template variables are placeholders that get substituted with actual values during the build process, allowing dynamic customization of headers and footers injected into each markdown file.

For information about the broader template system architecture and conditional logic, see Template System. For guidance on providing custom templates, see Custom Templates.

Variable Overview

Template variables are captured during the build process and passed to process-template.py for substitution into HTML template files. These variables provide context about the repository, documentation metadata, and generated links.

Sources: scripts/build-docs.sh:195-234

Complete Variable Reference

The following table documents all available template variables:

Sources: scripts/build-docs.sh:8-51 scripts/build-docs.sh:195-213

Variable Resolution Flow

The following diagram illustrates how template variables are resolved from multiple sources:

Sources: scripts/build-docs.sh:8-51 scripts/build-docs.sh:195-234

graph TB
    subgraph "Input Sources"
        EnvVars["Environment Variables\n(REPO, BOOK_TITLE, etc.)"]
GitRemote["Git Remote\n(git config remote.origin.url)"]
SystemTime["System Time\n(date -u)"]
end
    
    subgraph "Resolution Logic in build-docs.sh"
        AutoDetect["Auto-Detection\n[build-docs.sh:8-19]"]
SetDefaults["Set Defaults\n[build-docs.sh:21-26]"]
DeriveValues["Derive URLs\n[build-docs.sh:40-51]"]
CaptureDate["Capture Timestamp\n[build-docs.sh:200]"]
end
    
    subgraph "Variable Processing"
        TemplateProcessor["process-template.py"]
HeaderTemplate["templates/header.html"]
FooterTemplate["templates/footer.html"]
end
    
    subgraph "Output"
        ProcessedHeader["Processed Header HTML"]
ProcessedFooter["Processed Footer HTML"]
InjectedMD["Markdown Files\nwith Headers/Footers"]
end
    
 
   EnvVars -->|REPO not set| AutoDetect
 
   GitRemote --> AutoDetect
 
   AutoDetect -->|extract owner/repo| SetDefaults
    
 
   EnvVars --> SetDefaults
 
   SetDefaults --> DeriveValues
    
 
   SystemTime --> CaptureDate
    
 
   DeriveValues -->|8 variables| TemplateProcessor
 
   CaptureDate --> TemplateProcessor
    
 
   HeaderTemplate --> TemplateProcessor
 
   FooterTemplate --> TemplateProcessor
    
 
   TemplateProcessor --> ProcessedHeader
 
   TemplateProcessor --> ProcessedFooter
    
 
   ProcessedHeader --> InjectedMD
 
   ProcessedFooter --> InjectedMD

Variable Processing Implementation

Capture and Derivation

The variable capture process occurs in several stages within build-docs.sh:

1. Auto-detection scripts/build-docs.sh:8-19: If REPO is not set, the script attempts to extract it from the Git remote URL using git config --get remote.origin.url.

2. Default assignment scripts/build-docs.sh:21-26: Environment variables are assigned default values. The pattern ${VAR:-default} provides fallback values.

3. URL derivation scripts/build-docs.sh:40-51: Several URLs are constructed from the base variables:

   • DEEPWIKI_URL is built from REPO
   • GIT_REPO_URL defaults to GitHub URL from REPO
   • GITHUB_BADGE_URL includes URL-encoded REPO with character escaping

4. Timestamp capture scripts/build-docs.sh200: The generation date is captured in UTC format using date -u.

Sources: scripts/build-docs.sh:8-51 scripts/build-docs.sh200

Badge URL Generation

The GitHub badge URL generation includes special character handling:

REPO_BADGE_LABEL=$(printf '%s' "$REPO" | sed 's/-/--/g' | sed 's/\//%2F/g')
GITHUB_BADGE_URL="https://img.shields.io/badge/GitHub-${REPO_BADGE_LABEL}-181717?logo=github"

This escapes hyphens (doubled) and URL-encodes slashes for shields.io badge compatibility.

Sources: scripts/build-docs.sh:50-51

Template Invocation

Variables are passed to process-template.py as command-line arguments in KEY=VALUE format:

The same variables are passed for both header and footer template processing.

Sources: scripts/build-docs.sh:205-213 scripts/build-docs.sh:222-230

graph LR
    subgraph "Stage 1: Variable Collection"
        CollectEnv["Environment Variables"]
CollectGit["Git Remote Detection"]
CollectTime["Timestamp Generation"]
end
    
    subgraph "Stage 2: build-docs.sh Processing"
        ValidateREPO["Validate REPO\n[build-docs.sh:33-38]"]
ExtractParts["Extract REPO_OWNER\nand REPO_NAME\n[build-docs.sh:40-42]"]
ApplyDefaults["Apply Defaults\n[build-docs.sh:44-46]"]
ConstructURLs["Construct Badge URLs\n[build-docs.sh:48-51]"]
end
    
    subgraph "Stage 3: Template Processing"
        InvokeProcessor["Invoke process-template.py\n[build-docs.sh:205-230]"]
SubstituteVars["Variable Substitution"]
EvalConditionals["Evaluate Conditionals"]
StripComments["Strip HTML Comments"]
end
    
    subgraph "Stage 4: Output"
        HeaderHTML["HEADER_HTML"]
FooterHTML["FOOTER_HTML"]
InjectFiles["Inject into Markdown\n[build-docs.sh:240-261]"]
end
    
 
   CollectEnv --> ValidateREPO
 
   CollectGit --> ValidateREPO
 
   CollectTime --> InvokeProcessor
    
 
   ValidateREPO --> ExtractParts
 
   ExtractParts --> ApplyDefaults
 
   ApplyDefaults --> ConstructURLs
 
   ConstructURLs --> InvokeProcessor
    
 
   InvokeProcessor --> SubstituteVars
 
   SubstituteVars --> EvalConditionals
 
   EvalConditionals --> StripComments
    
 
   StripComments --> HeaderHTML
 
   StripComments --> FooterHTML
    
 
   HeaderHTML --> InjectFiles
 
   FooterHTML --> InjectFiles

Variable Processing Pipeline

The following diagram shows how variables flow through the processing pipeline:

Sources: scripts/build-docs.sh:8-51 scripts/build-docs.sh:195-261

Usage Syntax

Variable Substitution

Variables are referenced in templates using double curly braces:

At render time, this becomes:

Sources: templates/README.md:12-15

Conditional Blocks

Variables can be tested for existence using conditional syntax:

If GIT_REPO_URL is set, the link is rendered. If not set or empty, the entire block is omitted.

Sources: templates/README.md:17-22

Multiple Variables

Multiple variables can be combined in a single template:

Sources: templates/README.md:60-68

Implementation Examples

Badge Link Generation

The default templates use variables to generate badge links. Here’s a typical pattern:

This generates clickable badge images linking to both DeepWiki and GitHub, but only if the URLs are configured.

Sources: templates/README.md:30-39

Footer Timestamp

The footer typically includes the generation timestamp:

With GENERATION_DATE="December 25, 2024 at 14:30 UTC", this renders as:

Sources: templates/README.md:70-76

Environment Variable Override

All template variables can be overridden via environment variables when running the Docker container:

This allows full customization without modifying template files.

Sources: scripts/build-docs.sh:21-26

Variable Validation

Only REPO is strictly required. The build will fail if it cannot be determined:

All other variables have sensible defaults and can be omitted.

Sources: scripts/build-docs.sh:33-38

Variable Storage During Build

After processing, the rendered HTML is stored in shell variables:

• HEADER_HTML contains the processed header template
• FOOTER_HTML contains the processed footer template

These are then injected into each markdown file during the copy operation scripts/build-docs.sh:240-261

Sources: scripts/build-docs.sh:205-234 scripts/build-docs.sh:240-261

Dismiss

Refresh this wiki

Enter email to refresh