Refactor prose

rehypejs · Mar 22, 2020 · 98910d4 · 98910d4
1 parent e7d42b1
commit 98910d4
Show file tree

Hide file tree

Showing 8 changed files with 62 additions and 50 deletions.
diff --git 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,21 +31,21 @@ 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.
 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
 <!doctype html>
 <html>
   <head>
@@ -60,20 +60,23 @@ npm install --global rehype-cli rehype-preset-minify
 
 `rehype index.html --use preset-minify` yields:
 
-```txt
+```html
 <!doctypehtml><meta charset=utf8><title>Hello</title><p>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:
 [`rehype-parse`][parse] and [`rehype-stringify`][stringify].
 
 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('<title>Hi</title><h2>Hello world!', function(err, file) {
-  console.log(report(err || file))
   console.log(String(file))
+  console.log(report(err || file))
 })
 ```
 
 `node index.js` yields:
 
+```html
+<html><head><title>Hi</title></head><body><h2>Hello world!</h2></body></html>
+```
+
 ```txt
 no issues found
-<html><head><title>Hi</title></head><body><h2>Hello world!</h2></body></html>
 ```
 
 <!-- Definitions -->

diff --git 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,15 +90,15 @@ 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.
 
 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -8,19 +8,19 @@
 [![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][].
 
 *   API by [**unified**][unified]
 *   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
@@ -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