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.
Links
Write links relative to the file, as you would for GitHub:
- [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
- Images and video, a page
- Size and themes, a heading of another page
- Callouts, a heading of this page
- Introduction, the
README.mdof a folder - 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
- A numbered list
- 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:
package main
import "fmt"
// main greets the docs.
func main() {
name := "docs"
fmt.Printf("Hello, %s!\n", name)
}
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()
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() : [];
}
fn main() {
let pages = vec!["install", "usage"];
for (i, page) in pages.iter().enumerate() {
println!("{}. {page}", i + 1);
}
}
SELECT title, url
FROM pages
WHERE suggested = TRUE
ORDER BY title;
{
"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/andv1.2/ index.html,llms.txt,sitemap.xmland404.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.
$...$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 $10stays 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 amathcode 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.
Contents and search
"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.
-
See the specification. ↩︎
-
Press
/orCtrl+Kto open it. ↩︎