Refactor prose

readme.md

@@ -3,25 +3,26 @@
 [![Build][build-badge]][build]
 [![Coverage][coverage-badge]][coverage]
 [![Downloads][downloads-badge]][downloads]
-[![Chat][chat-badge]][chat]
+[![Size][size-badge]][size]
 [![Sponsors][sponsors-badge]][collective]
 [![Backers][backers-badge]][collective]
+[![Chat][chat-badge]][chat]
 
-heading-gap support, without needing spaces, for [**remark**][remark].
+[**remark**][remark] plugin to adjust the gap between headings.
 
 
-## Installation
+## Install
 
 [npm][]:
 
-```bash
+```sh
 npm install remark-heading-gap
 ```
 
 
-## Example
+## Use
 
-Say we have a markdown file, `example.md`, that looks as follows:
+Say we have a Markdown file, `example.md`, that looks as follows:
 
 ```markdown
 # remark-heading-gap
@@ -37,7 +38,7 @@ Say we have a markdown file, `example.md`, that looks as follows:
 
 And our script, `example.js`, contains:
 
-```javascript
+```js
 const fs = require('fs')
 const remark = require('remark')
 const gap = require('remark-heading-gap')
@@ -70,30 +71,33 @@ Now, running `node example` yields:
 
 ## API
 
-### `remark.use(headingGap[, options])`
+### `remark().use(headingGap[, options])`
 
-remark-heading-gap ensures that automatically generated Markdown follows your
-own rules for newlines in between section headings.
+Adjust the gap between headings.
+Ensures that automatically generated Markdown follows your own rules for blank
+lines between section headings.
 From personal experience, adding extra newlines helps to visualise breaks in
 sections, especially when quickly scanning documentation.
 
 #### `options.{1, 2, 3, 4, 5, 6}`
 
 Pass a gap (Object, default: `{before: '\n', after: ''}` for `options.2`,
 `{before: '', after: ''}` for all others)
-Customise the gap that appears for up to 6 levels of heading; for example,
-pass `{1: {before: '\n', after: '\n'}}` to double the gap for the first heading.
+Customise the gap that appears for up to 6 levels of heading; for example, pass
+`{1: {before: '\n', after: '\n'}}` to double the gap for the first heading.
 Note that both `before` and `after` accept a custom string so you can specify
 `\r\n` instead if you choose; or add other presentational markers.
 
 
 ## Contribute
 
-See [`contributing.md` in `remarkjs/remark`][contributing] for ways to get
-started.
+See [`contributing.md`][contributing] in [`remarkjs/.github`][health] for ways
+to get started.
+See [`support.md`][support] for ways to get help.
 
-This organisation has a [Code of Conduct][coc].  By interacting with this
-repository, organisation, or community you agree to abide by its terms.
+This project has a [Code of Conduct][coc].
+By interacting with this repository, organisation, or community you agree to
+abide by its terms.
 
 
 ## License
@@ -102,7 +106,7 @@ repository, organisation, or community you agree to abide by its terms.
 
 <!-- Definitions -->
 
-[build-badge]: https://img.shields.io/travis/remarkjs/remark-heading-gap.svg
+[build-badge]: https://img.shields.io/travis/remarkjs/remark-heading-gap/master.svg
 
 [build]: https://travis-ci.org/remarkjs/remark-heading-gap
 
@@ -114,24 +118,32 @@ repository, organisation, or community you agree to abide by its terms.
 
 [downloads]: https://www.npmjs.com/package/remark-heading-gap
 
-[chat-badge]: https://img.shields.io/badge/join%20the%20community-on%20spectrum-7b16ff.svg
+[size-badge]: https://img.shields.io/bundlephobia/minzip/remark-heading-gap.svg
 
-[chat]: https://spectrum.chat/unified/remark
+[size]: https://bundlephobia.com/result?p=remark-heading-gap
 
 [sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg
 
 [backers-badge]: https://opencollective.com/unified/backers/badge.svg
 
 [collective]: https://opencollective.com/unified
 
-[license]: license
+[chat-badge]: https://img.shields.io/badge/join%20the%20community-on%20spectrum-7b16ff.svg
 
-[author]: http://beneb.info
+[chat]: https://spectrum.chat/unified/remark
 
 [npm]: https://docs.npmjs.com/cli/install
 
-[remark]: /~https://github.com/remarkjs/remark
+[health]: /~https://github.com/remarkjs/.github
+
+[contributing]: /~https://github.com/remarkjs/.github/blob/master/contributing.md
 
-[contributing]: /~https://github.com/remarkjs/remark/blob/master/contributing.md
+[support]: /~https://github.com/remarkjs/.github/blob/master/support.md
 
-[coc]: /~https://github.com/remarkjs/remark/blob/master/code-of-conduct.md
+[coc]: /~https://github.com/remarkjs/.github/blob/master/code-of-conduct.md
+
+[license]: license
+
+[author]: http://beneb.info
+
+[remark]: /~https://github.com/remarkjs/remark