1. Docs
2. Writing

Markdown

Headings, links, code blocks, tables and images, and what Vitrine adds to each.

Vitrine uses Hugo’s Markdown (CommonMark with GitHub’s extensions: tables, task lists, strikethrough). A few elements get extra behaviour through Hugo’s render hooks.

Headings#

Start a page’s chapters at ##; the page’s title is its #. Every ## starts at a thin rule. Headings get a # link to themselves, shown on hover, so readers can link to a chapter. ## and ### headings are listed in “On this page”.

Links#

[Installation](/docs/getting-started/installation/)
[a chapter on this page](#code-blocks)
[the config file](hugo.toml)
[Hugo](https://gohugo.io/)

• A link to a page, written as its path in content/, becomes that page’s address. It works with or without the trailing slash, and keeps working if your site lives under a subpath like example.org/docs/.
• A link to a file next to the page (in its page bundle) becomes the file’s address.
• A path from the site’s root to a file in static/ gets the site’s base path.
• A link to another site opens in a new tab, and screen readers hear “opens in a new tab”.

Code blocks#

Fenced code gets a head with its language and a copy button:

const answer = 42;

Name the file instead of the language with file:

```js {file="script.js"}
const answer = 42;
```

const answer = 42;

Hugo’s highlighting options work as usual, for example highlighted lines and line numbers:

```go {hl_lines=[2] linenos=true}
func main() {
	fmt.Println("hello")
}
```

1
2
3

func main() {
	fmt.Println("hello")
}

Inline code like npm install gets a light box.

Tables#

A table wider than the column (on a phone, say) scrolls sideways in its own box, so the page doesn’t. Long code in a cell may break on narrow screens. Align a column with colons in the separator row (|---:| for right).

Quotes, lists and images#

A quote is set off by a rule on its left.

Lists and task lists work as on GitHub:

• write the docs
• publish them

Images in Markdown are shown at most as wide as the column. Put them next to the page in its folder and link them by name: ![The settings dialog](settings.png). Always write the alt text.