Template System

Loading…

Template System

Relevant source files

• python/process-template.py
• templates/README.md
• templates/footer.html
• templates/header.html

The template system provides customizable header and footer content that is injected into every markdown file during the build process. This system uses a simple variable substitution syntax with conditional rendering support, allowing users to customize the appearance and metadata of generated documentation without modifying the core build scripts.

For information about how templates are injected during the build process, see Template Injection. For comprehensive documentation on template variables, see Template Variables.

Sources: templates/README.md:1-77

Template Files

The system uses two HTML template files that define content to be injected into each markdown file:

Both templates are processed through the same variable substitution engine before injection.

Sources: templates/README.md:6-8 templates/header.html:1-9 templates/footer.html:1-11

Default Header Template

The default header template displays project badges and attribution information:

The template uses inline conditionals to prevent mdBook from wrapping links in separate paragraph tags, which would break the styling.

Sources: templates/header.html:1-9

Default Footer Template

The default footer template displays generation metadata and repository information:

Sources: templates/footer.html:1-11

Template Syntax

The template system supports three syntactic features: variable substitution, conditional rendering, and HTML comments.

Variable Substitution

Variables use double-brace syntax: {{VARIABLE_NAME}}. The processor replaces these with the corresponding variable value, or an empty string if the variable is not defined.

Variable names must match the pattern \w+ (alphanumeric and underscore characters).

Sources: python/process-template.py:38-45 templates/README.md:12-15

Conditional Rendering

Conditional blocks use {{#if VARIABLE}}...{{/if}} syntax. The content between the tags is included only if the variable exists and is non-empty.

The conditional pattern matches \{\{#if\s+(\w+)\}\}(.*?)\{\{/if\}\} and evaluates whether the variable is truthy.

Sources: python/process-template.py:24-36 templates/README.md:17-22

HTML Comments

HTML comments are automatically stripped from the output during processing:

Sources: python/process-template.py:47-48 templates/README.md:24-28

Template Processing Engine

Diagram: Template Processing Flow

Sources: python/process-template.py:1-82

The process-template.py script implements a two-pass processing algorithm:

1. Conditional Processing (first pass): Evaluates {{#if}} blocks using regular expression matching and removes or includes content based on variable truthiness python/process-template.py:24-36
2. Variable Substitution (second pass): Replaces {{VAR}} placeholders with actual values python/process-template.py:38-45
3. Comment Removal (cleanup): Strips HTML comments from the final output python/process-template.py:47-48

Command-Line Interface

The script accepts a template file path and variable assignments in KEY=value format:

Arguments are parsed at python/process-template.py:66-70 where each KEY=value pair is split and stored in a dictionary for substitution.

Sources: python/process-template.py:53-82

Available Template Variables

The following variables are provided by the build system and available in all templates:

All variables are optional. If a variable is undefined, it is replaced with an empty string during substitution.

Sources: templates/README.md:30-39

Customization

Diagram: Template Customization Architecture

Sources: templates/README.md:42-56

Volume Mount Customization

Custom templates can be provided by mounting a local directory or individual files into the Docker container:

Mount entire template directory:

Mount individual template files:

Sources: templates/README.md:45-51

Environment Variable Customization

Template locations can be overridden via environment variables:

Example:

Sources: templates/README.md:53-56

Integration with Build Process

Diagram: Template System in Build Pipeline

Sources: templates/README.md:1-77 Diagram 2 from high-level system architecture

The template system is invoked during Phase 3 of the build pipeline, after markdown files have been generated and enhanced with diagrams. The build-docs.sh orchestrator script processes each template file through process-template.py, then injects the processed content into every markdown file before generating SUMMARY.md and running mdbook build.

Template processing occurs in the following sequence:

1. Template Resolution : Determine paths to header and footer templates using environment variables or defaults
2. Variable Collection : Gather all template variables from environment and runtime context
3. Template Processing : Invoke process-template.py for each template file with collected variables
4. Content Injection : Prepend processed header and append processed footer to each markdown file
5. Build Continuation : Proceed with SUMMARY.md generation and mdBook build

This design ensures that all documentation pages share consistent branding, navigation, and metadata without requiring manual edits to individual markdown files.

Sources: templates/README.md:1-77

Example Custom Templates

Minimal Header Example

Sources: templates/README.md:60-68

Custom Footer Example

Sources: templates/README.md:70-76

Conditional Badge Example

This example demonstrates conditional rendering of badges based on available repository and documentation URLs. If neither GIT_REPO_URL nor DEEPWIKI_URL is defined, the template produces no output.

Sources: templates/header.html:2-4 templates/README.md:17-22

Dismiss

Refresh this wiki

Enter email to refresh