Site generator

How this site is built¶

This site is fully static. There is no database, no wiki engine and no content management system: every page is a plain Markdown file with front matter in the content/ tree, and a single Python script turns that into HTML.

• Build: python3 generate.py - wipes and rebuilds site/
• Preview: python3 -m http.server 8001 --bind 127.0.0.1 from site/
• No external dependencies, standard library only

The current version of the script is attached to this page, so you can read exactly what produced the page you are looking at. Every content page also links its own raw Markdown source at the bottom (index.txt, the successor of the old Trac "Download in other formats: Plain Text").

Styling inspiration¶

• The old Trac instance at rickvanderzwet.nl/trac/personal: the red links with dotted underline, the uppercase pill navigation, the yellow floating table of contents
• The FreeBSD Handbook (docs.freebsd.org): the dark code blocks with subtle syntax colors, the light blocks for plain command output and the admonition boxes
• A modern twist of our own: the card grid on the homepage, the heading anchors, the version stamp in the footer

Syntax reference¶

A page is a directory under content/ with an index.md and optional files under attachments/. Everything the generator understands is listed below. Emphasis with _ is deliberately not supported.

Front matter¶

The block between --- markers at the top of index.md:

Inline formatting¶

Headings¶

## Heading level 2
### Heading level 3

Renders as real headings; every heading gets an anchor link (#) on hover and the slug id used by the table of contents.

Lists¶

- unordered item
- item wrapped over
  multiple lines
  - nested item
1. ordered item
2. second item

Renders as:

• nested item

• unordered item
• item wrapped over multiple lines

1. ordered item
2. second item

Code blocks¶

Fenced code with a language gets syntax coloring. A `sh-block with prompt lines renders as a terminal session: <host># is the root prompt, $ the regular user.

```sh
build# truncate -s 6GB embedded.img
build# gpart create -s MBR $MD
```

Renders as:

build# truncate -s 6GB embedded.img
build# gpart create -s MBR $MD

Supported languages: sh (also bash, console, sh-session), python, c, diff and ini. A fenced block without language and without prompt lines renders as a light output block.

Tables¶

| Interface | Address |
|---|---|
| igb0 | 192.168.178.1 |
| wlan0 | 192.168.182.1 |

Renders as:

The first row is the header row. Tables without a header row are converted to a plain HTML table.

Blockquotes and rules¶

> Quoted text, for example from a mailing list.

---

Renders as:

Quoted text, for example from a mailing list.

Followed by a horizontal rule:

Admonitions¶

A paragraph starting with a keyword and a colon (or the bold variant) renders as a colored box:

Note: plain keyword
**Tip:** bold variant

Renders as:

Images and attachments¶

![alt text](attachments/photo.jpg)
![photo](attachments/photo.jpg){style="max-width:750px"}

Files in attachments/ next to index.md are copied to the site and listed automatically at the bottom of the page, with file size.

License¶

The content of this site is licensed under CC BY 4.0 - the successor of the old "BSDLike" documentation license. The build scripts themselves are BSD 2-Clause licensed. The full text of both lives in the LICENSE.md of the site repository.

Credits¶

Designed and maintained by Rick van der Zwet. The generator, the conversion of the old Trac content and this site were built in collaboration with Mistral Vibe (Mistral AI) as co-author.