yuriy/quartz-website
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: updated migration guide and alias-redirect options

Browse Source
This commit is contained in:
saberzero1
2026-06-09 20:01:46 +02:00
parent b2f1dad514
commit c5bbc92b74
2 changed files with 54 additions and 9 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/plugins/AliasRedirects.md
+34 -9
View File
@@ -1,6 +1,6 @@
---
title: AliasRedirects
description: Generates redirect pages from frontmatter aliases.
description: Generates redirect pages from frontmatter aliases and case-preserving URLs.
tags:
- plugin/emitter
image: https://images.unsplash.com/photo-1601735479770-bb5de9dbe844
@@ -9,31 +9,56 @@ enabled: true
required: false
---
This plugin emits HTML redirect pages for aliases and permalinks defined in the frontmatter of content files.
This plugin emits HTML redirect pages so that old URLs redirect to the canonical page. It handles two types of redirects:
For example, A `foo.md` has the following frontmatter
1. **Frontmatter aliases**: Redirect pages for aliases defined in your content's frontmatter.
2. **Case-preserving redirects**: Automatic redirect pages for URLs that changed due to Quartz v5's lowercase slug normalization.
### Frontmatter Aliases
If `foo.md` has the following frontmatter:
```md title="foo.md"
---
title: "Foo"
alias:
aliases:
- "bar"
---
```
The target `host.me/bar` will be redirected to `host.me/foo`
The target `host.me/bar` will be permanently redirected to `host.me/foo`.
Note that these are permanent redirect.
The emitter supports the following aliases:
The emitter supports the following frontmatter fields:
- `aliases`
- `alias`
### Case-Preserving Redirects
Quartz v5 normalizes all URLs to lowercase. If you are migrating from v4 (which preserved the original casing), previously indexed URLs containing uppercase letters (e.g. `/Diary/My-Note`) would return 404 errors.
When `enableCaseRedirects` is enabled (the default), this plugin automatically detects files whose original path differs from the lowercased slug and generates redirect pages at the original-case URL. For example, if your content directory contains `Diary/2026-01-01.md`, the plugin generates:
- The canonical page at `/diary/2026-01-01` (produced by the normal build)
- A redirect page at `/Diary/2026-01-01` (produced by this plugin)
The redirect page includes proper SEO signals:
- `<meta http-equiv="refresh" content="0; url=...">` for an instant redirect
- `<link rel="canonical">` pointing to the lowercase URL
- `<meta name="robots" content="noindex">` to prevent duplicate indexing
This preserves search engine rankings and ensures inbound links continue to work.
> [!note]
> Case-preserving redirects have no effect on case-insensitive filesystems (macOS, Windows) where the server already resolves either casing to the same file. The plugin automatically detects the filesystem type and skips redirect generation when unnecessary.
> [!note]
> For information on how to add, remove or configure plugins, see the [[configuration#Plugins|Configuration]] page.
This plugin has no configuration options.
This plugin accepts the following configuration options:
- `enableCaseRedirects`: If `true` (default), automatically generates redirect pages for URLs that changed casing due to v5's lowercase normalization. Set to `false` to disable this behavior.
## API