TutorialBuild a blog
Unit 2: Pages
Add Markdown and HTML pages and blog posts, link them together, choose where they are written, and use front matter in Liquid.
In this unit you will:
- write pages in Markdown and in HTML,
- give pages data with front matter, and show it with Liquid,
- add three blog posts in a folder of their own,
- link pages together,
- learn where Douze writes each page, and change it with
permalink.
Keep douze serve running from unit 1, and open each new page in the browser as you create it.
Step 1: add an about pageLink to this heading
Create _content/about.md:
---
title: About me
description: Who writes this blog, and why.
skills:
- HTML
- CSS
- Markdown
- Liquid
learning: true
---
# {{ title }}
{{ description }}
I am a web developer who likes small tools. This blog is my notebook while I learn Douze.
## My skills
{% for skill in skills %}
- {{ skill }}
{%- endfor %}
{% if learning %}
I am still learning Liquid, so expect a few mistakes.
{% endif %}
[Back to the home page](/)
Open http://localhost:8080/about/. The page shows its title, its description, the list of skills and the sentence
about learning Liquid.
Douze renders every page as a Liquid template before it renders its Markdown. Liquid has two kinds of markup:
{{ ... }}outputs a value.{{ title }}is thetitleof the front matter.{% ... %}is a tag: logic such as{% for %}loops and{% if %}conditions.
Every key of the front matter is a variable of the page: title, description, skills and learning here. They
can be strings, numbers, booleans, lists or objects, anything YAML can write.
Change learning: true to learning: false and save: the sentence disappears from the page.
Step 2: add an HTML pageLink to this heading
A page can also be HTML. Create _content/projects.html:
---
title: My projects
---
<h1>{{ title }}</h1>
<p>Things I built while learning.</p>
<ul>
<li><a href="https://github.com/sebastienros/douze">Douze</a> builds this blog.</li>
<li>A <a href="/about/">page about me</a>, written in Markdown.</li>
</ul>
<p><a href="/">Back to the home page</a></p>
Open http://localhost:8080/projects/. An HTML page has front matter and Liquid like a Markdown page; Douze only skips
the Markdown rendering.
Step 3: write blog postsLink to this heading
Posts are pages too. Keep them together in a posts folder: create _content/posts/ and these three files.
---
title: My first post
description: Why I started this blog.
date: 2026-09-01
author: Ada
tags: [post, douze]
---
# {{ title }}
Published on {{ date | date: "%B %-d, %Y" }} by {{ author }}.
This is the first post of my new blog. I am building it with Douze, a static site generator: I write Markdown, and
Douze turns it into HTML.
## What I want to learn
- How pages become HTML files.
- How to share a layout between pages.
- How to list my posts automatically.
---
title: Pages and permalinks
description: How Douze decides where each page goes.
date: 2026-09-15
author: Ada
tags: [post, douze]
---
# {{ title }}
Published on {{ date | date: "%B %-d, %Y" }} by {{ author }}.
Every file of the content folder ends up in the output folder. A page named `about.md` is written to
`about/index.html`, so its address is `/about/`, without `.html`.
A `permalink` in the front matter picks another path.
---
title: What I learned about Liquid
description: Variables, filters and loops, the three things I use the most.
date: 2026-10-01
author: Ada
tags: [post, liquid]
---
# {{ title }}
Published on {{ date | date: "%B %-d, %Y" }} by {{ author }}.
Liquid is the template language of Douze. Three of its features cover most of what I need.
## Variables
Every key of the front matter is a variable:
```liquid
<h1>{{ title }}</h1>
```
## Filters
A filter transforms a value, after a `|`:
```liquid
{{ date | date: "%B %-d, %Y" }}
```
## Loops
A `for` tag repeats its content for each item of a list:
```liquid
{% for skill in skills %}
<li>{{ skill }}</li>
{% endfor %}
```
Open http://localhost:8080/posts/first-post/. Under the title, the post shows "Published on September 1, 2026 by
Ada".
dateis a date in the front matter. Thedatefilter formats it:%Bis the month's name,%-dthe day without a leading zero,%Ythe year.tagsis a list of tags. You will use them in unit 5 to list the posts.- The code samples of the third post show Liquid that Douze does not run: the content of Markdown code fences is never
rendered as Liquid, so
{{ title }}stays as it is.
Step 4: link the pages togetherLink to this heading
Links between pages are ordinary links, to the address of each page. Replace _content/index.md with:
---
title: My blog
---
# Welcome to my blog
This is where I write about learning Douze.
- [About me](/about/)
- [My projects](/projects/)
## Posts
- [My first post](/posts/first-post/)
- [Pages and permalinks](/posts/second-post/)
- [What I learned about Liquid](/posts/third-post/)
The home page now links to every page. In unit 5, Douze will build the list of posts for you.
Step 5: see where pages are writtenLink to this heading
Look at the _site folder:
_site/
├── index.html
├── about/index.html
├── projects/index.html
└── posts/
├── first-post/index.html
├── second-post/index.html
└── third-post/index.html
Douze writes each page at its path in _content, in a folder named after the page, so that its address has no
extension:
| Source | Output | Address |
|---|---|---|
_content/index.md |
_site/index.html |
/ |
_content/about.md |
_site/about/index.html |
/about/ |
_content/projects.html |
_site/projects/index.html |
/projects/ |
_content/posts/first-post.md |
_site/posts/first-post/index.html |
/posts/first-post/ |
Files that are not pages, such as images or stylesheets, are copied as they are.
Step 6: choose a path with permalinkLink to this heading
A permalink in the front matter overrides the output path. Static hosts, and douze serve, show a 404.html page at
the root of the site when a page does not exist. Create one:
---
title: Page not found
permalink: /404.html
---
# Page not found
There is nothing at this address. Go back to the [home page](/).
Without the permalink, this page would be written to 404/index.html. Open http://localhost:8080/nothing-here/: the
server answers with your 404 page.
A permalink without an extension is a folder: permalink: /hello/ writes hello/index.html. It is a Liquid
template too, so permalink: /blog/{{ title | slug }}/ builds the path from the title. permalink: false does not
write the page at all, which is handy for drafts.
See Routing and permalinks for every rule.
Answers
/posts/hello/, written to_site/posts/hello/index.html.4, the number of items in theskillslist.sizeworks on lists and strings.- With
permalink: /feed.xmlin its front matter. Unit 5 shows another way, with a.liquidfile.
NextLink to this heading
The home and about pages repeat the same links, and every post repeats its title and date line. In unit 3, you will share markup between pages with includes and shortcodes.