~/tilder/, Documentation/, Reference/, The Markdown reference/, Blocks

blocks - paragraphs, lists, boxes, code, tables and comments

A block is a run of lines between two blank lines: a paragraph, a list, a box, a code block, a table. Each construct below is given as source, then rendered under a dashed frame marked Rendered, exactly as that source renders on any page of the site.

Consecutive lines make one paragraph, joined by spaces; a blank line ends it. Words in braces at the end of a paragraph are classes, applied on the web page only: the text mirror prints the paragraph plain.

The build joins these two lines
into one paragraph.

A small, muted line. {small muted}

A faint line. {faint}

A line in the monospace font. {mono}

A line in the warning colour. {warn}

small, muted, faint, mono and warn are the classes every theme is expected to style (classes). Any other word in the braces becomes a class too, for a theme that styles it. A {#id} there is dropped: a paragraph has no id.

A paragraph wrapped entirely in single asterisks is an empty state: the muted, monospace line that says something is not there yet. A list with nothing in it shows the same line.

*No talk announced yet.*

The asterisks must open and close the whole paragraph. With text after the closing asterisk, *Soon.* Check back later. is an ordinary paragraph that begins in italics. A paragraph entirely in bold also starts and ends with asterisks: it becomes an empty state, its text in italics. Keep bold for words inside a sentence.

A line starting with - or * is a bulleted item; 1. or 1) starts a numbered one. A numbered list starts at its first number: 7. then 8. counts from 7. Indent an item further than the one above to nest a list inside it. An indented line that is not an item carries on the item above it.

1. Copy the starter site
2. Build it, then keep it rebuilding
   while you write
   - `python3 builder/build.py`
   - `python3 builder/build.py --watch`
3. Write the first page

In the text mirror, each item is indented two spaces, as - item or 1. item, and its wrapped lines and nested lists align under the item's text.

A list does not follow a paragraph without a blank line: the list's lines would carry on the paragraph. And right after a ### heading, a list is the entry's meta line, not a list.

[ ] or [x] right after an item's marker makes a task: an empty box, or a checked one. Screen readers hear labels.task_todo or labels.task_done for the box ("to do", "done").

- [x] move the blog into folders
- [ ] write the first report

The text mirror prints the boxes as text: - [x] item, - [ ] item.

[TOC] alone on a line lists the page's sections, each one linking to its section. On the web page, it is a <nav> named by labels.toc, folded by default in a <details> that opens without any script. In the text mirror it is a numbered list of the section names. Each output lists only the sections it shows (sections).

[TOC]

[toc] works too, in any case. Put it where the contents should appear, near the top of a long page. This page has one under its ## Name; on a wide screen, this site's theme moves the first table of contents of a documentation page into the right-hand column.

---, *** or ___ alone on a line, between blank lines, draws a rule: <hr> on the web page, a line of dashes in the text mirror. At the very top of a file, --- opens the front matter instead.

Above the rule.

---

Below the rule.

Every line of an inset starts with >. It is drawn as a box on the web page, and indented in the text mirror. A line holding only > separates two paragraphs. An inset holds paragraphs, with inline markup: a list or a code block inside it is read as text.

