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/getting-started/migrating.md
+20
View File
@@ -87,6 +87,26 @@ Key changes:
- **Import pattern**: Community plugins use `ExternalPlugin.X()` (from `.quartz/plugins`) instead of `Plugin.X()` (from `./quartz/plugins`)
- **Layout structure**: `quartz.layout.ts` is gone — layout position is now a per-plugin property in `quartz.config.yaml`
- **Page types**: A new plugin category for page rendering (content, folder, tag pages)
- **URL casing**: All generated URLs are now lowercased and hyphenated (e.g. `My Notes/Hello World.md` → `/my-notes/hello-world`). In v4, the original casing of file and folder names was preserved in URLs.
### URL Casing and SEO
If your v4 site had URLs with uppercase letters, those URLs will return 404 errors after upgrading to v5. This also affects search engine indexing, since Google treats URLs as [case-sensitive](https://developers.google.com/search/docs/crawling-indexing/url-structure).
The [[AliasRedirects]] plugin (enabled by default) automatically handles this. During build, it detects files whose original path contained uppercase characters and generates redirect pages at the old URLs. These redirect pages include proper SEO signals (`<link rel="canonical">`, `<meta http-equiv="refresh">`, `<meta name="robots" content="noindex">`) so that search engines transfer ranking to the new lowercase URLs.
No manual configuration is needed — the plugin is enabled by default and the case redirect behavior is on by default. If you want to disable it, set `enableCaseRedirects: false` in the plugin options:
```yaml title="quartz.config.yaml"
plugins:
- source: github:quartz-community/alias-redirects
enabled: true
options:
enableCaseRedirects: false
```
> [!tip] Hosting on Netlify?
> Netlify automatically lowercases all URLs and issues server-side 301 redirects. If you're hosting on Netlify, the case redirect pages aren't strictly necessary, but they don't hurt either.
> [!note] Most users don't need to worry about these details
> If you used the default Quartz 4 configuration (or only changed settings that `npx quartz create` prompts for), the setup wizard handles everything. The details below are for users who had custom plugin configurations.
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