Writing pages

.md and .qmd files

A page can be a .md file or a .qmd file. smalldocs reads both in the same way. A .qmd file is a Markdown file that uses the additions above. The name .qmd comes from Quarto, and the additions come from the Markdown of Pandoc, as Quarto uses it. So name a page .qmd to show that it uses them. A Markdown viewer that does not know them, such as the file view of GitHub, shows them as plain text.

A page can also be a Jupyter notebook, a .ipynb file. See Notebooks.

Front matter

Front matter is a block of YAML between two --- lines at the top of a page. It holds the options of the page:

---
title: Writing pages
description: The Markdown that smalldocs reads.
order: 3
---

The title goes at the top of the page and in the sidebar. The configuration lists the other options.

Text

smalldocs changes some characters in text. To keep them as you type them, set the option from: markdown-smart:

Footnotes get numbers^[1]. Text can be struck out, and code keeps its own characters.

Term

A definition list gives each term its definition.

• A task list
• with boxes

Headings and attributes

Each heading has an id, so a link can point at it, as in config.qmd#globs. smalldocs makes the id from the text of the heading. The id is in lower case, with a - between the words. It keeps letters, digits, _, - and ., and it drops other punctuation and anything before the first letter. So ## A _quarto.yml gets the id a-_quarto.yml. Pandoc makes ids by the same rules, so a link written for Pandoc or Quarto still works.

To give your own id and classes, put them in braces:

## Install it {#install .important}

A link, a picture, a span and inline code take attributes too. A span is text in brackets with attributes after it. Write [text](url){.btn .btn-primary}, ![alt](pic.png){width="50%"} or [red]{.text-danger}. Here is a button and a span with a class.

Divs

A div is a block of the page with its own attributes. A line of three or more colons starts or ends a div. A line with attributes starts a div, and a line of colons only ends the innermost div. So divs can nest, with lines of the same length:

::: {.border .p-3}
Outer.

::: {.text-center}
Inner, in the centre.
:::
:::

Callouts

A callout is a box that sets off a note, a tip or a warning:

::: {.callout-note}
A note, with the default title.
:::

::: {.callout-tip}
## A tip with its own title
The first heading in a callout becomes its title.
:::

::: {.callout-warning title="Folded" collapse="true"}
This warning opens when you click its title.
:::

Tabs

A tabset is a group of tabs. In a div with the class panel-tabset, each heading becomes a tab:

def greet(name: str) -> str:
    "Say hello."
    return f"Hello, {name}!"

for name in Ann Bo; do echo "Hello, $name!"; done

Code

smalldocs colours code with Pygments, in the light theme and in the dark theme. See Themes. A copy button shows when the pointer is on the code. A filename goes above the code:

hello.py

import sys

def main() -> int:
    for arg in sys.argv[1:]:
        print(arg.upper())  # one line each
    return 0

A diff block shows a change to files, as git diff prints it. As on GitHub, smalldocs shows each removed line in red and each added line in green. The --- and +++ lines that name the files are red and green too. A hunk header, the line that starts with @@, is grey on a blue band. A diff --git or index line is grey and bold. The other lines keep their text as written, with the space at their start.

The names udiff and patch do the same. In a combined diff from a merge, smalldocs colours only the lines that start with + or -. Quarto and Pandoc colour a diff in the colours of strings and variables, and not in red and green.

--- a/hello.py
+++ b/hello.py
@@ -3,3 +3,3 @@
 def main() -> int:
-    for arg in sys.argv:
+    for arg in sys.argv[1:]:
         print(arg.upper())  # one line each

A code block whose fence names a language in braces, such as {python} or {r}, is a cell. A cell is code that is meant to run when the page is built, with its output in the page. smalldocs does not run code. It shows the cell as code, and the page shows no output. The build gives a warning for each page with cells.

A cell can start with option lines that begin with #|. smalldocs removes these lines. It hides the cell for #| echo: false or #| include: false. To hide every cell of a page, set echo: false in its front matter.

Raw HTML

HTML in the Markdown goes into the page unchanged. A block marked {=html} also goes in unchanged:

This paragraph came from a raw HTML block.

Figures

A picture alone in its paragraph becomes a figure, if it has alt text. The alt text becomes the caption:

Tables

A table has a row of headings, a row of dashes, and a row for each line of the table. A | goes between the cells:

smalldocs does not read the grid tables of Pandoc, which are drawn with + and -.

Maths

Inline maths goes between dollars, as in \(e^{i\pi} + 1 = 0\). Display maths goes between double dollars:

\[\int_0^1 x^2 \, dx = \frac{1}{3}\]

A dollar before a space or a digit is money, so the text "it costs $5 and \(10" stays as it is. With the option `from: markdown-tex_math_dollars`, in the front matter or in `_smalldocs.yml`, each `\)` is a dollar, and smalldocs draws no maths written with dollars. KaTeX, a JavaScript library, draws the maths. smalldocs loads KaTeX only on pages that have maths.

Diagrams

The JavaScript library mermaid.js draws a mermaid block. smalldocs loads it only on pages that have a diagram:

flowchart LR
  A[_smalldocs.yml] --> B(smalldocs render)
  C[pages] --> B
  B --> D[_site]

Shortcodes

A shortcode is a tag in double braces that smalldocs replaces before it reads the Markdown. smalldocs replaces these shortcodes everywhere except in code blocks:

To show a shortcode as it is, put /* and */ inside its braces. The left column of the table does so in its source.