Folder Pages

日本語

Folder Page support for Riebeckite. The plugin turns folder entry notes into the folder's landing page and generates a listing page for folders that have no entry note.

Installation

pnpm add @riebeckite/plugin-folder-pages

Usage

import { folderPages } from "@riebeckite/plugin-folder-pages";
 
export default {
  plugins: [folderPages()],
};

Markdown-backed Folder Pages

A note at <folder>/README.md or <folder>/index.md becomes the folder's landing page. Its resolved permalink is collapsed from /folder/README or /folder/index to /folder/, and the old URL redirects to the new one.

The collapse never guesses a URL from the slug. It rewrites the permalink that the location resolver already produced, so localized and custom permalinks stay correct.

Only README and index are treated as folder entries. A note at <folder>.md stays a normal content page.

When a folder contains both README.md and index.md, neither is collapsed: the choice would be ambiguous, so the plugin leaves both notes at their default locations.

Generated Folder Pages

Folders without a markdown entry note but with discoverable content get an automatically generated page at /folder/. The page lists only the folder's direct children:

Pages: direct public, discoverable notes.
Folders: direct subfolders that contain discoverable content.

The listing is built from manifest.discoverableEntries, so unlisted, draft, and scheduled notes never appear. Notes reachable only by URL stay hidden from the navigation. The folder.md case is never confused with a folder entry.

Ordering

Pages and folders are sorted by their resolved permalink, then by title, so the output is deterministic regardless of plugin order.

Options

Option	Type	Default	Description
`className`	`string`	`"rr-folder-page"`	Root CSS class for the rendered fragment.
`pagesLabel`	`string`	`"Pages"`	Heading for the page list.
`foldersLabel`	`string`	`"Folders"`	Heading for the folder list.

Plugin dependencies

The plugin declares an optional dependency on the content.localization capability. When @riebeckite/plugin-l10n is enabled, the folder page location rewrite runs after localization so the collapsed URLs and redirects use the final, localized permalinks. Without l10n, the plugin still works on its own.

History

1 changesCollapseExpand

From To

	1	+ <!-- Generated from packages/plugins/folder-pages/README.md. Do not edit this page directly; edit the package README and run `pnpm docs:sync`. -->
	2	`+`
	3	`+ # Folder Pages`
	4	`+`
	5	`+ [日本語](./folder-pages.md)`
	6	`+`
	7	`+ Folder Page support for Riebeckite. The plugin turns folder entry notes into the`
	8	`+ folder's landing page and generates a listing page for folders that have no`
	9	`+ entry note.`
	10	`+`
	11	`+ ## Installation`
	12	`+`
	13	+ ```bash
	14	`+ pnpm add @riebeckite/plugin-folder-pages`
	15	+ ```
	16	`+`
	17	`+ ## Usage`
	18	`+`
	19	+ ```ts
	20	`+ import { folderPages } from "@riebeckite/plugin-folder-pages";`
	21	`+`
	22	`+ export default {`
	23	`+ plugins: [folderPages()],`
	24	`+ };`
	25	+ ```
	26	`+`
	27	`+ ## Markdown-backed Folder Pages`
	28	`+`
	29	+ A note at `<folder>/README.md` or `<folder>/index.md` becomes the folder's
	30	+ landing page. Its resolved permalink is collapsed from `/folder/README` or
	31	+ `/folder/index` to `/folder/`, and the old URL redirects to the new one.
	32	`+`
	33	`+ The collapse never guesses a URL from the slug. It rewrites the permalink that`
	34	`+ the location resolver already produced, so localized and custom permalinks stay`
	35	`+ correct.`
	36	`+`
	37	+ Only `README` and `index` are treated as folder entries. A note at
	38	+ `<folder>.md` stays a normal content page.
	39	`+`
	40	+ When a folder contains both `README.md` and `index.md`, neither is collapsed:
	41	`+ the choice would be ambiguous, so the plugin leaves both notes at their default`
	42	`+ locations.`
	43	`+`
	44	`+ ## Generated Folder Pages`
	45	`+`
	46	`+ Folders without a markdown entry note but with discoverable content get an`
	47	+ automatically generated page at `/folder/`. The page lists only the folder's
	48	`+ direct children:`
	49	`+`
	50	`+ - Pages: direct public, discoverable notes.`
	51	`+ - Folders: direct subfolders that contain discoverable content.`
	52	`+`
	53	+ The listing is built from `manifest.discoverableEntries`, so unlisted, draft,
	54	`+ and scheduled notes never appear. Notes reachable only by URL stay hidden from`
	55	+ the navigation. The `folder.md` case is never confused with a folder entry.
	56	`+`
	57	`+ ## Ordering`
	58	`+`
	59	`+ Pages and folders are sorted by their resolved permalink, then by title, so the`
	60	`+ output is deterministic regardless of plugin order.`
	61	`+`
	62	`+ ## Options`
	63	`+`
	64	`+ \| Option \| Type \| Default \| Description \|`
	65	`+ \| --- \| --- \| --- \| --- \|`
	66	+ \| `className` \| `string` \| `"rr-folder-page"` \| Root CSS class for the rendered fragment. \|
	67	+ \| `pagesLabel` \| `string` \| `"Pages"` \| Heading for the page list. \|
	68	+ \| `foldersLabel` \| `string` \| `"Folders"` \| Heading for the folder list. \|
	69	`+`
	70	`+ ## Plugin dependencies`
	71	`+`
	72	+ The plugin declares an optional dependency on the `content.localization`
	73	+ capability. When `@riebeckite/plugin-l10n` is enabled, the folder page location
	74	`+ rewrite runs after localization so the collapsed URLs and redirects use the`
	75	`+ final, localized permalinks. Without l10n, the plugin still works on its own.`
	76	`+`