What to expect
This example article demonstrates all build script features, including
custom TOC entries,
automatic TOC extraction,
footnotes, tag metadata, code blocks, tables,
and more.
For a deeper look at the build script itself, see
the build script deep dive.
First section: automatic and custom TOC
If a heading uses
<font size="5" color="#ff66cc">, the
build script can extract it automatically into the TOC.
If the page starts with
<!-- toc: Title 1, Title 2 | anchor -->, the script uses the custom TOC definition first. Each entry can be a
title only or a title with a custom anchor.
Custom TOC entries require
<!-- toc-anchor --> markers in the
article body. Each marker is replaced in order: the first marker maps to the
first TOC item, the second to the second, and so on.
This article shows both a custom TOC entry and an automatically extracted
heading.
Second section: footnote system
Footnotes are an important feature for long technical articles. This system
is handled during build time and does not rely on JavaScript.
Use [^N] in the text for footnote
references, and define footnotes at the end with
[^N]: content.
The build script performs three steps: extract definitions, replace
references with anchor links, and render the footnote list at the bottom.
Format one: block footnote definition
<p> tag. Block footnotes support
multiple lines and can include code, links, or inline HTML.
Format two: single-line definition
line.
Footnote references like [8] jump to the
definition, and the footnote number links back to the source.
Footnote demo
The page footer contains a footnote area generated by the build script. It
is a live example of the link-based footnote workflow.
Code & table
Use this command to build a page:
powershell -ExecutionPolicy Bypass -File scripts/build.ps1 `
-PageName "blog-SLUG" `
-Title "Page title" `
-ContentFile "src/content/blog/content-SLUG.html"
Here is a table example:
|
Feature
|
Usage
|
Description
|
| Custom TOC |
<!-- toc: Title | anchor -->
|
Comma-separated items with optional anchor names
|
| Automatic TOC |
<font size="5" color="#ff66cc">
|
Extracted from headings automatically
|
| TOC anchor markers |
<!-- toc-anchor -->
|
Used for custom TOC targets
|
| Footnote ref |
[^N]
|
Superscript link in the text
|
| Footnote definition |
<p>[^N]: content</p>
|
Block definitions support multiple lines
|
| Tags |
<!-- tags: A, B -->
|
Comma-separated tags shown in the sidebar
|
| Draft flag |
<!-- draft: true -->
|
Skipped by default build
|
For more details, read the source code in
scripts/build.ps1.
| [1] | The title regex is
<font[^>]*size="5"[^>]*color="#ff66cc"[^>]*>. |
| [2] | Custom TOC uses commas and optional anchor names like
Title | anchor. |
| [3] | If a custom TOC exists, the build script uses it. Otherwise it falls
back to automatic extraction. |
| [4] | Pure HTML anchor navigation is the most compatible choice for retro
browsers. |
| [5] | The build script inserts TOC items and anchors by processing headings
in reverse order. |
| [6] | This is a footnote wrapped in a |
| [7] | This is a short, inline footnote definition that must stay on one |
