The Equal Justice Initiative
Eleventy
The possum is Eleventy’s mascot

Eleventy Documentation

This is an older version of Eleventy. Go to the newest Eleventy docs (current path: /docs/permalinks/) or the full release history.
Menu

Permalinks #

Cool URIs don’t change #

Eleventy automatically helps you make sure that Cool URIs don’t change.

What to leave out…
File name extension. This is a very common one. "cgi", even ".html" is something which will change. You may not be using HTML for that page in 20 years time, but you might want today's links to it to still be valid. The canonical way of making links to the W3C site doesn't use the extension.

Default Input/Output Examples #

Assuming your --output directory is the default, _site:

Input Fileindex.njk
Output File_site/index.html
Href/
Input Filetemplate.njk
Output File_site/template/index.html
Href/template/
Input Filesubdir/template.njk
Output File_site/subdir/template/index.html
Href/subdir/template/
Input Filesubdir/template/template.njk or subdir/template/index.njk
Output File_site/subdir/template/index.html
Href/subdir/template/

Remapping Output (Permalink) #

To remap your template’s output to a different path than the default, use the permalink key in the template’s front matter. If a subdirectory does not exist, it will be created.

Syntax YAML Front Matter
---
permalink: "this-is-a-new-path/subdirectory/testing/index.html"
---

The above is functionally equivalent to:

Syntax YAML Front Matter
---
permalink: "this-is-a-new-path/subdirectory/testing/"
---

Both of the above examples will write to _site/this-is-a-new-path/subdirectory/testing/index.html.

While index.html is optional, it is a Common Pitfall to leave off the trailing slash! If you forget it, the browser may attempt to download the file instead of displaying it (unless you’ve done some extra work to set up your Content-Type headers correctly).
If multiple input files attempt to write to the same permalink output file, Eleventy will throw an error New in v0.9.0.

If you set the permalink value to be false, this will disable writing the file to disk in your output folder. The file will still be processed normally (and present in collections, with its url and outputPath properties set to false) but will not be available in your output directory as a standalone template.

Syntax YAML Front Matter
---
permalink: false
---

You may use data variables here (and template syntax, too). These will be parsed with the current template’s rendering engine.

For example, in a Nunjucks template:

Syntax YAML Front Matter using Liquid, Nunjucks
---
mySlug: this-is-a-new-path
permalink: "subdir/{{ mySlug }}/index.html"
---

Writes to _site/subdir/this-is-a-new-path/index.html.

Make sure you read about the special page variables useful for permalinks too: page.fileSlug and page.filePathStem.

Warning about YAML Objects #

When you use variables, make sure that you use quotes! Without quotes YAML may try to parse this as an object if the first character is a {, for example permalink: {{ page.filePathStem }}.html. This is a common pitfall.
Syntax YAML
permalink: "{{ page.filePathStem }}.html"

The error message might look like can not read a block mapping entry; a multiline key may not be an implicit key.

Some template syntaxes are nicer than others and you may want to opt-out of the templating engine here. Use the dynamicPermalink option in your front matter to disable this on a per-template basis.

This is a common pitfall for users of the Pug templating engine.
Syntax YAML Front Matter
---
permalink: "/this-will-be-a-string-without-templating/"
dynamicPermalink: false
---

Eleventy includes a global configuration option to disable dynamic templating altogether. This will save a few template renders and is probably marginally faster, too.

Filename .eleventy.js
module.exports = function(eleventyConfig) {
// Enabled by default
eleventyConfig.setDynamicPermalinks(false);
};

Use filters! #

Use the provided slug filter to modify other data available in the template.

Syntax YAML Front Matter using Liquid, Nunjucks
---
title: My Article Title
permalink: "subdir/{{ title | slug }}/index.html"
---

(the above is using syntax that works in at least Liquid and Nunjucks)

Writes to _site/subdir/my-article-title/index.html.

Syntax YAML Front Matter using Liquid
---
date: "2016-01-01T06:00-06:00"
permalink: "/{{ page.date | date: '%Y/%m/%d' }}/index.html"
---

Writes to _site/2016/01/01/index.html. There are a variety of ways that the page.date variable can be set (using date in your front matter is just one of them). Read more about Content dates.

Ignore the output directory New in v0.1.4 #

To remap your template’s output to a directory independent of the output directory (--output), use permalinkBypassOutputDir: true in your front matter.

Syntax YAML Front Matter
---
permalink: "_includes/index.html"
permalinkBypassOutputDir: true
---

Writes to _includes/index.html even though the output directory is _site. This is useful for writing child templates to the _includes directory for re-use in your other templates.

Custom File Formats #

To generate different file formats for your built site, you can use a different extension in the permalink option of your front matter.

For example, to generate a JSON search index to be used by popular search libraries:

Syntax EJS
---
permalink: "index.json"
---

<%- JSON.stringify(collections.all) -%>

Pagination #

Pagination variables also work here. Read more about Pagination


Other pages in Working with Templates: