From 3d7ea2e3eb06350800b33e2531ee7820fd1fced0 Mon Sep 17 00:00:00 2001 From: Kevin Van Lierde Date: Wed, 13 Dec 2023 00:34:22 +0100 Subject: [PATCH] Updates README.md & types for v3.0.0 --- README.md | 247 ++++++++++++++++++++++++++++++++++++++----------- lib/index.d.ts | 34 +++---- 2 files changed, 204 insertions(+), 77 deletions(-) diff --git a/README.md b/README.md index 010bed0..0218d23 100644 --- a/README.md +++ b/README.md @@ -24,6 +24,10 @@ yarn add @metalsmith/permalinks ## Usage +By default `@metalsmith/permalinks` moves all HTML source files at `:dirname?/:basename` to the build as `:dirname/:basename/index.html` and adds [a customizable `permalink` property](#customizing-permalinks) to te file metadata. You can tweak [which files to `match`](#matching-files), set [fixed permalinks](#fixed-permalinks), use a permalink `pattern` with `:placeholder`'s that will be read from the file's metadata, and finetune how that metadata and the final permalink are formatted as a string through the `directoryIndex`, `slug`, `date` and `trailingSlash` options. + +Fixed permalinks or permalink patterns can be defined in file front-matter, or for a set of files through plugin options. Permalink patterns defined in file front-matter take precedence over plugin options. + ```js import { dirname } from 'path' import { fileURLToPath } from 'url' @@ -32,24 +36,151 @@ import permalinks from '@metalsmith/permalinks' const __dirname = dirname(fileURLToPath(import.meta.url)) +// defaults +Metalsmith(__dirname).use(permalinks()) + +// explicit defaults Metalsmith(__dirname).use( permalinks({ - pattern: ':title' + // files to target + match: '**/*.html', + // permalink pattern with placeholders + pattern: ':dirname?/:basename', + // how to format Date values when substituting pattern parts + date: { + format: 'YYYY/MM/DD', + locale: 'en-US' // only relevant if you use textual date part formats + }, + // how to postprocess a resolved permalink in a URL (and filesystem)-friendly way + slug: { + lowercase: true, + remove: /[<>:"\'|?*]|[^\\w\\s$_+~.()!\\-@\\/]+/g, + extend: { ':': '-', '|': '-', '/': '-', '<': '', '>': '' } + }, + trailingSlash: false, + directoryIndex: 'index.html', + // throw an error when 2 files have the same target permalink + duplicates: 'error', + // additional linksets + linksets: [] + }) +) +``` + +Every `permalinks()` instantiation supports the following options: + +- directoryIndex - traditionally `index.html`, but servers could be configured with alternatives. See [Overriding the default index.html file](#overriding-the-default-indexhtml-file) +- trailingSlash - whether to add a trailing `/` so that the permalink becomes `blog/post/` instead of `blog/post`. Useful to avoid redirects on servers which do not have a built-in rewrite module enabled. +- duplicates - what to do when 2 files have the same target destination. See [Ensure files have unique URI's](#ensure-files-have-unique-uris) +- linksets + +### Matching files + +The `match` option can be 1 or multiple glob patterns, or an object with key-value pairs that will be matched on _either... or..._ basis. + +```js +// only match non-root html files +metalsmith.use(permalinks({ match: '*/**/*.html' })) + +// match templates so you can use the permalink property in @metalsmith/layouts later +metalsmith.use(permalinks({ match: '**/*.hbs' })) + +// match files that are either primary:false or have id:1 +metalsmith.use(permalinks({ match: { primary: false, id: 1 } })) +``` + +If a `match` object property targets an array in file metadata, it will be matched if the array contains the value in the `match` object. + +### Defining linksets + +Whereas the default `match` option globally defines which files are permalinked, additional `linksets` can be defined with their own `match`, `pattern`, `date` and `slug` options. + +```js +metalsmith.use( + permalinks({ + // original options act as the keys of a `default` linkset, + pattern: ':dirname?/:basename', + date: 'YYYY', + + // each linkset defines a match, and any other desired option + linksets: [ + { + match: { collection: 'blogposts' }, + pattern: 'blog/:date/:title', + date: 'MM-DD-YYYY' + }, + { + match: { collection: 'pages' }, + pattern: 'pages/:title' + } + ] }) ) ``` +Every matched file is only permalinked once, even if it is matched by multiple linksets. The linksets defined in `linksets` take precedence over the default match, and the first linkset in `linksets` takes precedence over the next. In the example above, a file which has `collection: ['pages','blogposts']` would be permalinked to `blog/:date/:title`. + +### Fixed permalinks + +You can declare a fixed permalink in file front-matter: + +```yml +--- +# src/topic_metalsmith.html +permalink: topics/static-site/metalsmith +--- +``` + +`@metalsmith/permalinks` will move the source file `topic_metalsmith.html` to the build path `topics/static-site/metalsmith/index.html` and add `permalink: 'topics/static-site/metalsmith'` to the file metadata. +Setting an explicit front-matter permalink overrides any other `match` that also matched the file from plugin options. + +_Typical use case: SEO-sensitive links that should be preserved, even if you moved or renamed the file or updated its front-matter._ + +### Computed permalinks + +File permalinks can be computed from other (own) file metadata properties. + +```yml +--- +# src/topic_metalsmith.html +topic: static-site +subtopic: metalsmith +permalink: topics/:topic/:subtopic +--- +``` + +Just like the previous example, this will also move the source file `topic_metalsmith.html` to the build path `topics/static-site/metalsmith/index.html` and add `permalink: 'topics/static-site/metalsmith'` to the file metadata. + +Placeholders can also refer to a keypath within the front-matter `permalink` or plugin option linkset, e.g. `permalink: blog/:postData.html.slug`. + +### Skipping permalinks + +An otherwise linkset-matched file can be excluded from permalinking by setting `permalink: false` in its front-matter: + +```yaml +--- +title: error +permalink: false +--- +``` + +Explicitly disabling a permalink in front-matter overrides any other pattern that also matched the file from plugin options. + +_Typical use case: hosting static sites on third-party providers with specific conventions, e.g. on AWS S3 there must be a top level `error.html` file and not an `error/index.html` file._ + +### Customizing permalinks + The `pattern` can contain a reference to **any piece of metadata associated with the file** by using the `:PROPERTY` syntax for placeholders. -By default, all files get a `:dirname/:basename` (+ directoryIndex = `/index.html`) pattern, i.e. the original filepath `blog/post1.html` becomes `blog/post1/index.html`. The `dirname` and `basename` values are automatically made available by @metalsmith/permalinks for the purpose of generating the permalink. +By default, all files get a `:dirname?/:basename` (+ directoryIndex = `/index.html`) pattern, i.e. the original filepath `blog/post1.html` becomes `blog/post1/index.html`. The `dirname` and `basename` values are automatically made available by @metalsmith/permalinks for the purpose of generating the permalink. -If no pattern is provided, the files won't be remapped, but the `permalink` metadata key will still be set, so that you can use it for outputting links to files in the template. +If you want to tweak how the characters in the permalink are transformed (for example to handle unicode & non-ascii characters),see [slug options](#slug-options). The `pattern` can also be set as such: ```js metalsmith.use( permalinks({ - // original options would act as the keys of a `default` linkset, + // original options act as the keys of a `default` linkset, pattern: ':title', date: 'YYYY', @@ -58,7 +189,7 @@ metalsmith.use( { match: { collection: 'blogposts' }, pattern: 'blog/:date/:title', - date: 'mmddyy' + date: 'MM-DD-YYYY' }, { match: { collection: 'pages' }, @@ -69,9 +200,9 @@ metalsmith.use( ) ``` -### Optional permalink pattern parts +#### Optional permalink pattern parts -The pattern option can also contain optional placeholders with the syntax `:PROPERTY?`. If the property is not defined in a file's metadata, it will be replaced with an empty string `''`. For example the pattern `:category?/:title` applied to a source directory with 2 files: +The permalink example in [Computed permalinks](#computed-permalinks) would result in an error if `subtopic` or `topic` were not defined. To allow this add a question mark to the placeholder like `:topic/:subtopic?`. If the property is not defined in a file's metadata, it will be replaced with an empty string `''`. For example the pattern `:category?/:title` applied to a source directory with 2 files: @@ -97,7 +228,7 @@ build └── no-category/index.html ``` -### Dates +#### Date formatting By default any date will be converted to a `YYYY/MM/DD` format when using in a permalink pattern, but you can change the conversion by passing a `date` option: @@ -135,7 +266,7 @@ Starting from v3 `@metalsmith/permalinks` no longer uses moment.js. A subset of Tokens marked with (\*) use the [Node.js Intl API](https://nodejs.org/api/intl.html) which is not available by default in every Node.js distribution. The `date` option can be a string of date-formatting tokens and will default to `en-US` for the locale, or an object in the format `{ format: 'YYYY', locale: 'en-US' }`. However, if your Node.js distribution does not have support for the Intl API, or the locale you specified is missing, the build will throw an error. -### Slug options +#### Slug options You can finetune how a pattern is processed by providing custom [slug](https://developer.mozilla.org/en-US/docs/Glossary/Slug) options. By default [slugify](https://www.npmjs.com/package/slugify) is used and patterns will be lowercased. @@ -169,74 +300,43 @@ metalsmith.use( ) ``` -#### Handling special characters - -If your pattern parts contain special characters like `:` or `=`, specifying `slug.strict` as `true` is a quick way to remove them: - -```js -metalsmith.use( - permalinks({ - slug: { - lower: true, - strict: true - } - }) -) -``` - #### Custom 'slug' function If the result is not to your liking, you can replace the slug function altogether. For now only the js version of syntax is supported and tested. ```js +import { slugify } from 'transliteration' + metalsmith.use( permalinks({ pattern: ':title', - slug: require('transliteration').slugify + slug: slugify }) ) ``` There are plenty of other options on npm for transliteration and slugs. . -### Skipping Permalinks for a file - -A file can be ignored by the permalinks plugin if you pass the `permalink: false` option to the yaml metadata of a file. -This is useful for hosting a static site on AWS S3, where there is a top level `error.html` file and not an `error/index.html` file. - -For example, in your error.md file: - -```js ---- -template: error.html -title: error -permalink: false ---- -``` - -### Overriding the permalink for a file - -Using the `permalink` property in a file's front-matter, its permalink can be overridden. This can be useful for transferring -projects over to Metalsmith where pages don't follow a strict permalink system. +### Overriding the default `index.html` file -For example, in one of your pages: +Use `directoryIndex` to define a custom index file. ```js ---- -title: My Post -permalink: "posts/my-post" ---- +metalsmith.use( + permalinks({ + directoryIndex: 'alt.html' + }) +) ``` -### Overriding the default `index.html` file - -Use `indexFile` to define a custom index file. +Use an empty `directoryIndex` to create _extensionless_ files that can be accompanied by a matching Content-Type Response header with a server like Apache or Nginx, so you could call `https://mysite.com/api/plugins` supposing you have files at `src/api/plugins.json` ```js metalsmith.use( permalinks({ - indexFile: 'alt.html' + match: '**/*.json', + directoryIndex: '' }) ) ``` @@ -254,7 +354,7 @@ metalsmith.use( ) ``` -There are 3 other possible values for the `duplicates` option: `index` will add an `-` suffix to other files with the same target URI, , `overwrite` will silently overwrite previous files with the same target URI. +There are 3 other possible values for the `duplicates` option: `index` will add an `-` suffix to other files with the same target URI, `overwrite` will silently overwrite previous files with the same target URI. The third possibility is to provide your own function to handle duplicates, with the signature: @@ -276,6 +376,45 @@ The example above is a variant of the `index` value, where 2 files targeting the _Note_: The `duplicates` option combines the `unique` and `duplicatesFail` options of version < 2.4.1. Specifically, `duplicatesFail:true` maps to `duplicates:'error'`, `unique:true` maps to `duplicates:'index'`, and `unique:false` or `duplicatesFail:false` map to `duplicates:'overwrite'`. +### Maintaining relative links + +Previously this plugin had a `relative: true` option that allowed one to transform a file structure such as: + +```txt +|_ posts + |_ hello-world.html + |_ post-image.png +``` + +into + +```txt +|_ posts + |_ hello-world + | |_ index.html + | |_ post-image.png + |_ post-image.png +``` + +This allowed users to reference post-image.png as ``, but also duplicated the asset and resulted in other unexpected side-effects. +Our advice is to keep your media in an `assets` or similar folder that does not undergo path transforms, and reference it with a root-relative URI (eg `/assets/hello-world/post-image.png`). If this is not an option for you, the better way to structure your source folder is to have the source path of the referencing HTML file equal to its destination permalink: + +```txt +|_ posts + |_ hello-world + |_ index.html + |_ post-image.png +``` + +### Migrating from v2 to v3 + +The v2 -> v3 update had a lot of breaking changes, but the good news is v3 can do all that v2 did, just a bit differently, and more. v3 is less forgiving (and more predictable) in that it will throw errors when a (required) `:placeholder` resolves to an undefined value. + +Previously permalinks would omit that pattern part so that a `my-post.html` with pattern `:category/:title` and `title: My post` but without a defined category would be output to `blog/my-post/index.html`. To preserve this behavior, make the failing `:placeholder?` optional by adding a question mark. + +The `indexFile` option has been renamed to `directoryIndex`. +The options `duplicatesFail` and `unique` have been condensed into `duplicates`, see also [Ensure files have unique URI's](#ensure-files-have-unique-uris). + ### Debug To enable debug logs, set the `DEBUG` environment variable to `@metalsmith/permalinks`: diff --git a/lib/index.d.ts b/lib/index.d.ts index 3fca10e..5a01869 100644 --- a/lib/index.d.ts +++ b/lib/index.d.ts @@ -39,10 +39,6 @@ export type slugFunction = (filepath: string) => string; * Linkset definition */ export type Linkset = { - /** - * Whether this linkset should be used as the default instead - */ - isDefault?: boolean; /** * A glob pattern or array of glob patterns passed to {@linkcode Metalsmith.match}, or an object whose `key:value` pairs * will be used to match files when at least one `key:value` pair matches, and transform their permalinks according to the rules in this linkset. @@ -56,15 +52,17 @@ export type Linkset = { [x: string]: any; }; /** - * A permalink pattern to transform file paths into, e.g. `blog/:date/:title` + * A permalink pattern to transform file paths into, e.g. `blog/:date/:title`. + * @default ':dirname?/:basename' */ - pattern: string; + pattern?: string; /** * [Slugify options](https://github.com/simov/slugify) or a custom slug function of the form `(pathpart) => string` */ slug?: SlugifyOptions | slugFunction; /** - * [Moment.js format string](https://momentjs.com/docs/#/displaying/format/) to transform Date link parts into, defaults to `YYYY/MM/DD`. + * [Date format string](https://github.com/metalsmith/permalinks#dates) to transform Date link parts into, defaults to `YYYY/MM/DD`. + * @default 'YYYY/MM/DD' */ date?: string; }; @@ -72,36 +70,26 @@ export type Linkset = { * `@metalsmith/permalinks` options & default linkset */ export type Options = { - /** - * A permalink pattern to transform file paths into, e.g. `blog/:date/:title`. - * @default ':dirname/:basename' - */ - pattern?: string; - /** - * [Moment.js format string](https://momentjs.com/docs/#/displaying/format/) to transform Date link parts into, defaults to `YYYY/MM/DD`. - */ - date?: string; /** * Basename of the permalinked file (default: `index.html`) + * @default 'index.html' */ directoryIndex?: string; /** - * Whether a trailing `/` should be added to the `file.permalink` property. Useful to avoid redirects on servers which do not have a built-in rewrite module enabled. + * Whether a trailing `/` should be added to the `file.permalink` property. Useful to avoid redirects on servers (like `express.js`) which do not have a built-in rewrite module enabled. + * @default false */ trailingSlash?: boolean; /** * How to handle duplicate target URI's. + * @default 'error' */ duplicates?: 'error'|'index'|'overwrite'|Function /** - * An array of additional linksets + * An array of additional linksets. */ linksets?: Linkset[]; - /** - * {@link SlugifyOptions} or a custom slug function of the form `(pathpart) => string` - */ - slug?: SlugifyOptions | slugFunction; -}; +} & Linkset; /** * Metalsmith plugin that renames files so that they're permalinked properly * for a static site, aka that `about.html` becomes `about/index.html`.