MTML

Subtitle or decorative text

Preface

This article demonstrates all the features supported by the build script, including custom TOC, auto-extracted TOC, footnote system, tag categorization, code blocks, tables, and more.

For a detailed introduction to the build script itself, check out this Build Script Deep Dive.

First Section: Auto TOC and Custom TOC

If your article uses <font size="5"> as section headings, the build script will automatically extract them to generate a TOC directory^[1]. An anchor <a name="toc-N"> is automatically inserted before each heading, so the sidebar TOC links can jump directly to the right position.

If you include  at the top of the article, the build script will use the custom TOC instead^[2]. Each custom entry can be just a title (auto-assigned toc-N anchors), or you can specify anchors with the Title | anchor-name format.

If a custom TOC exists, you need to place  markers in the article to tell the build script where to insert anchors. Markers are replaced in order: the first marker corresponds to the first TOC entry, and so on.

This article demonstrates both approaches: the first two TOC entries use a custom TOC with  markers, while the remaining sections are auto-extracted from headings^[3].

Second Section: Footnote System Explained

Footnotes are essential tools for academic writing and long-form articles. This project's footnote system is entirely processed at build time and does not depend on JavaScript^[4].

Use [^number] in the body text to reference a footnote, and [^number]: content at the end of the article to define it. The build script does three things^[5]:

1. Replaces [^N] in the body with superscript numbers linked to anchors
2. Collects [^N]: definition at the end into a footnote area
3. Renders the footnote list at the bottom of the article, with each entry clickable to jump back to the reference point

Footnote definitions support two formats:

Format 1: With paragraph tags (recommended, supports line breaks)

<p> tag. This format supports line breaks — footnote content can be lengthy and may contain <code> tags, links, and other HTML elements. The build script correctly extracts the full multi-line content.

Format 2: Bare definition (single line)

notes. This format is limited to a single line.

Click the footnote number ^[8] in the body text to jump to the note at the bottom, then click the number on the left of the note to jump back^[8]. This is a standard anchor-based jump mechanism supported since the HTML 3.2 era.

Footnote Demo

Below demonstrates typical usage of footnotes in code and technical articles. The build script's version management follows several principles^[9]: manually run the build after each modification, use Git to track source files rather than output files, and use build.cmd as the unified build entry point.

The build process design also considers practicality^[10]. To learn more about the technical details of the build system, read the Build Script Deep Dive article.

Code and Tables

Core usage of the PowerShell build script:

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, anchor optional
Auto TOC	`<font size="5">`	Auto-extracted from headings
TOC Anchor Marker	`<!-- toc-anchor -->`	Jump target for custom TOC
Footnote Reference	`[^N]`	Superscript link in body text
Footnote Definition	`<p>[^N]: Content</p>`	With tags, supports line breaks
Tag Categorization	`<!-- tags: A, B -->`	Comma-separated, displayed in sidebar
Draft Marker	`<!-- draft: true -->`	Skipped by default build

For more details, refer to the scripts/build.ps1 source code in the project root directory.

[1]	Auto-extracted heading regex: `<font[^>]size="5"[^>]color="#ff66cc"[^>]*>`. The build script inserts anchors in reverse match order to ensure correct anchor placement.
[2]	Custom TOC entries are comma-separated, and each entry can optionally use the `Title \| anchor-name` format. If the anchor name is omitted, `toc-1`, `toc-2`, etc. are auto-assigned.
[3]	If a custom TOC exists and is non-empty, it takes precedence; otherwise, headings are auto-extracted. The two approaches are mutually exclusive and cannot be used simultaneously.
[4]	JavaScript may be unavailable or disabled on retro browsers (IE5.5, etc.). Pure HTML anchor-based navigation is an HTML 3.2 standard feature with the best compatibility.
[5]	Footnote processing in the build script is done in two steps: first, it matches definitions wrapped in tags like `<p>` (supporting multi-line); second, it matches bare definitions (single line). After both steps are complete, references are replaced and the footnote area is rendered.
[6]	This is a multi-line footnote example. This footnote spans multiple lines, containing Chinese, English mixed content, `inline code`, and inline styles. This is very practical when writing long notes without cramming everything into one line.
[7]	Bare definitions are not wrapped in tags and are limited to a single line. Suitable for brief notes.
[8]	The `[^8]` mentioned in the body is itself a footnote reference. This sentence appears in the body text — click it to jump to this note at the end, then click the number to jump back. This is the "self-referential demo" of the footnote system.
[9]	The build script is run manually after each modification, and Git tracks source files rather than the `dist/` output directory. This keeps the output directory clean and ensures each build is deterministic.
[10]	Single-page builds only replace placeholders without scanning the blog directory, making them very fast. If you add a new article, you need to run `generate-archive.ps1` first to update the latest-posts component, then run `build.ps1`.

« Home