Permalinks and Cascade#

Copy as MarkdownView Markdown

Page URLs usually follow the Markdown file tree. Enable permalinks when a page needs a different public path, and cascade when a directory should share default frontmatter with its children.

Both features are off unless you turn them on. Existing sites stay unchanged.

import { oxContent } from "@ox-content/vite-plugin";

export default {
  plugins: [
    oxContent({
      permalinks: true,
      cascade: true,
    }),
  ],
};

false or omitted keeps the feature off. true enables the defaults. An object enables the feature and overrides only the fields you set.

Permalinks#

When permalinks is on, frontmatter can replace the file-tree URL:

---
title: Getting Started
permalink: /getting-started
---

slug replaces only the last path segment:

---
title: Install
slug: install
---

guide/intro.md with slug: install becomes guide/install. A permalink wins when both keys are set.

Unsafe values are rejected and the file-tree URL is kept:

• ../ or . path segments
• Absolute filesystem paths (C:\, drive letters)
• javascript:, data:, vbscript:, file:
• Protocol-relative // URLs

If two pages resolve to the same URL, the build records an error, keeps the first page, and skips the later page.

Values written into HTML attributes are escaped.

Cascade#

When cascade is on, _index.md (also _index.mdx / _index.markdown) files supply default frontmatter for pages in that directory and below. A child keeps any key it already set. permalink and slug are never inherited, so a section index cannot force every child onto the same URL.

<!-- guide/_index.md -->

---

sidebar: Guide
---

<!-- guide/install.md -->

---

title: Install
---

guide/install.md inherits sidebar: Guide and keeps its own title.

Related#

• Site Generation
• Collections
• Built-in Features overview