From 4ad2f8853796c51fea714290653c5da8ec0331df Mon Sep 17 00:00:00 2001 From: Titus Date: Sat, 29 Jan 2022 11:26:17 +0100 Subject: [PATCH] Add improved docs Closes GH-89. --- doc/getting-started.md | 131 +------ doc/plugins.md | 199 +++++++---- packages/rehype-cli/readme.md | 263 +++++++++----- packages/rehype-parse/readme.md | 508 +++++++++++++++++++--------- packages/rehype-stringify/readme.md | 436 +++++++++++++++++++----- packages/rehype/readme.md | 340 ++++++++++++++----- readme.md | 290 ++++++++++++---- 7 files changed, 1477 insertions(+), 690 deletions(-) diff --git a/doc/getting-started.md b/doc/getting-started.md index 2c0edc70..9b6a99c3 100644 --- a/doc/getting-started.md +++ b/doc/getting-started.md @@ -1,131 +1,6 @@ -![rehype][logo] - # Getting started -**rehype** transforms HTML. -It’s an ecosystem of [plugins][]. -If you get stuck, [issues][] and [discussions][] are good places to get help. - -rehype is built on [unified][], make sure to read it and its [website][] too. - -## Contents - -* [Intro](#intro) -* [Command line](#command-line) -* [Programmatic](#programmatic) - -## Intro - -Out of the box, **rehype** processes HTML: it’s given, reformatted, and -written: - -```html -

Some emphasis, importance, and code. -``` - -Yields (in fragment mode): - -```html -

Some emphasis, importance, and code.

-``` - -But much can be done [through plugins][plugins]. - -## Command line - -**rehype**’s CLI is a simple way to process markdown files from the -command line. -Its interface is provided by [**unified-args**][unified-args]. - -Install [`rehype-cli`][cli] and dependencies with [npm][]: - -```sh -npm install --global rehype-cli rehype-preset-minify -``` - -`index.html` contains: - -```html - - - - - Hello - - -

World!

- - -``` - -`rehype index.html --use preset-minify` yields: - -```html -Hello

World! -``` - -```txt -index.html: no issues found -``` - -## Programmatic - -The programmatic interface of **rehype** is provided by [**unified**][unified]. -In fact, [`rehype`][api] is two plugins: -[`rehype-parse`][parse] and [`rehype-stringify`][stringify]. - -Install [`rehype`][api] with [npm][]: - -```sh -npm install rehype -``` - -`index.js` contains: - -```js -import {reporter} from 'vfile-reporter' -import {rehype} from 'rehype' - -rehype() - .process('Hi

Hello world!') - .then((file) => { - console.log(String(file)) - console.log(reporter(file)) - }) -``` - -`node index.js` yields: - -```html -Hi

Hello world!

-``` - -```txt -no issues found -``` - - - -[logo]: https://raw.githubusercontent.com/rehypejs/rehype/cb624bd/logo.svg?sanitize=true - -[issues]: https://github.com/rehypejs/rehype/issues - -[discussions]: https://github.com/rehypejs/rehype/discussions - -[npm]: https://docs.npmjs.com/cli/install - -[api]: https://github.com/rehypejs/rehype/tree/main/packages/rehype - -[plugins]: https://github.com/rehypejs/rehype/tree/main/doc/plugins.md - -[unified]: https://github.com/unifiedjs/unified - -[website]: https://unifiedjs.com - -[parse]: https://github.com/rehypejs/rehype/tree/main/packages/rehype-parse - -[stringify]: https://github.com/rehypejs/rehype/tree/main/packages/rehype-stringify - -[unified-args]: https://github.com/unifiedjs/unified-args +See [the monorepo readme][rehype] for what the rehype ecosystem is and examples +of how to get started. -[cli]: https://github.com/rehypejs/rehype/tree/main/packages/rehype-cli +[rehype]: https://github.com/rehypejs/rehype diff --git a/doc/plugins.md b/doc/plugins.md index 985abec4..c0efb674 100644 --- a/doc/plugins.md +++ b/doc/plugins.md @@ -2,8 +2,9 @@ # Plugins -**rehype** is an HTML processor powered by plugins part of the [unified][] -[collective][]. +**rehype** is a tool that transforms HTML with plugins. +See [the monorepo readme][rehype] for info on what the rehype ecosystem is. +This page lists existing plugins. ## Contents @@ -14,12 +15,16 @@ ## List of plugins -See [awesome rehype][awesome] for the most awesome projects in the ecosystem. -More plugins can be found on GitHub tagged with the [`rehype-plugin` -topic][topic]. +See [`awesome-rehype`][awesome-rehype] for the most awesome projects in the +ecosystem. +More plugins can be found on GitHub tagged with the +[`rehype-plugin` topic][topic]. -Have a good idea for a new plugin? -See [Create plugins][create] below. +> 💡 **Tip**: rehype plugins work with HTML and **remark** plugins work with +> markdown. +> See remark’s [List of plugins][remark-plugins] for more plugins. + +The list of plugins: * [`rehype-accessible-emojis`](https://github.com/GaiAma/Coding4GaiAma/tree/HEAD/packages/rehype-accessible-emojis) — make emojis accessible adding role & aria-label @@ -28,77 +33,161 @@ See [Create plugins][create] below. * [`rehype-annotate`](https://github.com/baldurbjarnason/rehype-annotate) — add W3C-style annotations * [`rehype-attr`](https://github.com/jaywcjlove/rehype-attr) - — new syntax to add attributes to Markdown. + — new markdown syntax to add attributes. * [`rehype-autolink-headings`](https://github.com/rehypejs/rehype-autolink-headings) — add links to headings +* [`rehype-citation`](https://github.com/timlrx/rehype-citation) + — add citation and bibliography from bibtex * [`rehype-components`](https://github.com/marekweb/rehype-components) — render components (custom elements) +* [`rehype-concat-css-style`](https://github.com/rehypejs/rehype-minify/tree/main/packages/rehype-concat-css-style) + — concatenate `