Content¶
Everything under content/ becomes the site. The engine reads .md and
.html files recursively; any other file is ignored.
Files and URLs¶
The path of a file determines its URL and its output file:
| Source | URL | Output |
|---|---|---|
content/index.md |
/ |
dist/index.html |
content/about.md |
/about/ |
dist/about/index.html |
content/posts/hello.md |
/posts/hello/ |
dist/posts/hello/index.html |
content/posts/2026/index.md |
/posts/2026/ |
dist/posts/2026/index.html |
A file named index maps to its directory instead of a subdirectory, which is
what makes clean URLs work. Two sources that resolve to the same output fail
the build instead of overwriting each other silently.
Front matter¶
Markdown and HTML pages can start with TOML front matter between +++ lines:
+++
title = "Why static sites"
date = 2026-11-07
summary = "No runtime, no database, no surprises."
template = "post"
+++
The body starts here.
Front matter is optional. Without it, the title is derived from the file name
(second-post.md becomes "Second Post") and the default template is used.
Recognised keys¶
| Key | Type | Default | Meaning |
|---|---|---|---|
title |
string | File name | Page title. |
date |
ISO date | none | Publication date. Drives ordering and feeds. |
template |
string | index or page |
Template file, with or without .html. |
draft |
boolean | false |
Skipped unless the build uses --drafts. |
summary |
string | none | Short description used by the blog theme and the feed. |
url |
string | Derived from the file | Public URL, starting with / and ending in / or .html. |
Any other key is kept in page.meta and is available to templates, so a theme
can support cover, tags, or anything else without engine changes.
URLs¶
By default the URL comes from the file path: about.md becomes /about/ and
posts/hello.md becomes /posts/hello/. Use url in the front matter to
publish a page somewhere else:
+++
title = "Changelog"
url = "/changelog/"
+++
The value must start with / and end in / or .html; anything else fails
the build instead of being silently ignored.
File names are used as written, including non-ASCII characters: año-nuevo.md
is published at /año-nuevo/. Keep that in mind when choosing names, because
changing one changes the URL.
Dates¶
date accepts a TOML date (2026-11-07), a TOML datetime, or an ISO string.
Only the calendar date is used; times are discarded. An invalid value fails
the build with the source file in the message.
Drafts¶
A page with draft = true is loaded but excluded from the build. To preview
it locally:
jamstack build --drafts
jamstack serve --drafts
Be careful not to deploy a dist/ built with --drafts: drafts are included
in the sitemap and the feed.
Markdown¶
Markdown is parsed as CommonMark with raw HTML enabled, so inline HTML works:
A paragraph with a <mark>highlight</mark>.
<div class="note">A block written in HTML.</div>
The rendered HTML is exposed to templates as page.content, already marked
safe. Do not add |safe to it.
HTML pages¶
A .html file is rendered as a Jinja template instead of Markdown. It receives
the same variables as any other page (site, page, pages), which makes it
useful for landing pages with custom markup:
+++
title = "Landing"
+++
<section class="hero">
<h1>{{ site.title }}</h1>
<p>{{ site.description }}</p>
</section>
<ul>
{% for item in pages if item.url != "/" %}
<li><a href="{{ item.url }}">{{ item.title }}</a></li>
{% endfor %}
</ul>
Page order¶
Templates receive pages sorted by date, newest first, then by title. Pages
without a date sort after dated pages. The blog theme filters that list to
dated pages, which is why an about page does not appear among the posts.
Errors you will see¶
invalid front matter: the TOML between+++lines does not parse.unterminated front matter: the opening+++has no closing line.invalid date: the value is not an ISO date.both build to …: two files resolve to the same output path.
All of them stop the build and name the source file. The development server keeps serving the last successful build while you fix the file.