Refactor readme.md

Author: wooorm

package.json

@@ -37,13 +37,15 @@
   "devDependencies": {
     "nyc": "^12.0.2",
     "prettier": "^1.14.2",
+    "remark-cli": "^5.0.0",
+    "remark-preset-wooorm": "^4.0.0",
     "tape": "^4.4.0",
     "unist-builder": "^1.0.1",
     "unist-util-select": "^1.5.0",
     "xo": "^0.22.0"
   },
   "scripts": {
-    "format": "prettier --write \"**/*.js\" && xo --fix",
+    "format": "remark . -qfo && prettier --write \"**/*.js\" && xo --fix",
     "test-api": "node test",
     "test-coverage": "nyc --reporter lcov tape test.js",
     "test": "npm run format && npm run test-coverage"
@@ -65,5 +67,10 @@
   "xo": {
     "prettier": true,
     "esnext": false
+  },
+  "remarkConfig": {
+    "plugins": [
+      "preset-wooorm"
+    ]
   }
 }

readme.md

@@ -1,106 +1,110 @@
-[![npm](https://nodei.co/npm/unist-util-index.png)](https://npmjs.com/package/unist-util-index)
+# unist-util-index [![Build Status][travis-badge]][travis] [![Coverage Status][codecov-badge]][codecov]
 
-# unist-util-index
+Create mutable index mapping property values or computed keys back to
+[**unist**][unist] nodes.
 
-[![Build Status][travis-badge]][travis] [![Dependency Status][david-badge]][david]
+## Installation
 
-Create mutable index mapping property values or computed keys back to [Unist] nodes.
+[npm][]:
 
-[unist]: https://github.com/wooorm/unist
+```bash
+npm install unist-util-index
+```
 
-[travis]: https://travis-ci.org/eush77/unist-util-index
-[travis-badge]: https://travis-ci.org/eush77/unist-util-index.svg?branch=master
-[david]: https://david-dm.org/eush77/unist-util-index
-[david-badge]: https://david-dm.org/eush77/unist-util-index.png
+## Usage
 
-## Example
+## API
 
-Headings by depth:
+### `Index([tree[, filter]], prop|keyFn)`
 
-```js
-var Index = require('unist-util-index'),
-    fs = require('fs'),
-    remark = require('remark'),
-    toString = require('mdast-util-to-string');
+Create an index data structure that maps keys (calculated by `keyFn` function
+or the values at `prop` in each node) to a list of nodes.
 
-var ast = remark.parse(fs.readFileSync('README.md', 'utf8'));
-var index = Index(ast, 'heading', 'depth');
+If `tree` is given, the index is initialised with all nodes, optionally
+filtered by `filter`.
 
-index.get(1).map(toString)
-//=> [ 'unist-util-index' ]
+###### Signatures
 
-index.get(2).map(toString)
-//=> [ 'Example', 'API', 'Install', 'License' ]
-```
+*   `Index(prop|keyFn)`
+*   `Index(tree, prop|keyFn)`
+*   `Index(tree, filter, prop|keyFn)`
 
-Definitions by identifier:
+###### Parameters
 
-```js
-var index = Index(ast, 'definition', 'identifier');
+*   `tree` ([`Node`][node])
+*   `filter` (`*`) — [`is`][is]-compatible test
+*   `prop` (`string`) — Property to look up in each node to find keys
+*   `keyFn` ([`Function`][keyfn]) — Function called with each node to calculate
+    keys
 
-index.get('unist')
-//=> [ { type: 'definition',
-//       identifier: 'unist',
-//       title: null,
-//       url: 'https://github.com/wooorm/unist',
-//       position: Position { start: [Object], end: [Object], indent: [] } } ]
+###### Returns
 
-index.get('travis')
-//=> [ { type: 'definition',
-//       identifier: 'travis',
-//       title: null,
-//       url: 'https://travis-ci.org/eush77/unist-util-index',
-//       position: Position { start: [Object], end: [Object], indent: [] } } ]
-```
+`Index` — an index instance.
 
-## API
+#### `function keyFn(node)`
 
-### `index = Index([ast, [filter]], key)`
+Function called with every added [node][] to return the value to index on.
 
-- `ast` — [Unist] tree.
+#### `Index#get(key)`
 
-- `filter` — one of:
-  - node type (string);
-  - function invoked with arguments `(node, index?, parent?)`.
+Get nodes by `key` (`*`).
+Returns a list of zero or more nodes ([`Array.<Node>`][node]).
 
-- `key` — one of:
-  - property name (string);
-  - function invoked with argument `(node)`.
+#### `Index#add(node)`
 
-Create index data structure that maps keys (returned by `key` function or property) to nodes.
+Add [`node`][node] to the index (if not already present).
 
-If `ast` argument is given, initialize index with `ast` nodes (recursively), optionally filter by node type or predicate.
+#### `Index#remove(node)`
 
-### `index.get(key)`
+Remove [`node`][node] from the index (if present).
 
-- `key` — index key.
+## Related
 
-Get nodes by `key`.
+*   [`unist-util-is`](https://github.com/syntax-tree/unist-util-is)
+    — Utility to check if a node passes a test
+*   [`unist-util-visit`](https://github.com/syntax-tree/unist-util-visit)
+    — Utility to recursively walk over nodes
+*   [`unist-util-map`](https://github.com/syntax-tree/unist-util-map)
+    — Create a new tree by mapping by the provided function
+*   [`unist-util-flatmap`](https://gitlab.com/staltz/unist-util-flatmap)
+    — Create a new tree by mapping and then flattening
+*   [`unist-util-select`](https://github.com/syntax-tree/unist-util-select)
+    — Select nodes with CSS-like selectors
 
-Returns array of nodes.
+## Contribute
 
-### `index.add(node)`
+See [`contributing.md` in `syntax-tree/unist`][contributing] for ways to get
+started.
 
-- `node` — [Unist] node.
+This organisation has a [Code of Conduct][coc].  By interacting with this
+repository, organisation, or community you agree to abide by its terms.
 
-Add `node` to index. No-op if `node` is already present in index.
+## License
 
-Returns `index`.
+[MIT][license] © Eugene Sharygin
 
-### `index.remove(node)`
+<!-- Definitions -->
 
-- `node` — [Unist] node.
+[travis-badge]: https://img.shields.io/travis/syntax-tree/unist-util-index.svg
 
-Remove `node` from index. No-op if `node` is not present in index.
+[travis]: https://travis-ci.org/syntax-tree/unist-util-index
 
-Returns `index`.
+[codecov-badge]: https://img.shields.io/codecov/c/github/syntax-tree/unist-util-index.svg
 
-## Install
+[codecov]: https://codecov.io/github/syntax-tree/unist-util-indexs
 
-```
-npm install unist-util-index
-```
+[npm]: https://docs.npmjs.com/cli/install
 
-## License
+[license]: license
+
+[contributing]: https://github.com/syntax-tree/unist/blob/master/contributing.md
+
+[coc]: https://github.com/syntax-tree/unist/blob/master/code-of-conduct.md
+
+[unist]: https://github.com/syntax-tree/unist
+
+[node]: https://github.com/syntax-tree/unist#node
+
+[is]: https://github.com/syntax-tree/unist-util-is
 
-MIT
+[keyfn]: #function-keyfnnode