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.11.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
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.
Heading links
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 heirarchy 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.mdas{Markdown}
Markdown is a descendant of Documentation (the index file acts as the Documentation page). - from
Writing/Documentation/Cobalt.mdas{../Markdown}
Markdown is a sibling of Cobalt, not a descendant. - from
Writing/+index.mdas{Documentation/Markdown}
Documentation is a descendant of Writing (the index file acts as the Writing page). - from
Writing/Notes/+index.mdas{../Documentation/Markdown}
Notes is a sibling of Documentation (the index file acts as the Notes page). - from
Writing/Notes/Technical writingas{../../Documentation/Markdown}
Technical writing is a descendant of Notes, which is a sibling of Documentation - from
Projects/+index.mdas{../Writing/Documentation/Markdown}
Writing is a sibling of Projects (the index file acts as the Projects page). - from
Projects/Toaster.mdas{../../Writing/Documentation/Markdown}
Toaster is a descendant of Projects. - from
+index.mdas{Writing/Documentation/Markdown}
Writing is a descendant of the site root (the index file acts as the site root). - from
About.mdas{../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
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:
gallerygallery-navmathrecipeembed-htmlembed-cssembed-js/embed-javascripthidden/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.