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:

_content/posts/posts.yml
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

Esc to close