From 98910d4157d2d5f14306fdc8aec5ee91109660fe Mon Sep 17 00:00:00 2001 From: Titus Wormer Date: Sun, 22 Mar 2020 10:34:17 +0100 Subject: [PATCH] Refactor prose --- doc/getting-started.md | 38 +++++++++++++++++------------ doc/plugins.md | 22 ++++++++--------- package.json | 6 +++++ packages/rehype-cli/readme.md | 6 ++--- packages/rehype-parse/readme.md | 8 +++--- packages/rehype-stringify/readme.md | 10 ++++---- packages/rehype/readme.md | 14 +++++------ readme.md | 8 +++--- 8 files changed, 62 insertions(+), 50 deletions(-) diff --git a/doc/getting-started.md b/doc/getting-started.md index 54b12327..9657640b 100644 --- a/doc/getting-started.md +++ b/doc/getting-started.md @@ -1,22 +1,22 @@ ![rehype][logo] -# Getting Started +# Getting started -**rehype** transforms natural language. +**rehype** transforms HTML. It’s an ecosystem of [plugins][]. If you get stuck, [issues][] and [spectrum][] are good places to get help. rehype is built on [unified][], make sure to read it and its [website][] too. -## Table of Contents +## Contents -* [Introduction](#introduction) -* [Command-line](#command-line) -* [Programmatic usage](#programmatic-usage) +* [Intro](#intro) +* [Command line](#command-line) +* [Programmatic](#programmatic) -## Introduction +## Intro -Out of the box, **rehype** transpiles HTML: it’s given, reformatted, and +Out of the box, **rehype** processes HTML: it’s given, reformatted, and written: ```html @@ -31,7 +31,7 @@ Yields (in fragment mode): But much can be done [through plugins][plugins]. -## Command-line +## Command line **rehype**’s CLI is a simple way to process markdown files from the command line. @@ -39,13 +39,13 @@ Its interface is provided by [**unified-args**][unified-args]. Install [`rehype-cli`][cli] and dependencies with [npm][]: -```bash +```sh npm install --global rehype-cli rehype-preset-minify ``` `index.html` contains: -```md +```html @@ -60,12 +60,15 @@ npm install --global rehype-cli rehype-preset-minify `rehype index.html --use preset-minify` yields: -```txt +```html Hello

