Permalinks

Permalinks control the output URL for each page. Alloy resolves URLs through a three-level priority chain: front matter first, then the _data.yaml cascade, then the file path.

# content/blog/_data.yaml
permalink: &#34;/:year/:month/:slug/&#34;

With this directory data, a post at content/blog/my-post.md with date: 2026-04-10 outputs to /2026/04/my-post/.

Resolution order

Front matter permalink: – Always wins. A page with an explicit permalink ignores all cascade patterns.
_data.yaml cascade permalink: – Section-level patterns with token replacement. The nearest _data.yaml in the directory tree wins – a subdirectory’s pattern overrides its parent’s.
DefaultFromPath – The file path maps directly to the URL. content/about.md becomes /about/.

There is no site-level permalinks: config key. URL patterns are section-level data set in _data.yaml – sections own their own URL structure.

Available tokens

Tokens in permalink patterns are replaced with values from the page’s front matter and metadata:

Token	Value	Example
`:year`	Content date, 4-digit	`2026`
`:month`	Content date, 2-digit	`04`
`:day`	Content date, 2-digit	`10`
`:slug`	Slugified title or filename	`my-first-post`
`:title`	Raw title from front matter	`My First Post`
`:section`	Top-level content directory	`blog`
`:filename`	Source filename without extension	`my-first-post`

Blog with date-based URLs

# content/blog/_data.yaml
layout: post
permalink: &#34;/blog/:year/:month/:slug/&#34;

# content/blog/my-first-post.md
---
title: &#34;My First Post&#34;
date: 2026-04-10
---

Output: /blog/2026/04/my-first-post/

Docs site with flat URLs

# content/docs/_data.yaml
layout: doc
permalink: &#34;/docs/:slug/&#34;

Every page under content/docs/ gets a flat URL like /docs/getting-started/, unless a subdirectory’s _data.yaml sets its own pattern.

Nested patterns

A subdirectory can override its parent’s permalink pattern. Alloy uses the nearest _data.yaml permalink in the directory tree:

# content/blog/_data.yaml — simple slugs for static pages
permalink: &#34;/blog/:slug/&#34;

# content/blog/posts/_data.yaml — date-based URLs for posts
permalink: &#34;/blog/:year/:month/:slug/&#34;

Pages in content/blog/ use /blog/:slug/. Pages in content/blog/posts/ use /blog/:year/:month/:slug/.

Front matter permalinks

A page can set its own URL directly, overriding any cascade pattern:

---
title: &#34;About Us&#34;
permalink: &#34;/about/&#34;
---

Template permalinks

Permalinks containing {{ }} are rendered as Liquid template expressions. Template permalinks work on both regular pages and pagination virtual pages.

Token permalinks and template permalinks are two separate modes – they are not composable. If a permalink contains {{, the entire string is rendered as a template expression. Token syntax (:year, :slug, etc.) is not processed and would appear as literal text.

---
title: &#34;My Post&#34;
slug: &#34;my-post&#34;
permalink: &#34;/articles/{{ page.slug }}/&#34;
---

Template permalinks render through Liquid regardless of the configured engine. The page object contains front matter fields, date, slug, summary, and collection:

Token	Template equivalent
`:year`	`{{ page.date \| date: '%Y' }}`
`:month`	`{{ page.date \| date: '%m' }}`
`:day`	`{{ page.date \| date: '%d' }}`
`:slug`	`{{ page.slug }}`
`:title`	`{{ page.title }}`
`:section`	`{{ page.collection }}`

Tokens are simpler and faster – use them when the built-in set covers your needs. Template permalinks are for cases that need custom front matter fields or Liquid filters:

---
title: &#34;My Custom Post&#34;
lang: &#34;en&#34;
permalink: &#34;/{{ page.lang }}/{{ page.title | slugify }}/&#34;
---

page.url is not available in the template permalink context (it is what’s being computed). A template permalink that renders to an empty string is a build error.

Pagination pages can use the as: variable in template permalinks:

---
pagination:
  data: site.data.team
  perPage: 1
  as: member
permalink: &#34;/team/{{ member.slug }}/&#34;
---

Static overrides

Permalinks without tokens or template tags are a zero-cost fast path:

---
permalink: &#34;/custom/path/here/&#34;
---

Overriding just the slug

To change only the URL segment derived from the filename, set slug: instead of a full permalink:

---
title: &#34;A Very Long Title That Would Make an Ugly URL&#34;
slug: &#34;short-url&#34;
---

With a cascade pattern of /:year/:month/:slug/, this page outputs to /:year/:month/short-url/.

Index files

Index files (index.md, index.html) resolve to their parent directory path by default, skipping cascade permalink patterns:

content/index.md – / (site root)
content/blog/index.md – /blog/ (section landing)
content/blog/second-post/index.md – /blog/second-post/ (page bundle)

This prevents a cascade pattern from turning content/index.md (title: “Home”) into /home/ instead of /.

Front matter permalink: still works on index files:

---
title: &#34;Home&#34;
permalink: &#34;/docs/&#34;
---

`permalink: false`

Process the page (include it in collections, make its data available) without writing an output file. Useful for data-only pages:

---
title: &#34;Shared Config&#34;
permalink: false
layout: false
sharedData: &#34;value available in collections but no output page&#34;
---

Aliases

A page can output at multiple paths. Aliases write identical copies of the rendered HTML – not redirects.

---
title: &#34;About Us&#34;
permalink: &#34;/about/&#34;
aliases:
  - /about-us/
  - /team/
---

This writes the same HTML to _site/about/index.html, _site/about-us/index.html, and _site/team/index.html.

Aliases are validated during the pre-build conflict detection pass. If an alias collides with another page’s output path, the build fails with a clear error.

Trailing slashes

All permalinks should end with a trailing slash. Alloy writes pages as path/index.html, so /about/ becomes _site/about/index.html. This produces clean URLs that work with any static file server.