readme
A Lume plugin that uses README.md or specified page as homepage of the
website, as on GitHub Pages and docsify.
Problem
By default, Lume generates URLs like this:
/docs/getting-started/README.md → /docs/getting-started/README/This plugin transforms them to:
/docs/getting-started/README.md → /docs/getting-started/Usage
Basic usage
Transform all README files to directory URLs:
import readme from "https://deno.land/x/lume_readme/mod.ts";
site.use(readme());Custom homepage basenames
Specify a custom ordered array of basenames to transform:
site.use(readme({
homepage: ["home", "index", "README"],
}));Do not include file extensions — Lume’s srcPath is extension-less. The first
match in the array wins. Matching is case insensitive.
Exclude paths
Skip transformation for specific directories:
site.use(readme({
exclude: ["/blog/", "/notes/"],
}));Include only specific paths
Only transform files in specified directories:
site.use(readme({
include: ["/docs/", "/guides/"],
}));Note:
excludeandincludecannot be used together.
Options
| Option | Type | Default | Description |
|---|---|---|---|
homepage |
string[] |
["README"] |
Ordered array of homepage basenames (case insensitive, no extensions, first match wins) |
exclude |
string[] |
[] |
Paths to skip (must start and end with /) |
include |
string[] |
[] |
Paths to process exclusively (must start and end with /) |
Plugin ordering
Register this plugin before any other plugins that modify page URLs (e.g.,
slugify_urls). The plugin detects explicit user-set URLs by comparing against
Lume’s auto-generated default; if another preprocessor modifies the URL first,
this detection may fail.
Behavior
- Pretty URLs enabled (default):
README.md→/path/to/ - Pretty URLs disabled:
README.md→/path/to/index.html - Explicit URL set: If a page has
urlin front matter, it is preserved - Nested homepage files: Each is transformed to its parent directory URL