Name
docs - the manual of tilder
This manual describes tilder 1.4.1: every configuration key, front-matter key, Markdown construct, placeholder, class and command-line option of that version, written for the people who build a site with it. Start with the guide; come back to the reference when you need a detail.
Sections
- Guide: from the first build to a site online, in the order you meet things.
- Content types: collections, posts, events, members, types of your own, and the order of a collection's pages.
- Themes: what a theme is made of, its layouts, placeholders, classes and scripts, and how to check one.
- Reference: the Markdown dialect, every key of the configuration, the text mirror, SEO, feeds and images, the command line.
In a terminal
Like every site tilder builds, this manual has a text twin, 75 columns wide. A terminal gets it at the same address:
curl tilder.thosted.fr/docs
curl tilder.thosted.fr/docs/guide/getting-startedPages
Guide
The path through tilder, page by page: install it, lay out a project, write pages, add a language, then put the site online.
Getting started
Install tilder with Docker or Python 3.11, copy the starter site, build it once, rebuild as you write, and find your way in public/.
The project
The three folders of a tilder site, content/, theme/ and assets/, the three layers of its configuration, and what is served.
Writing pages
From a Markdown file to a page: its address, every front-matter key, man-page sections, links inside and across languages, and images.
Languages
Serve a site in several languages: declare them, translate the configuration and the pages, and know what happens to a page not yet translated.
Deployment
Put a tilder site online with Docker, compose and Caddy: clean URLs, the text mirror for curl, a plain-text host, headers, and other servers.
Content types
Collections of pages of one type: declaring them, their items, the list markers, their RSS feeds and iCalendar files, and the four built-in types.
page
The page type: every Markdown file outside a collection, with no settings, no card and no list, described to search engines as a WebPage.
post
The post type: dated articles named by their date, listed newest first by {posts}, with an RSS feed, article metadata and BlogPosting data.
event
The event type: dated items with a place, upcoming or past by the build's date, the {upcoming}, {past} and {next-event} lists, RSS and iCalendar.
member
The member type: one page per person, a searchable grid by {members}, categories, pronouns, public profiles with their logos, and members.js.
Types of your own
Write a content type in Python in theme/types/: its attributes, its functions, the item, the entry node, markers, imports and errors, with an example.
Navigation
The order of a collection's pages, their groups and sections, the sidebar, the links to the previous and next page, and their line in the text mirror.
Themes
What a tilder theme is, how to use one, and the pages that describe its files, layouts, classes, scripts and checks.
The files of a theme
Every file a tilder theme may provide, what the build does with each one, what it serves, and how assets/ overrides the theme.
Layouts and placeholders
layout.html and layouts/, how tilder chooses a page's layout, every placeholder with its value and escaping, and what a layout must keep.
Classes
Every class tilder writes in its HTML, grouped as in its contract, with the element each lands on, and the accessibility a theme owns.
Scripts
The scripts a tilder theme may ship, code.js, members.js and a type's own, where the build loads each one, and the rules every script follows.
Checking a theme
build.py --check checks a theme against the tilder that runs it: a rule for every class it writes, and the contrast of the colour pairs.
Reference
Every detail of tilder, to look up: the Markdown dialect, the configuration keys, the text mirror, SEO, feeds and images, and the command line.
The Markdown reference
tilder's Markdown dialect on one page: its principles, a quick reference of every construct, and what it leaves out on purpose.
Sections
The ## headings of a page: the man-page rows they draw, the id each one gets, and every marker in braces that changes a section.
Blocks
Paragraphs and their classes, the empty state, lists, tasks, contents, rules, insets, callouts, code blocks, tables and comments, each shown rendered.
Entries
The ### headings inside a section: an event, a person, a card. Their meta line of dates and tags, their indented body, and their markers.
Inline markup
Bold, italic, struck and underlined text, code and links inside a sentence: the six inline constructs, what stays literal, and the text mirror.
Links and images
Link targets written from the site root, anchors, links across languages, files and other sites; images next to their page, alt text and captions.
Configuration
Every key of tilder's defaults.toml, table by table: its default value, what it does, and an example of setting it in site.toml.
The text mirror
Every page as text: 75 columns, folded to ASCII, plain in txt/ and coloured in ansi/, with framed code, boxed callouts and the plain-text host.
SEO
What tilder writes for search engines and link previews: title, description, canonical, Open Graph, JSON-LD, sitemaps, robots.txt, checks.
Feeds and images
The files tilder writes besides the pages: RSS feeds, iCalendar, the icons and share.png drawn from SVG at every build, and the web manifest.
The command line
build.py and every option, from --root to --check, what the build prints, every warning and error it can give, and its exit codes.