jekyll/docs/_docs/permalinks.md

title	permalink
Permalinks	/docs/permalinks/

Permalinks are the output path for your pages, posts, or collections. They allow you to structure the directories of your source code different from the directories in your output.

Front Matter

The simplest way to set a permalink is using front matter. You set the permalink variable in front matter to the output path you'd like.

For example, you might have a page on your site located at /my_pages/about-me.html and you want the output url to be /about/. In front matter of the page you would set:

---
permalink: /about/
---

Global

Setting a permalink in front matter for every page on your site is no fun. Luckily, Jekyll lets you set the permalink structure globally in your _config.yml.

To set a global permalink, you use the permalink variable in _config.yml. You can use placeholders to your desired output. For example:

permalink: /:categories/:year/:month/:day/:title:output_ext

Note that pages and collections (excluding posts and drafts) don't have time and categories (for pages, the above :title is equivalent to :basename), these aspects of the permalink style are ignored for the output.

For example, a permalink style of /:categories/:year/:month/:day/:title:output_ext for the posts collection becomes /:title.html for pages and collections (excluding posts and drafts).

Placeholders

Here's the full list of placeholders available:

{%- for entry in site.data.permalinks.placeholders %} {%- endfor %}

Variable	Description
:{{ entry.name }} {%- if entry.intro_ver -%} {% include docs_version_badge.html version = entry.intro_ver %} {%- endif -%}	{{ entry.desc }}

Built-in formats

For posts, Jekyll also provides the following built-in styles for convenience:

{%- for entry in site.data.permalinks.builtin_formats %} {%- endfor %}

Permalink Style	URL Template
{{ entry.name }} {%- if entry.intro_ver -%} {% include docs_version_badge.html version = entry.intro_ver %} {%- endif -%}	{{ entry.format }} {%- if entry.note -%} ({{ entry.note }}) {%- endif -%}

Rather than typing permalink: /:categories/:year/:month/:day/:title/, you can just type permalink: pretty.

Specifying permalinks through the front matter

Built-in permalink styles are not recognized in front matter. As a result, permalink: pretty will not work.

Collections

For collections (including posts and drafts), you have the option to override the global permalink in the collection configuration in _config.yml:

collections:
  my_collection:
    output: true
    permalink: /:collection/:name

Collections have the following placeholders available:

{%- for entry in site.data.permalinks.types.documents -%} {%- endfor -%}

Variable	Description
:{{ entry.name }}	{{ entry.desc }}

Pages

For pages, you have to use front matter to override the global permalink, and if you set a permalink via front matter defaults in _config.yml, it will be ignored.

Pages have the following placeholders available:

{%- for entry in site.data.permalinks.types.pages -%} {%- endfor -%}

Variable	Description
:{{ entry.name }}	{{ entry.desc }}