# Advanced Syntax

> Any HTML element, a page's own styles and scripts, math, Mermaid diagrams and project components.

## 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 H2O.

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](/authoring/rich-elements/#theme-tokens) 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:

**HTML**

```html
<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>
```

**Markdown**

```md
---
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](#included-documents).

## 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:

**HTML**

```html
<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>
```

**Markdown**

```md
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:

**HTML**

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

**Markdown**

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

$$
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](https://mermaid.js.org) 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.

**HTML**

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

**Markdown**

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

Renders as:

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

**HTML**

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

**Markdown**

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

Renders as:

```mermaid
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
      - disclaimer.css

- guide.html

**HTML**

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

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

**Markdown**

```md
<!-- .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](/customization/overriding-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.

**HTML**

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

**Markdown**

```md
::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:

**HTML**

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

**Markdown**

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

Renders as:

**build.ts**

```typescript
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`.