Advanced Syntax

HTML Blocks

A page is HTML, so every element works directly. Common examples include <kbd> for keyboard shortcuts, <sup>/<sub> for superscripts and subscripts, and <details>/<summary> for accordions.

Press <kbd>Ctrl</kbd> + <kbd>C</kbd> to copy. Water is H<sub>2</sub>O.

Renders as: Press Ctrl + C to copy. Water is H₂O.

Prefer semantic elements to classes and inline style: the theme styles the elements themselves, and that is what keeps every page looking like the same site. To change the look site-wide, override a theme token instead.

MDX Rendering

There is no templating language: what a page needs beyond HTML comes from its own <head>. A page's <link>, <style> and <script> are kept and added to the layout's head, after the theme:

<title>Version</title>
<script type="module">
  document.querySelector("#version").textContent = "2.0.0"
</script>

<h1>Version</h1>
<p>The current version is <strong id="version"></strong>.</p>

---
title: Version
---

<script type="module">
  document.querySelector("#version").textContent = "2.0.0"
</script>

# Version

The current version is <strong id="version"></strong>.

This is an escape hatch for advanced use cases. For markup shared between pages, use a project component.

LaTeX Expressions

LaTeX between dollar signs is rendered to MathML at build time, which browsers draw natively, with no script or web font. Single dollars are inline, double dollars a centered block:

<p>Inline: $E = mc^2$, with $x$, $\alpha$ or $\sum_{i=1}^{n} i$.</p>
<p>$$\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}$$</p>

Inline: $E = mc^2$, with $x$, $\alpha$ or $\sum_{i=1}^{n} i$.

$$
\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}
$$

Renders as:

Inline: $E = mc^2$, with $x$, $\alpha$ or $\sum_{i=1}^{n} i$.

$$\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}$$

$$f(x) = \frac{1}{\sigma\sqrt{2\pi}} e^{-\frac{(x-\mu)^2}{2\sigma^2}}$$

Matrices and aligned equations:

$$\begin{pmatrix} a & b \\ c & d \end{pmatrix} \begin{pmatrix} x \\ y \end{pmatrix} = \begin{pmatrix} ax + by \\ cx + dy \end{pmatrix}$$

A dollar sign is math only around something that looks like it: the opening one is followed by a non-space, and the closing one follows a non-space and is not followed by a digit. So prices, as in "it costs $5 and $10", stay text, and \$ is always a plain dollar sign. A $$ pair must sit in one element. Code, links and data-literal elements are left alone.

<htmlpress-math> writes the same without dollars; display makes it a block:

<htmlpress-math display>a^2 + b^2 = c^2</htmlpress-math>

$$
a^2 + b^2 = c^2
$$

Invalid LaTeX fails the build with the parser's message. The page's Markdown copy keeps the $…$ source. A page can still write MathML by hand.

Mermaid Diagrams

A <pre><code class="language-mermaid"> block holds Mermaid source, drawn in the current theme and redrawn when the theme changes. Escape < and & in the source. The library loads from jsDelivr only on a page that has a diagram; offline, the source shows instead.

<pre><code class="language-mermaid">flowchart LR
  pages[HTML pages] --&gt; build[htmlpress build] --&gt; site[Static site]</code></pre>

```mermaid
flowchart LR
  pages[HTML pages] --> build[htmlpress build] --> site[Static site]
```

Renders as:

flowchart LR
  pages[HTML pages] --> build[htmlpress build] --> site[Static site]

<pre><code class="language-mermaid">pie title Languages
  "Rust" : 45
  "TypeScript" : 30
  "Python" : 15
  "Other" : 10</code></pre>

```mermaid
pie title Languages
  "Rust" : 45
  "TypeScript" : 30
  "Python" : 15
  "Other" : 10
```

Renders as:

pie title Languages
  "Rust" : 45
  "TypeScript" : 30
  "Python" : 15
  "Other" : 10

Included Documents

A project component shares markup between pages. A file at .htmlpress/components/<name>/<name>.html fills every <htmlpress-<name>> in every page at build time:

<!-- .htmlpress/components/disclaimer/disclaimer.html -->
<aside><p>Provided as-is, without warranty.</p></aside>

<!-- guide.html -->
<htmlpress-disclaimer></htmlpress-disclaimer>

<!-- .htmlpress/components/disclaimer/disclaimer.html -->
<aside><p>Provided as-is, without warranty.</p></aside>

<!-- guide.md -->
::disclaimer

• Its .css and .js load only on pages where the tag appears; the tag stays around the pasted markup, so its CSS scopes to the tag, @scope (htmlpress-disclaimer).
• The folder is the tag without its htmlpress- prefix, the same as a built-in's: a folder named for a built-in component, such as tabs, replaces it.

See Overriding and Escaping for every file under .htmlpress/.

<htmlpress-include src="…"> pastes another file in by its path, relative to the page (or the project with a leading /): an .html file's body, a .md file rendered (its frontmatter dropped), or any other file as a code block titled with its name and highlighted by its extension.

<htmlpress-include src="../includes/disclaimer.md"></htmlpress-include>

::include{file="../includes/disclaimer.md"}

Renders as:

Disclaimer. Htmlpress is provided as-is, without warranty. This note lives in rust/docs/includes/disclaimer.md and is included, not copied, into this page.

A code file takes the code block attributes, such as data-lines, data-line-numbers or data-title, which replaces the file name:

<htmlpress-include src="../includes/build.ts" data-lines="3"></htmlpress-include>

<htmlpress-include src="../includes/build.ts" data-lines="3"></htmlpress-include>

Renders as:

import { build } from "htmlpress"

const report = await build("docs")
console.log(`built ${report.pages} pages`)

• Includes nest up to five levels, and one page expands at most 1,000 of them or 16 MB. A missing file, a cycle, or a path that leaves the project, or names a dot-file, node_modules or .htmlpress, fails the build: an included file is published.
• Keep partials out of the site with exclude, as this site does with exclude: rust/docs/includes/**; an .html partial would otherwise be a page too.
• The page's "Edit on GitHub" link and updated date stay its own; editing an included file rebuilds the page under htmlpress start.