Skip to main content

pandoc/sourcecode.html5

The sourcecode.html5 template is a stripped-down Pandoc HTML5 template used specifically for generating syntax-highlighted previews of source code files.

Pathtemplate/pandoc/sourcecode.html5
LanguageHTML5/Pandoc
Lines38

Read this when Use this page when tracing the HTML/Pandoc templates and include fragments that shape rendered gwern.net pages around pandoc/sourcecode.

Overview​

The sourcecode.html5 template is a stripped-down Pandoc HTML5 template used specifically for generating syntax-highlighted previews of source code files. Unlike the full default.html Hakyll template, this template provides minimal scaffolding - just enough HTML structure to display Pandoc's syntax-highlighted code with proper styling.

This template is used when gwern.net needs to display raw source code files (e.g., linking to .js, .py, .hs files) in a readable, syntax-highlighted format rather than as plain text. The template relies on Server-Side Includes (SSI) to inject shared CSS resources via /static/include/inlined-standalone.html, ensuring consistent styling with the rest of the site.

The template is intentionally minimal to keep the focus on the code itself. It includes basic metadata (author, date) support from Pandoc variables but doesn't include the full metadata apparatus of default.html.

Key Variables/Blocks​

Metadata Variables​

  • $pagetitle$: Page title (the file path, set via --metadata title= in sync.sh), displayed as "$pagetitle$ (syntax-highlighted preview)"
  • $author-meta$: Optional author metadata (loops with $for(author-meta)$)
  • $date-meta$: Optional date metadata

Conditional Blocks​

  • $if(dir)$ dir="$dir$"$endif$: Text direction attribute for internationalization
  • $if(date-meta)$: Conditionally includes Dublin Core date metadata

CSS/Asset Loading​

  • $for(css)$: Loops through CSS files to include
    • Each CSS file rendered as: <link rel="stylesheet" href="$css$">
  • SSI block: <!--#include virtual="/static/include/inlined-standalone.html" -->
  • Provides inlined color CSS plus external head.css/style.css links (no JS)
    • Ensures syntax highlighting styles are available

Content Block​

  • $body$: Pandoc-generated syntax-highlighted HTML
    • Contains the actual code with <pre><code> structure
    • Pandoc applies language-specific CSS classes for highlighting

Usage​

This template is invoked by Pandoc (not Hakyll), from the syntaxHighlight shell function in build/sync.sh (~line 640). That function wraps the first 2000 lines of each source file in a fenced code block tagged with a language derived from the file extension, then pipes it through Pandoc:

# Actual usage in build/sync.sh (simplified)
... | pandoc --from=markdown+smart --write=html5 --standalone \
        --template=./static/template/pandoc/sourcecode.html5 \
        --metadata title="$FILE" \
        >> $FILE.html

Files longer than 2000 lines are truncated with a "[File truncated due to length…]" notice linking to the original, and Pandoc/skylighting's per-line self-link anchors are stripped with sed afterward. This is run over _site/ for extensions such as .R, .c, .css, .hs, .js, .py, .sh, .php, .md, .txt, .json, .xml, etc.

The template is specifically designed for:

  1. Source file previews: Making .js, .hs, .py, .sh files viewable in-browser with syntax highlighting
  2. Code snippet pages: Standalone pages that are just code (no prose)
  3. Embedded code viewers: Content transcluded into popups or iframes

Body Class Convention​

The template applies a special body class file-preview-source-code to distinguish these pages from regular content pages. The template's own inline <style> block uses it to handle very wide source lines (which render badly in popups):

body.file-preview-source-code { max-width: none; }
body.file-preview-source-code .sourceCode pre,
body.file-preview-source-code .sourceCode pre code {
    white-space: pre-wrap;
    overflow-wrap: anywhere;
    tab-size: 4; }
See Also