GuideHow-to recipes
Customize output paths
Change where pages are written with permalink, in front matter or for a whole folder, with dates and slugs in paths.
The permalink step writes each file to an output path and sets its url. Without a permalink, the path follows the
source file: blog/post.md is written to blog/post/index.html, index.md stays index.html, and
feed.xml.liquid is feed.xml. A permalink value overrides that path. It is a Liquid template rendered with the
page's data, and it can come from front matter, from folder data, or from site data.
Set the path of one pageLink to this heading
| Front matter | Output file | url |
|---|---|---|
permalink: /about/ |
about/index.html |
/about/index.html |
permalink: /about |
about/index.html |
/about/index.html |
permalink: /legacy.html |
legacy.html |
/legacy.html |
permalink: /api/{{ name }}.json |
api/status.json (with name: status) |
/api/status.json |
permalink: false |
nothing: the page is not written |
A path without an extension is a folder, which gets an index.html. The content folder (_content) is never part of
the output path.
---
title: About us
permalink: /about/
---
About
Set the paths of a folderLink to this heading
A data file in a folder applies its keys to every page of the folder and its subfolders, so a permalink there is a
pattern for all of them. Each page renders it with its own data:
permalink: "/blog/{{ date | date: '%Y/%m' }}/{{ title | slug }}/"
---
title: Hello, World & More!
date: 2026-03-14
---
Hi
_content/posts/2026-03-14-hello.md is written to blog/2026/03/hello-world-more/index.html. A page of the folder
that sets its own permalink keeps it: the page's data comes before its folder's.
Write files that are not HTMLLink to this heading
A file whose name ends in .liquid is rendered as a template and written without .liquid, which is how to publish
JSON, XML or text built from data:
---
permalink: /api/{{ name }}.json
name: status
---
{ "name": "{{ name }}" }
Name it _content/status.json.liquid, not status.json: the .json, .yml, .yaml and .xml files of the content
folder are folder data, not pages.
Read the url in templatesLink to this heading
url is the output path, with index.html. Links to folder URLs remove it:
<a href="{{ post.data.url | replace: 'index.html', '' }}">{{ post.data.title }}</a>
On a site served under a path, such as a GitHub Pages project site, relative_url adds the path of site.url:
see Deploy to GitHub Pages.
Change the output folderLink to this heading
The output folder is _site in the source folder. -o changes it for one build, and site.output in douze.yml
for every build (-o wins):
site:
output: public
See alsoLink to this heading
- Routing and permalinks
- Pagination, for the paths of paginated pages
- permalink step
- Template data
- douze.yml reference