Riebeckite
Menu
Color mode

Alias

Turns Obsidian aliases / alias frontmatter into site-local redirect URLs, so a note can be reached through its alternate names without changing its canonical permalink.

Japanese

What it does

When a vault note has frontmatter like

md
---
title: Old Note
aliases:
  - legacy-note
  - "old notes"
---

the plugin registers redirects such as:

  • /legacy-note → the note's canonical permalink
  • /old%20notes → the note's canonical permalink

Redirects are written into the build-time manifest and resolved by HonoX at request time. No client-side JavaScript is required.

Setup

ts
import { defineConfig } from "@riebeckite/core";
import { aliasPlugin } from "@riebeckite/plugin-alias";
 
export default defineConfig({
  // ...
  plugins: [aliasPlugin()],
});

It composes with the permalink plugin. alias augments already-resolved public locations through extendContentLocations, so it never overrides or re-derives the canonical permalink, whatever decided it.

ts
plugins: [permalinkPlugin(), aliasPlugin()],

Options

Option Type Default Description
status 301 | 302 | 307 | 308 308 HTTP status used for generated redirects

Alias normalization

An alias is treated as an alternate note name and mapped to a path under the site root:

  • A leading / is ignored (Old and /Old both become /Old).
  • Path separators are allowed (archive/Old → /archive/Old).
  • Each segment is percent-encoded with the same rules as request paths, so non-ASCII and spaces work as-is.
  • An alias that cannot become a URL is skipped with a warning:
    • empty, or only . / .. segments
    • containing #, ?, or \
    • containing // (an empty segment)
    • containing malformed percent escapes

Diagnostics

Code Severity Meaning
alias-invalid warning The alias cannot be converted into a URL path.
alias-collision warning The alias path collides with another note's canonical permalink or an existing redirect.

A colliding alias is not registered; the existing path wins.

Limitations

  • Redirects are decided at build time; add or change aliases and rebuild the site.
  • SSG does not emit dedicated redirect HTML files. Redirects are resolved by the server (resolveContentRoute in HonoX).
  • Aliases are not part of the content graph (backlinks); only links written in the Markdown count.

Exports

  • aliasPlugin(options?) / alias(options?) — the plugin factory
  • resolveAliasPath(alias) — pure alias-to-path helper (returns null when invalid)
  • Types: AliasOptions, AliasRedirectStatus, ResolvedAliasOptions

See also

History

1 changesCollapseExpand
1 + <!-- Generated from packages/plugins/alias/README.md. Do not edit this page directly; edit the package README and run `pnpm docs:sync`. -->
2 +
3 + # Alias
4 +
5 + Turns Obsidian `aliases` / `alias` frontmatter into site-local redirect URLs, so a note can be reached through its alternate names without changing its canonical permalink.
6 +
7 + [Japanese](./alias.md)
8 +
9 + ## What it does
10 +
11 + When a vault note has frontmatter like
12 +
13 + ```md
14 + ---
15 + title: Old Note
16 + aliases:
17 + - legacy-note
18 + - "old notes"
19 + ---
20 + ```
21 +
22 + the plugin registers redirects such as:
23 +
24 + - `/legacy-note` → the note's canonical permalink
25 + - `/old%20notes` → the note's canonical permalink
26 +
27 + Redirects are written into the build-time manifest and resolved by HonoX at request time. No client-side JavaScript is required.
28 +
29 + ## Setup
30 +
31 + ```ts
32 + import { defineConfig } from "@riebeckite/core";
33 + import { aliasPlugin } from "@riebeckite/plugin-alias";
34 +
35 + export default defineConfig({
36 + // ...
37 + plugins: [aliasPlugin()],
38 + });
39 + ```
40 +
41 + It composes with the `permalink` plugin. `alias` augments already-resolved public locations through `extendContentLocations`, so it never overrides or re-derives the canonical permalink, whatever decided it.
42 +
43 + ```ts
44 + plugins: [permalinkPlugin(), aliasPlugin()],
45 + ```
46 +
47 + ## Options
48 +
49 + | Option | Type | Default | Description |
50 + | --- | --- | --- | --- |
51 + | `status` | `301 \| 302 \| 307 \| 308` | `308` | HTTP status used for generated redirects |
52 +
53 + ## Alias normalization
54 +
55 + An alias is treated as an alternate note name and mapped to a path under the site root:
56 +
57 + - A leading `/` is ignored (`Old` and `/Old` both become `/Old`).
58 + - Path separators are allowed (`archive/Old` → `/archive/Old`).
59 + - Each segment is percent-encoded with the same rules as request paths, so non-ASCII and spaces work as-is.
60 + - An alias that cannot become a URL is skipped with a warning:
61 + - empty, or only `.` / `..` segments
62 + - containing `#`, `?`, or `\`
63 + - containing `//` (an empty segment)
64 + - containing malformed percent escapes
65 +
66 + ## Diagnostics
67 +
68 + | Code | Severity | Meaning |
69 + | --- | --- | --- |
70 + | `alias-invalid` | warning | The alias cannot be converted into a URL path. |
71 + | `alias-collision` | warning | The alias path collides with another note's canonical permalink or an existing redirect. |
72 +
73 + A colliding alias is not registered; the existing path wins.
74 +
75 + ## Limitations
76 +
77 + - Redirects are decided at build time; add or change aliases and rebuild the site.
78 + - SSG does not emit dedicated redirect HTML files. Redirects are resolved by the server (`resolveContentRoute` in HonoX).
79 + - Aliases are not part of the content graph (backlinks); only links written in the Markdown count.
80 +
81 + ## Exports
82 +
83 + - `aliasPlugin(options?)` / `alias(options?)` — the plugin factory
84 + - `resolveAliasPath(alias)` — pure alias-to-path helper (returns `null` when invalid)
85 + - Types: `AliasOptions`, `AliasRedirectStatus`, `ResolvedAliasOptions`
86 +
87 + ## Related
88 +
89 + - [Plugin system](../reference/plugin-api.en.md)
90 +
91 + ## See also
92 +
93 + - [Plugin guide](../reference/plugin-api.en.md)
94 +