From cbb2a30ab78665402dad15ab8d70dca382270b3d Mon Sep 17 00:00:00 2001 From: Titus Date: Sun, 23 Jan 2022 09:34:52 +0100 Subject: [PATCH] Add improved docs Closes GH-1. Reviewed-by: Christian Murphy --- readme.md | 99 ++++++++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 79 insertions(+), 20 deletions(-) diff --git a/readme.md b/readme.md index 738f24c..d909589 100644 --- a/readme.md +++ b/readme.md @@ -8,36 +8,70 @@ [![Backers][backers-badge]][collective] [![Chat][chat-badge]][chat] -[**rehype**][rehype] plugin to infer the estimated reading time from a document -as file metadata. -This plugin sets `file.data.meta.readingTime`. -This is mostly useful with [`rehype-meta`][rehype-meta]. +**[rehype][]** plugin to infer the estimated reading time of a document. ## Contents +* [What is this?](#what-is-this) +* [When should I use this?](#when-should-i-use-this) * [Install](#install) * [Use](#use) * [API](#api) * [`unified().use(rehypeInferReadingTimeMeta, options?)`](#unifieduserehypeinferreadingtimemeta-options) +* [Types](#types) +* [Compatibility](#compatibility) * [Security](#security) * [Related](#related) * [Contribute](#contribute) * [License](#license) -## Install +## What is this? + +This package is a [unified][] ([rehype][]) plugin to infer the estimated reading +time of a document. +The estimation takes readability, calibrated relative to the target audience, +into account. -This package is [ESM only](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c): -Node 12+ is needed to use it and it must be `import`ed instead of `require`d. +**unified** is a project that transforms content with abstract syntax trees +(ASTs). +**rehype** adds support for HTML to unified. +**vfile** is the virtual file interface used in unified. +**hast** is the HTML AST that rehype uses. +This is a rehype plugin that inspects hast and adds metadata to vfiles. -[npm][]: +## When should I use this? + +This plugin is particularly useful in combination with +[`rehype-meta`][rehype-meta]. +When both are used together and documents are shared, the estimated reading time +is shown on Slack or certain other services. + +## Install + +This package is [ESM only](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c). +In Node.js (version 12.20+, 14.14+, or 16.0+), install with [npm][]: ```sh npm install rehype-infer-reading-time-meta ``` +In Deno with [Skypack][]: + +```js +import rehypeInferReadingTimeMeta from 'https://cdn.skypack.dev/rehype-infer-reading-time-meta@1?dts' +``` + +In browsers with [Skypack][]: + +```html + +``` + ## Use -Say `example.js` looks as follows: +Say our module `example.js` looks as follows: ```js import {unified} from 'unified' @@ -66,7 +100,7 @@ async function main() { } ``` -Now, running `node example` yields: +Now running `node example.js` yields: ```html @@ -92,10 +126,14 @@ The default export is `rehypeInferReadingTimeMeta`. ### `unified().use(rehypeInferReadingTimeMeta, options?)` -Plugin to infer the estimated reading time from a document as file metadata. - +Infer the estimated reading time from a document as file metadata. The reading time is inferred not just on words per minute, but also takes readability into account. +The result is stored on `file.data.meta.readingTime`. + +##### `options` + +Configuration (optional). ##### `options.age` @@ -111,6 +149,21 @@ CSS selector to body of content (`string`, optional, example: `'main'`). Useful to exclude other things, such as the head, ads, styles, scripts, and other random stuff, by focussing on one element. +## Types + +This package is fully typed with [TypeScript][]. +The extra type `Options` is exported. + +## Compatibility + +Projects maintained by the unified collective are compatible with all maintained +versions of Node.js. +As of now, that is Node.js 12.20+, 14.14+, and 16.0+. +Our projects sometimes work with older versions, but this is not guaranteed. + +This plugin works with `rehype-parse` version 3+, `rehype-stringify` version 3+, +`rehype` version 4+, and `unified` version 6+. + ## Security Use of `rehype-infer-reading-time-meta` is safe. @@ -118,15 +171,15 @@ Use of `rehype-infer-reading-time-meta` is safe. ## Related * [`rehype-document`](https://github.com/rehypejs/rehype-document) - — Wrap a document around a fragment + — wrap a fragment in a document * [`rehype-meta`](https://github.com/rehypejs/rehype-meta) - — Add metadata to the head of a document + — add metadata to the head of a document * [`unified-infer-git-meta`](https://github.com/unifiedjs/unified-infer-git-meta) - — Infer file metadata from Git + — infer file metadata from Git * [`rehype-infer-title-meta`](https://github.com/rehypejs/rehype-infer-title-meta) - — Infer file metadata from the title of a document + — infer file metadata from the title of a document * [`rehype-infer-description-meta`](https://github.com/rehypejs/rehype-infer-description-meta) - — Infer file metadata from the description of a document + — infer file metadata from the description of a document ## Contribute @@ -172,18 +225,24 @@ abide by its terms. [npm]: https://docs.npmjs.com/cli/install +[skypack]: https://www.skypack.dev + [health]: https://github.com/rehypejs/.github -[contributing]: https://github.com/rehypejs/.github/blob/HEAD/contributing.md +[contributing]: https://github.com/rehypejs/.github/blob/main/contributing.md -[support]: https://github.com/rehypejs/.github/blob/HEAD/support.md +[support]: https://github.com/rehypejs/.github/blob/main/support.md -[coc]: https://github.com/rehypejs/.github/blob/HEAD/code-of-conduct.md +[coc]: https://github.com/rehypejs/.github/blob/main/code-of-conduct.md [license]: license [author]: https://wooorm.com +[typescript]: https://www.typescriptlang.org + +[unified]: https://github.com/unifiedjs/unified + [rehype]: https://github.com/rehypejs/rehype [rehype-meta]: https://github.com/rehypejs/rehype-meta