Pages, folders and addresses
A siv website is a folder of folders. Each page is a folder with an index.md file, and the folders become the addresses of the pages.
A page is a folder # ↑
Everything in content/ is published at the same path:
content/index.md / the front page
content/hello/index.md /hello/
content/hello/cat.jpg /hello/cat.jpg
content/boats/tugboat/index.md /boats/tugboat/
Keep each page's images and other files in its folder, and use them by name: . When you move the folder, everything moves along.
A folder without index.md is not a page, but its files are still published. Folders inside it that have an index.md are pages again.
Create a page # ↑
$
Created content/trams-in-helsinki/index.md
The title goes into the page as you wrote it. The folder name is made of it with the address rule below. A page can go inside another folder:
$
Created content/boats/tugboat/index.md
A short name like boats/tugboat gets the title "Tugboat". Use quotes around a title with characters the shell treats specially, like ', ? or !: siv new "Tero's trip: what is DNS?".
New pages start from skel/default.md, a skeleton you can edit:
+++
title = "{{ title }}"
published = "{{ now }}"
+++
Write the first paragraph here. It's the summary shown on the front page.
Write the rest of the page here.
The front matter # ↑
The lines between +++ at the top of a page are its front matter, in TOML: a name, = and a value.
+++
title = "Boat repairs"
published = "2026-10-12 w42 Mon"
tags = ["boats", "repair"]
+++
The text of the page starts here.
The most used keys:
title the page title
published the date, optionally with a time
updated the date of the last real update
tags a list of tags: siv help tags
draft = true shown in preview only, never published
listed = false published, but left out of lists
aliases old addresses that lead here, see below
cover an image for lists of pages
Every key: siv help front-matter. A misspelled key gets a warning that suggests the right one.
Dates # ↑
published = "2026-10-12 w42 Mon"
published = "2026-10-12 w42 Mon 14:30"
published = 2026-10-12
The first form, from calendar.txt, has the week number and weekday, so you see them while you write. If they don't match the date, siv tells the right ones:
content/foo/index.md:3:25: error[siv2201 date]: 2026-12-01 is w49 Tue, not w01 Mon
Lists show dated pages first, newest first, then pages without a date.
Drafts # ↑
A page with draft = true is shown by siv preview, but never built into the website. Remove the line to publish it. A link from a published page to a draft gets a warning, as the link would go nowhere.
Addresses # ↑
The address of a page comes from its folder name. Folder names, new pages and heading anchors follow one rule:
- only a-z, 0-9 and
- - lowercase
- ä, ö and å become a, o and a; other accents are removed
- every other character becomes
-
"Catalyzing change in Öljytön enterprises" becomes catalyzing-change-in-oljyton-enterprises.
Links between pages # ↑
Write a link to your own page as a path, from this page or from the root:
siv checks every link to your pages, and every anchor, on every build. A broken link stops the build, with the file and line to fix.
In the finished website, siv writes the links in the style set in siv.toml. The default, links = "relative", works on any server, in any folder.
Moving a page # ↑
Addresses are forever: other sites and bookmarks link to them. When you move or rename a page, keep the old address working with an alias:
+++
title = "Tugboat"
aliases = ["/old-address/"]
+++
The old address becomes a small page that sends the visitor to the new one.
The 404 page # ↑
A page at content/404/index.md is the "page not found" page. Tell your web server to show /404/ for missing pages: Publishing.
Site-wide files # ↑
There is no separate folder for static files. Files next to the front page are published at the root of the site:
content/favicon.ico /favicon.ico
content/robots.txt /robots.txt
content/fonts/a.woff2 /fonts/a.woff2
Files and folders whose name starts with a dot, like .git, are not published, with a warning. .well-known/ is the exception, as certificates need it.
A text file starting with +++ is a template that siv fills in, like the Atom feed content/feed.xml. Other files are copied as they are.
Dated copies of a page # ↑
A course page changes every year, but last year's version should stay readable. siv util archive makes a dated copy, an edition, at an address of its own:
$
Created the 2026 edition in content/2026/karaoke-101-2026/:
content/2026/karaoke-101-2026/index.md
Details: siv help editions.
Reusable text # ↑
A snippet is text you use on many pages, kept in skel/snippets/:
$
Inserted skel/snippets/old-version.md at the top of content/karaoke-101/index.md
The text becomes part of the page, as plain Markdown. Details: siv help snippets.
Next: Lists, tags and the feed