Add example section to readme.

Author: tmpfs

README.md

@@ -22,6 +22,7 @@ For the command line interface install [mkdoc][] globally (`npm i -g mkdoc`).
 
 - [Install](#install)
 - [Usage](#usage)
+- [Example](#example)
 - [Help](#help)
 - [API](#api)
   - [abs](#abs)
@@ -43,6 +44,20 @@ ast.src('[readme](/README.md)')
   .pipe(process.stdout);
 ```
 
+## Example
+
+Make links absolute using data in `package.json`:
+
+```shell
+mkcat README.md | mkabs | mkout
+```
+
+Make links absolute using an specific URL:
+
+```shell
+mkcat README.md | mkabs -b http://example.com | mkout
+```
+
 ## Help
 
 ```

doc/readme.md

@@ -14,13 +14,7 @@ The typical use case is for README documents whose forward slash links work as e
 <!-- @toc -->
 ***
 
-## Usage
-
-Create the stream and write a [commonmark][] document:
-
-<? @source {javascript=s/\.\.\/index/mkabs/gm} usage.js ?>
-
-<? @include {=readme} help.md ?>
+<? @include {=readme} usage.md example.md help.md ?>
 
 <? @exec mkapi index.js absolute.js --title=API --level=2 ?>
 <? @include {=readme} license.md links.md ?>

doc/readme/usage.md

@@ -0,0 +1,6 @@
+## Usage
+
+Create the stream and write a [commonmark][] document:
+
+<? @source {javascript=s/\.\.\/index/mkabs/gm} ../usage.js ?>
+