World! +``` + +```txt index.html: no issues found ``` -## Programmatic usage +## Programmatic The programmatic interface of **rehype** is provided by [**unified**][unified]. In fact, [`rehype`][api] is two plugins: @@ -73,7 +76,7 @@ In fact, [`rehype`][api] is two plugins: Install [`rehype`][api] with [npm][]: -```bash +```sh npm install rehype ``` @@ -84,16 +87,19 @@ var rehype = require('rehype') var report = require('vfile-reporter') rehype().process('Hi

Hello world!', function(err, file) { - console.log(report(err || file)) console.log(String(file)) + console.log(report(err || file)) }) ``` `node index.js` yields: +```html +Hi

Hello world!

+``` + ```txt no issues found -Hi

Hello world!

``` diff --git a/doc/plugins.md b/doc/plugins.md index f67a34fe..da52c2ab 100644 --- a/doc/plugins.md +++ b/doc/plugins.md @@ -5,21 +5,21 @@ **rehype** is an HTML processor powered by plugins part of the [unified][] [collective][]. -## Table of Contents +## Contents -* [List of Plugins](#list-of-plugins) -* [List of Utilities](#list-of-utilities) -* [Using plugins](#using-plugins) -* [Creating plugins](#creating-plugins) +* [List of plugins](#list-of-plugins) +* [List of utilities](#list-of-utilities) +* [Use plugins](#use-plugins) +* [Create plugins](#create-plugins) -## List of Plugins +## 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]. Have a good idea for a new plugin? -See [Creating plugins][create] below. +See [Create plugins][create] below. * [`rehype-accessible-emojis`](https://github.com/GaiAma/Coding4GaiAma/tree/master/packages/rehype-accessible-emojis) — make emojis accessible adding role & aria-label @@ -81,7 +81,7 @@ See [Creating plugins][create] below. * [`rehype-webparser`](https://github.com/Prettyhtml/prettyhtml/tree/master/packages/rehype-webparser) — less strict HTML parser -## List of Utilities +## List of utilities See [**hast**][hast-util] for a list of utilities for working with the syntax tree. @@ -90,7 +90,7 @@ nodes, too. Finally, see [**vfile**][vfile-util] for a list of utilities working with virtual files. -## Using plugins +## Use plugins To use a plugin programmatically, invoke the [`use()`][unified-use] function. @@ -98,7 +98,7 @@ function. To use plugin with `rehype-cli`, pass a [`--use` flag][unified-args-use] or specify it in a [configuration file][config-file-use]. -## Creating plugins +## Create plugins Have an idea for a plugin? Post it on [spectrum][] or in [ideas][] and make it happen! @@ -151,4 +151,4 @@ use `unist-util-`, and if it works with virtual files, use `vfile-`. [collective]: https://opencollective.com/unified -[create]: #creating-plugins +[create]: #create-plugins diff --git a/package.json b/package.json index ba73a129..6313b365 100644 --- a/package.json +++ b/package.json @@ -62,6 +62,12 @@ "remarkConfig": { "plugins": [ "preset-wooorm", + [ + "toc", + { + "heading": "contents" + } + ], "./script/parse-error" ] } diff --git a/packages/rehype-cli/readme.md b/packages/rehype-cli/readme.md index 839846f5..a41ba21b 100644 --- a/packages/rehype-cli/readme.md +++ b/packages/rehype-cli/readme.md @@ -128,8 +128,8 @@ Ideas for new plugins and tools can be posted in [`rehypejs/ideas`][ideas]. A curated list of awesome rehype resources can be found in [**awesome rehype**][awesome]. -This project has a [Code of Conduct][coc]. -By interacting with this repository, organisation, or community you agree to +This project has a [code of conduct][coc]. +By interacting with this repository, organization, or community you agree to abide by its terms. ## License @@ -156,7 +156,7 @@ abide by its terms. [collective]: https://opencollective.com/unified -[chat-badge]: https://img.shields.io/badge/join%20the%20community-on%20spectrum-7b16ff.svg +[chat-badge]: https://img.shields.io/badge/chat-spectrum-7b16ff.svg [chat]: https://spectrum.chat/unified/rehype diff --git a/packages/rehype-parse/readme.md b/packages/rehype-parse/readme.md index e47561c4..de7dbfc3 100644 --- a/packages/rehype-parse/readme.md +++ b/packages/rehype-parse/readme.md @@ -65,7 +65,7 @@ npm install rehype-parse This example shows how we can parse HTML with this module and configure it to emit parse errors except for duplicate attributes. Then we transform HTML to Markdown with [`rehype-remark`][rehype-remark] and -finally compile that Markdown with [`remark-stringify`][remark-stringify]. +finally serialize that Markdown with [`remark-stringify`][remark-stringify]. Say we have the following file, `example.html`, with a few errors: @@ -268,8 +268,8 @@ Ideas for new plugins and tools can be posted in [`rehypejs/ideas`][ideas]. A curated list of awesome rehype resources can be found in [**awesome rehype**][awesome]. -This project has a [Code of Conduct][coc]. -By interacting with this repository, organisation, or community you agree to +This project has a [code of conduct][coc]. +By interacting with this repository, organization, or community you agree to abide by its terms. ## License @@ -300,7 +300,7 @@ abide by its terms. [collective]: https://opencollective.com/unified -[chat-badge]: https://img.shields.io/badge/join%20the%20community-on%20spectrum-7b16ff.svg +[chat-badge]: https://img.shields.io/badge/chat-spectrum-7b16ff.svg [chat]: https://spectrum.chat/unified/rehype diff --git a/packages/rehype-stringify/readme.md b/packages/rehype-stringify/readme.md index 9db4b91c..a648d390 100644 --- a/packages/rehype-stringify/readme.md +++ b/packages/rehype-stringify/readme.md @@ -8,7 +8,7 @@ [![Backers][backers-badge]][collective] [![Chat][chat-badge]][chat] -[**rehype**][rehype] plugin to stringify HTML. +[**rehype**][rehype] plugin to serialize HTML. [Compiler][] for [**unified**][unified]. Stringifies [**hast**][hast] syntax trees to HTML. Used in the [**rehype** processor][processor] but can be used on its own as @@ -84,7 +84,7 @@ process.stdin.pipe(createStream(processor)).pipe(process.stdout) ### `processor.use(stringify[, options])` -Configure `processor` to stringify [**hast**][hast] syntax trees to HTML. +Configure `processor` to serialize [**hast**][hast] syntax trees to HTML. ###### `options` @@ -108,8 +108,8 @@ Ideas for new plugins and tools can be posted in [`rehypejs/ideas`][ideas]. A curated list of awesome rehype resources can be found in [**awesome rehype**][awesome]. -This project has a [Code of Conduct][coc]. -By interacting with this repository, organisation, or community you agree to +This project has a [code of conduct][coc]. +By interacting with this repository, organization, or community you agree to abide by its terms. ## License @@ -140,7 +140,7 @@ abide by its terms. [collective]: https://opencollective.com/unified -[chat-badge]: https://img.shields.io/badge/join%20the%20community-on%20spectrum-7b16ff.svg +[chat-badge]: https://img.shields.io/badge/chat-spectrum-7b16ff.svg [chat]: https://spectrum.chat/unified/rehype diff --git a/packages/rehype/readme.md b/packages/rehype/readme.md index a49df949..51850865 100644 --- a/packages/rehype/readme.md +++ b/packages/rehype/readme.md @@ -8,7 +8,7 @@ [![Backers][backers-badge]][collective] [![Chat][chat-badge]][chat] -[**unified**][unified] processor to parse and compile HTML. +[**unified**][unified] processor to parse and serialize HTML. Powered by [plugins][]. Part of the [unified][] [collective][]. @@ -16,11 +16,11 @@ Part of the [unified][] [collective][]. * Parses HTML to the tree with [`rehype-parse`][parse] * [**hast**][hast] syntax tree * [Plugins][] transform the tree -* Compiles the tree to HTML with [`rehype-stringify`][stringify] +* Serializes the tree to HTML with [`rehype-stringify`][stringify] Don’t need the parser? Or the compiler? -[That’s OK][unified-usage]. +[That’s OK][unified-use]. If you’re in a browser, trust the content, and value a smaller bundle size, use [`rehype-dom`][rehype-dom] instead. @@ -106,8 +106,8 @@ Ideas for new plugins and tools can be posted in [`rehypejs/ideas`][ideas]. A curated list of awesome rehype resources can be found in [**awesome rehype**][awesome]. -This project has a [Code of Conduct][coc]. -By interacting with this repository, organisation, or community you agree to +This project has a [code of conduct][coc]. +By interacting with this repository, organization, or community you agree to abide by its terms. ## License @@ -138,7 +138,7 @@ abide by its terms. [collective]: https://opencollective.com/unified -[chat-badge]: https://img.shields.io/badge/join%20the%20community-on%20spectrum-7b16ff.svg +[chat-badge]: https://img.shields.io/badge/chat-spectrum-7b16ff.svg [chat]: https://spectrum.chat/unified/rehype @@ -172,7 +172,7 @@ abide by its terms. [plugins]: https://github.com/rehypejs/rehype/blob/master/doc/plugins.md -[unified-usage]: https://github.com/unifiedjs/unified#usage +[unified-use]: https://github.com/unifiedjs/unified#use [announcement]: https://medium.com/unifiedjs/collectively-evolving-through-crowdsourcing-22c359ea95cc diff --git a/readme.md b/readme.md index 8f9f8c09..6c16534c 100644 --- a/readme.md +++ b/readme.md @@ -26,7 +26,7 @@ into a document][document]. This repository contains the following projects: * [`rehype-parse`][parse] — Parse HTML documents to syntax trees -* [`rehype-stringify`][stringify] — Stringify syntax trees to HTML documents +* [`rehype-stringify`][stringify] — Serialize syntax trees to HTML documents * [`rehype`][api] — Programmatic interface with both `rehype-parse` and `rehype-stringify` * [`rehype-cli`][cli] — Command-line interface wrapping `rehype` @@ -81,8 +81,8 @@ Ideas for new plugins and tools can be posted in [`rehypejs/ideas`][ideas]. A curated list of awesome rehype resources can be found in [**awesome rehype**][awesome]. -This project has a [Code of Conduct][coc]. -By interacting with this repository, organisation, or community you agree to +This project has a [code of conduct][coc]. +By interacting with this repository, organization, or community you agree to abide by its terms. ## License @@ -115,7 +115,7 @@ abide by its terms. [collective]: https://opencollective.com/unified -[chat-badge]: https://img.shields.io/badge/join%20the%20community-on%20spectrum-7b16ff.svg +[chat-badge]: https://img.shields.io/badge/chat-spectrum-7b16ff.svg [chat]: https://spectrum.chat/unified/rehype