Writing pages

Raw Markdown View this page on GitHub

Writing pages

Pages are GitHub Flavored Markdown. If a page reads well on GitHub, it reads well on the site.

Front matter

A page can start with YAML front matter between 2 lines of ---:

---
title: Install
suggested: true
---
Key What it does
title Replaces the level 1 heading in the navigation and the browser tab.
suggested true offers the page in the search before you type.
source Shows another Markdown file in place of the page, as ../../CHANGELOG.md. The file stays where it is.
url Makes the entry a link to another site, as an API reference. Needs title.

The README.md of the docs folder also holds the site settings. The reference lists every key.

Write links relative to the file, as you would for GitHub:

docs/2-guide/2-writing.md
- [Images and video](3-media.md), a page
- [Size and themes](3-media.md#size-and-themes), a heading of another page
- [Callouts](#callouts), a heading of this page
- [Introduction](../), the `README.md` of a folder
- [License](../../LICENSE), a file of the repository

docpages resolves and checks each link:

  • A link to the Markdown file of a page opens the page.
  • A link to a folder opens the page of its README.md.
  • A link to any other file of the repository opens the file in the repository. With -serve, it opens the file in your working tree instead, which includes changes you haven't pushed.
  • A link to a file or a folder that doesn't exist fails the build.
  • A link to a heading, as 1-install.md#windows, must name a heading of that page, or the build fails.

Images and videos take paths the same way. See Images and video.

Warning

GitHub and docpages make different IDs for headings with _ or letters outside ASCII. A link to such a heading can work on GitHub and fail the build.

Formatting

Text formats as on GitHub:

**Bold**, *italic*, ~~struck through~~ and `code`. A URL becomes a link: https://github.com/romshark/docpages.

Press <kbd>Ctrl</kbd>+<kbd>K</kbd> to search. H<sub>2</sub>O, x<sup>2</sup> and <ins>inserted</ins> text.<br>A line break.

An emoji by its name: :rocket: :tada: :+1:

- A list
  - with a nested item
- [x] A done task
- [ ] An open task

1. A numbered list
2. that counts on

| Flag | Default |
| --- | --- |
| `-o` | `site` |

> A quote

---

Bold, italic, struck through and code. A URL becomes a link: https://github.com/romshark/docpages.

Press Ctrl+K to search. H2O, x2 and inserted text.
A line break.

An emoji by its name: 🚀 🎉 👍

  • A list
    • with a nested item
  • A done task
  • An open task
  1. A numbered list
  2. that counts on
Flag Default
-o site

A quote


Of the HTML for text, pages keep <kbd>, <sup>, <sub>, <ins> and <br>, without attributes. See The HTML that pages keep.

An emoji name stays text if GitHub doesn't know it, or shows it as an image, as :octocat:.

Footnotes

A reference, as [^gfm], links to its footnote. The page lists the footnotes at its end, each with a link back:

Pages are GitHub Flavored Markdown[^gfm], and the search[^search] splits them at their headings.

[^gfm]: See the [specification](https://github.github.com/gfm/).
[^search]: Press `/` or `Ctrl+K` to open it.

Pages are GitHub Flavored Markdown1, and the search2 splits them at their headings.

The footnotes of this example are at the end of this page. A footnote that no reference names stays out.

Code

Code blocks are highlighted and have a copy button. Add title="..." after the language for a title bar:

```go title="main.go"
package main
```

The word after the opening fence picks the language, as on GitHub, from the languages that Chroma supports. A block without one stays plain. A language that Chroma doesn't know fails the build. Some examples:

main.go
package main

import "fmt"

// main greets the docs.
func main() {
	name := "docs"
	fmt.Printf("Hello, %s!\n", name)
}
build.py
import subprocess

def build(out: str = "site") -> None:
    """Builds the docs into out."""
    subprocess.run(["docpages", "-o", out, "docs"], check=True)

if __name__ == "__main__":
    build()
search.ts
interface Result {
  title: string;
  url: string;
}

export async function search(query: string): Promise<Array<Result>> {
  const res = await fetch(`/search?q=${encodeURIComponent(query)}`);
  return res.ok ? res.json() : [];
}
main.rs
fn main() {
    let pages = vec!["install", "usage"];
    for (i, page) in pages.iter().enumerate() {
        println!("{}. {page}", i + 1);
    }
}
pages.sql
SELECT title, url
FROM pages
WHERE suggested = TRUE
ORDER BY title;
package.json
{
  "name": "my-docs",
  "private": true,
  "scripts": {
    "docs": "docpages -serve 127.0.0.1:7340 docs"
  }
}

Callouts

GitHub alerts become callouts, each kind with its own color and title:

> [!NOTE]
> The search runs in the browser, with no server.

> [!TIP]
> Preview your docs with `docpages -serve`.

> [!IMPORTANT]
> Every page needs a level 1 heading or a `title`.

> [!WARNING]
> A build first deletes what the last build wrote in `site/`:
>
> - The version folders, as `main/` and `v1.2/`
> - `index.html`, `llms.txt`, `sitemap.xml` and `404.html`
>
> Keep **files of your own** out of these. See [Deploy](9-deploy.md#build-in-ci).

> [!CAUTION]
> Deleting the tags of a release removes it from the site.

Note

The search runs in the browser, with no server.

Tip

Preview your docs with docpages -serve.

Important

Every page needs a level 1 heading or a title.

Warning

A build first deletes what the last build wrote in site/:

  • The version folders, as main/ and v1.2/
  • index.html, llms.txt, sitemap.xml and 404.html

Keep files of your own out of these. See Deploy.

Caution

Deleting the tags of a release removes it from the site.

Details

A <details> hides its text until you click its <summary>. Write the text in Markdown between blank lines, as on GitHub. It holds what a page holds: formatting, lists, code blocks, callouts and other <details>.

<details>
<summary>Install from source</summary>

Clone the repository and **install** the command:

```sh
git clone https://github.com/romshark/docpages
cd docpages
go install ./cmd/docpages
```

> [!TIP]
> `go install github.com/romshark/docpages/cmd/docpages@latest` needs no clone.

</details>
Install from source

Clone the repository and install the command:

git clone https://github.com/romshark/docpages
cd docpages
go install ./cmd/docpages

Tip

go install github.com/romshark/docpages/cmd/docpages@latest needs no clone.

<details open> starts open:

<details open>
<summary>The <code>-o</code> flag</summary>

- Writes the site into a folder
- Defaults to `site`

</details>
The -o flag
  • Writes the site into a folder
  • Defaults to site

Its height grows and shrinks as it opens and closes. The <summary> keeps its text and <code>, <b>, <strong>, <i> and <em>. Markdown in it stays as written, as on GitHub, so write <code> there and not backticks. A <details> without a <summary> first, or without its end, fails the build.

Diagrams

A mermaid code block becomes a diagram. The browser loads Mermaid from a CDN, only on pages with a diagram.

```mermaid
flowchart LR
    A[Markdown files] --> B[docpages] --> C[Static site]
```
flowchart LR
    A[Markdown files] --> B[docpages] --> C[Static site]

A diagram takes the colors of style.css in both themes, and the font of the text. --bg-card fills its boxes, --accent draws their borders, --text-muted draws its lines and --text writes its text.

To change 1 diagram, give it front matter with theme: base and the theme variables to change. Mermaid ignores them without theme: base. The other colors stay those of the page.

A color written as light-dark(), or as var() of a color property, follows the theme. GitHub doesn't draw a diagram with such a color, as its Mermaid takes neither.

```mermaid
---
config:
  theme: base
  themeVariables:
    primaryColor: "light-dark(#fde68a, #6e5902)"
    primaryTextColor: "var(--text)"
---
flowchart LR
    A[Markdown files] --> B[docpages] --> C[Static site]
```
---
config:
  theme: base
  themeVariables:
    primaryColor: "light-dark(#fde68a, #6e5902)"
    primaryTextColor: "var(--text)"
---
flowchart LR
    A[Markdown files] --> B[docpages] --> C[Static site]

Math

Math is TeX. The browser typesets it with KaTeX, which it loads from a CDN, only on pages with math.

The area of a circle is $\pi r^2$, and $`\sqrt{2}`$ is about 1.41.

$$
\sum_{k=1}^{n} k = \frac{n(n+1)}{2}
$$

```math
e^{i\pi} + 1 = 0
```

The area of a circle is \pi r^2, and \sqrt{2} is about 1.41.

\sum_{k=1}^{n} k = \frac{n(n+1)}{2}
e^{i\pi} + 1 = 0
  • $...$ holds math in a line of text. Its TeX neither starts nor ends with a space, and no digit follows the closing $, so $5 and $10 stays text.
  • $`...`$ holds math too, without the rules of $...$ on spaces and digits.
  • $$...$$ in a paragraph shows its math on a line of its own.
  • A block between 2 lines of $$, and a math code block, show their math on lines of their own.

A price, as $5, starts math when a later $ in the paragraph closes it. Write \$5 then. KaTeX shows TeX that it can't read in red, in place of the math. The build doesn't check TeX.

"On this page" lists the headings down to level 4. When 2 headings below level 2 share their text, as a "Flags" heading under each command, the list stops above their level so it doesn't repeat itself.

The search splits each page at those headings. Press / or Ctrl+K to search. A result holds every word that you type as the start of one of its words, so conf finds "configuration" but go doesn't find "Logo". Case and accents don't count, and matches in headings come first.


  1. See the specification. ↩︎

  2. Press / or Ctrl+K to open it. ↩︎