Toaster

toaster is a static website generator that reads a structured directory of Markdown files and produces a directory of HTML files. It verifies all internal page and file links, and collates directories of static files. This website was generated using toaster.

Usage

To generate an HTML website using toaster, run the following command.

toaster --html <source> <destination>

source is the path to a directory containing Markdown files (as per the directory structure section below), and destination is the path to a directory in which the generated website will be saved.

Installation

Source code for toaster can be downloaded from code.benbridle.com/toaster.

The latest release is available at toaster-1.12.0 as a pre-compiled Linux executable.

Build from source

To build toaster from source, first install the Rust compiler from www.rust-lang.org/tools/install, then install the nightly toolchain with rustup toolchain install nightly, and then run cargo +nightly build --release inside the toaster source code directory.

The compiled binary will be created at ./target/release/toaster.

Directory structure

The structure of the source directory determines the structure of the generated website.

The following is an example source directory that demonstrates many of the file organisation features of toaster, followed by the contents of the destination directory after the website has been generated.

source/
├── +index.md
├── about.md
├── Photography/
│   ├── !images/
│   │   ├── Bird in field.jpg
│   │   └── Oak tree.jpg
│   ├── +index.md
│   ├── 2025-01-14 Trees.md
│   └── 2025-01-25 Riverside walk.md
├── Recipes/
│   ├── !images/
│   │   ├── Bread.jpg
│   │   └── Iced cake.jpg
│   ├── +index.md
│   ├── Carrot cake.md
│   └── Wholegrain bread.md
├── !static/
│   ├── print.css
│   └── screen.css
└── toaster.conf

destination/
└── source/
    ├── index.html
    ├── about.html
    ├── photography.html
    ├── recipes.html
    ├── photography/
    │   ├── riverside-walk.html
    │   └── trees.html
    ├── recipes/
    │   ├── carrot-cake.html
    │   └── wholegrain-bread.html
    ├── images/
    │   ├── Bird in field.jpg
    │   ├── Bread.jpg
    │   ├── Iced cake.jpg
    │   └── Oak tree.jpg
    └── static/
        ├── print.css
        └── screen.css

Site name

The name of the source directory is used as the name of the generated website. It will be visible as part of the tab name for every page of the website.

Pages

A markdown file denotes a page of the website. The markdown file will be converted to an HTML file, with the file name changed to a URL-safe format.

If the file name is prefixed with a string of digits and hyphens (used to affect the file sort order), that string will be discarded. The name of a page is given by the file name, minus the file extension and the aforementioned sort prefix.

Pages with the file name +index.md are index pages. The name of an index page will be the name of the parent directory, and the page will be moved one level higher when the website is generated. The root index file will be kept in the site root.

Static files

A directory prefixed with a ! character contains static files. All static directories with the same name are collated, and the resultant directory is moved to the site root. This allows files to be stored alongside the pages that use them, while also grouping all files of a similar type in a common location once the website is generated.

Configuration file

The source directory can contain a toaster.conf configuration file. This file is used to modify the behaviour of toaster, and is not included when the website is generated.

The file uses a rudimentary key-value format. Lines with no leading whitespace denote keys, and the set of non-key lines following a key are the value.

  • html.head
    The value of this key is copied unmodified into the <head> section of the HTML version of every generated page. Useful for defining site-wide CSS and Javascript files.

Markdown syntax

The Markdown syntax used by toaster departs from the defacto standard Markdown syntax in a few areas. Refer to the Markdown project page for the full syntax description.

The following sections describe Markdown behaviour specific to toaster.

Headings

Each page is generated with a top-level heading that has the same name as the page.

Internal links are used for linking to pages, or for linking to headings within pages. toaster validates that every page link resolves to a real page, and that every heading link resolves to a real heading in the target page.

Internal links are case-insensitive, so that the case of the link text can match the case of the surrounding text.

A heading link is an internal link that points to a heading on a page. The link will display as just the heading name, without the name of the target page.

An internal link in the form {Markdown#Paragraph} is a heading link that points to the Paragraph heading on the Markdown page.

An internal link in the form {#Paragraph} is a heading link that points to the Paragraph heading on the current page.

Page links

A page link is an internal link that points to a page. The link will display as just the page name, without any path information.

An internal link in the form {Markdown} is a page link that points to the Markdown page.

Page links are relative to the hierarchy of the website. Consider the following source directory:

source/
├── +index.md
├── About.md
├── Projects/
│   ├── +index.md
│   └── Toaster.md
└── Writing/
    ├── +index.md
    ├── Notes/
    │   ├── +index.md
    │   └── Technical writing.md
    └── Documentation/
        ├── +index.md
        ├── Markdown.md
        └── Cobalt.md

When using relative links, the page Writing/Documentation/Markdown is linked:

  • from Writing/Documentation/+index.md as {Markdown}
    Markdown is a descendant of Documentation (the index file acts as the Documentation page).
  • from Writing/Documentation/Cobalt.md as {../Markdown}
    Markdown is a sibling of Cobalt, not a descendant.
  • from Writing/+index.md as {Documentation/Markdown}
    Documentation is a descendant of Writing (the index file acts as the Writing page).
  • from Writing/Notes/+index.md as {../Documentation/Markdown}
    Notes is a sibling of Documentation (the index file acts as the Notes page).
  • from Writing/Notes/Technical writing as {../../Documentation/Markdown}
    Technical writing is a descendant of Notes, which is a sibling of Documentation
  • from Projects/+index.md as {../Writing/Documentation/Markdown}
    Writing is a sibling of Projects (the index file acts as the Projects page).
  • from Projects/Toaster.md as {../../Writing/Documentation/Markdown}
    Toaster is a descendant of Projects.
  • from +index.md as {Writing/Documentation/Markdown}
    Writing is a descendant of the site root (the index file acts as the site root).
  • from About.md as {../Writing/Documentation/Markdown}
    Writing is a sibling of About.

The Writing/Documentation/Markdown page can also be linked to from any page in the website using the absolute link form {/Writing/Documentation/Markdown}. This is preferred in all but the most trivial cases.

External links are used for linking to static files within the website, or for linking to any other URL.

If the path for an external link is prefixed with http://, https://, or mailto:, it is assumed to be a link to an external website and is not validated. If the link was not given a label, the path will be used as the label instead with the prefix removed.

If an external link does not begin with a prefix, it is assumed to be a relative link to a static file within the generated website and is validated by toaster. If the link was not given a label, the final segment of the path will be used as the label instead. toaster will validate that

Lists

If a list item begins with the characters [ ], it will be prefixed with an unchecked checkbox. If a list item begins with the characters [x], it will be prefixed with a checked checkbox.

- List item 1
- List item 2
- [ ] Unchecked checkbox
- [x] Checked checkbox

Syntax fragments

Supported syntax fragment ‘languages’ are:

  • gallery
  • gallery-nav
  • math
  • recipe
  • embed-html
  • embed-css
  • embed-js/embed-javascript
  • hidden/todo

Embedded files

Embedded files with extensions .mp3, .wav, and .m4a will be rendered as <audio> elements.

Emdedded files with extensions .jpg, .jpeg, .png, .webp, .gif, or .tiff will be rendered as <img> elements. Each <img> will be inside an <a> linking to the source file, which is then inside a <figure>.

Emdedded files with extensions .mp4 will be rendered as <video> elements.