> **Note:** the [archive ↗](https://archive.example.org/) keeps older posts.
>
> A second paragraph.

The pages of this reference use insets to frame the live examples of inline markup.

An inset whose first line is [!INFO], [!WARNING] or [!ERROR] is a callout, in GitHub's syntax. Text may follow the marker on the same line. GitHub's other names are accepted, in upper or lower case.

> [!INFO]
> The build runs again at midnight.

> [!WARNING]
> Never edit `public/` by hand: the next build replaces it.

> [!ERROR] A missing `title:` stops the build.

On the web page, a callout is a box with a coloured rule on its left and its label, marked role="note" for screen readers. In the text mirror it is a box drawn in ASCII, the label in its top rule, and coloured by kind in the ANSI mirror:

+- WARNING --------------------------------------------------------+
| Never edit public/ by hand: the next build replaces it.          |
+------------------------------------------------------------------+

The labels come from [labels] in site.toml, so they follow the page's language. Any other word, [!NOTICE] say, leaves an ordinary inset that begins with the marker as written.

A code block opens with a fence of three backquotes and closes with another. A language name right after the opening fence turns on syntax highlighting, done by the build (no script), and shows the language in the block's corner. The block keeps its spacing exactly, and a long line scrolls sideways instead of widening the page.

```python
def fold(text, width=75):
    return textwrap.wrap(text, width)
```

def fold(text, width=75):
    return textwrap.wrap(text, width)

To show a fence inside a code block, as the source above does, open the outer block with more backquotes: a fence of four closes only on a line of four or more.

The name may be written in any case; the label shows it in lower case, as written: caddy, not conf. jsonc is JSON with // and /* */ comments, such as VS Code's settings; kyaml is Kubernetes' strict YAML subset, flow style and quoted values. Five languages are read line by line rather than word by word:

• console: a line starting with a prompt, $ or # , possibly after a user and a host, is a command and is highlighted as shell; any other line is output, left plain.
• diff: added lines and removed lines are coloured apart, hunk headers muted.
• markdown: this dialect - front matter keys, headings and their {markers}, fences (a fenced block's own code is left plain), comments, rules, quotes and [!KIND] callouts, [TOC], list markers and task boxes, tables, and inline markup - code, emphasis, a link's or an image's target - within every line. Most of the source blocks of this reference are markdown blocks.
• text: no highlighting at all, but the label is shown.

```console
$ python3 builder/build.py
built public/
```

```diff
-nav = "blog"
+nav = "blog/"
```

$ python3 builder/build.py
built public/

-nav = "blog"
+nav = "blog/"

A block with no language has no label and no highlighting. A language tilder does not know prints a build warning and leaves the block plain.

If the theme ships code.js, as this one does, every code block gets a button that copies its code as plain text, worded by labels.copy and labels.copied; the script is loaded only on pages with code (scripts). In the text mirror, the block is framed by two rules, the language in the top one, and nothing is added to its lines, so they copy clean from a terminal: they are only folded to ASCII, tabs expanded to four spaces. A line longer than the mirror's 75 columns is cut and continued on the next one, the cut marked with \. In the coloured mirror, ansi/, a block in a language above (text and an unknown language excepted) is highlighted too, each token in its kind's colour, the same rules as the HTML; txt/ stays plain either way (the text mirror):

.-- python --------------------------------------------------------.
  def fold(text, width=75):
      return textwrap.wrap(text, width)
'------------------------------------------------------------------'

Pipes separate the cells; the second line, of dashes, separates the header from the rows. Colons in that line set each column's alignment: :--- left, the default, :---: centred, ---: right. Inline markup works in the cells, and \| writes a pipe inside one. Every line of the table starts with |: a line without one turns the block into a paragraph.

| Output | Format | Width |
|:-------|:------:|------:|
| page   | HTML   | any   |
| mirror | ASCII  | 75    |
| `a \| b` | text | 5 |

The pipes need not line up, and each line of dashes needs at least three. A row has as many cells as the header: a missing cell is empty, an extra one is dropped. On the web page, a table wider than the column scrolls inside its own frame, named by labels.table for screen readers. In the text mirror it becomes padded columns; when those do not fit in 75 columns, each row becomes a record of Header: value lines.

A block starting with <!-- is copied into the web page as it is, where the browser does not show it, and left out of the text mirror. Use it for notes to the people who edit the page, such as a fact still to find:

<!-- TO FILL: the venue's address. -->

*Venue to be announced.*

The comment says what is missing, the empty state tells the reader. The whole block, down to the next blank line, is copied as it is: leave a blank line after the comment.

• sections
• entries
• the text mirror
• classes