From c3f197c79d4be963baa67c7f998b7905d3388d7e Mon Sep 17 00:00:00 2001
From: ismay <ismay@users.noreply.github.com>
Date: Sat, 28 Jul 2018 13:04:46 +0200
Subject: [PATCH] Improve readme (#155)

* Move example to wiki

* Add installation instructions

* Add wiki link

* Collapse paragraph
---
 README.md | 86 +++++--------------------------------------------------
 1 file changed, 7 insertions(+), 79 deletions(-)

diff --git a/README.md b/README.md
index 359b0c6..8551f38 100644
--- a/README.md
+++ b/README.md
@@ -4,12 +4,11 @@
 [![coverage status][coverage-badge]][coverage-url]
 [![greenkeeper][greenkeeper-badge]][greenkeeper-url]
 
-> A metalsmith plugin for rendering templates to html
+> A metalsmith plugin for transforming your source files
 
-This plugin allows you to render various templating languages to html. It uses file extensions to
-infer which templating engine to use. So files ending in `.njk` will be processed as nunjucks, `.pug` as pug, etc. You can even chain transformations by appending multiple extensions, which will be processed right-to-left.
+This plugin allows you to transform the contents of your source files. It uses file extensions to infer which transform to use. So files ending in `.njk` will be processed as nunjucks, `.md` as markdown, etc. You can even chain transformations by appending multiple extensions, which will be processed right-to-left.
 
-For support questions please use [stack overflow][stackoverflow-url] or our [slack channel][slack-url]. For templating engine specific questions try the aforementioned channels, as well as the documentation for [jstransformers](https://github.com/jstransformers) and your templating engine of choice.
+For usage examples check out our [wiki](https://github.com/metalsmith/metalsmith-in-place/wiki). Feel free to contribute an example if anything is missing, or update the existing ones. For support questions please use [stack overflow][stackoverflow-url] or our [slack channel][slack-url]. For templating engine specific questions try the aforementioned channels, as well as the documentation for [jstransformers](https://github.com/jstransformers) and your templating engine of choice.
 
 ## Installation
 
@@ -17,6 +16,10 @@ For support questions please use [stack overflow][stackoverflow-url] or our [sla
 $ npm install metalsmith-in-place
 ```
 
+This plugin uses [jstransformers](https://github.com/jstransformers/jstransformer) to transform files. Since there are a lot of jstransformers we don't install them automatically, so you'll also need to install the appropriate jstransformers.
+
+For example, to render markdown you would install [jstransformer-markdown](https://github.com/jstransformers/jstransformer-markdown). To render handlebars you would install [jstransformer-handlebars](https://github.com/jstransformers/jstransformer-handlebars). See the [jstransformer organisation](https://github.com/jstransformers) for all available jstransformers and [this dictionary](https://github.com/jstransformers/inputformat-to-jstransformer/blob/master/dictionary.json) to see which extensions map to which jstransformer.
+
 ## Options
 
 You can pass options to `metalsmith-in-place` with the [Javascript API](https://github.com/segmentio/metalsmith#api) or [CLI](https://github.com/segmentio/metalsmith#cli). The options are:
@@ -72,81 +75,6 @@ Would pass `{ "cache": false }` to each used jstransformer.
 
 Note that if you have [debugging](#errors-and-debugging) turned on, you’ll see a message denoting that no files are present for processing.
 
-## Example
-
-You can use `metalsmith-in-place` with metalsmith's
-[Javascript API](https://github.com/segmentio/metalsmith#api) or the
-[CLI](https://github.com/segmentio/metalsmith#cli). For this example we'll use the cli:
-
-### 1. Install metalsmith and metalsmith-in-place:
-
-```bash
-$ npm install --save metalsmith metalsmith-in-place
-```
-
-### 2. Install appropriate jstransformers
-
-Under the hood this plugin uses [jstransformers](https://github.com/jstransformers/jstransformer)
-to render your html. Since there are over a 100 jstransformers we don't install them automatically,
-so you'll also need to install the appropriate jstransformers. 
-
-For example, to render markdown you would install [jstransformer-markdown](https://github.com/jstransformers/jstransformer-markdown). To render
-handlebars you would install
-[jstransformer-handlebars](https://github.com/jstransformers/jstransformer-handlebars). See the
-[jstransformer organisation](https://github.com/jstransformers) for all available jstransformers and
-[this dictionary](https://github.com/jstransformers/inputformat-to-jstransformer/blob/master/dictionary.json)
-to see which extensions map to which jstransformer.
-  
-In this case we'll use nunjucks, so we'll install `jstransformer-nunjucks`:
-
-```bash
-$ npm install --save jstransformer-nunjucks
-```
-
-### 3. Configure metalsmith
-
-We'll create a metalsmith.json configuration file and a handlebars file for metalsmith-in-place to
-process:
-
-`./metalsmith.json`
-
-```json
-{
-  "source": "src",
-  "destination": "build",
-  "plugins": {
-    "metalsmith-in-place": true
-  }
-}
-```
-
-`./src/index.njk`
-
-```nunjucks
----
-title: This is a variable, defined in the file's frontmatter
----
-<h1>{{ title }}</h1>
-<p>Some text here.</p>
-```
-
-### 4. Build
-
-To build just run the metalsmith CLI:
-
-```bash
-$ node_modules/.bin/metalsmith
-```
-
-Which will output the following file:
-
-`./build/index.html`
-
-```html
-<h1>This is a variable, defined in the file's frontmatter</h1>
-<p>Some text here.</p>
-```
-
 ## Errors and debugging
 
 If you're encountering problems you can use [debug](https://www.npmjs.com/package/debug) to enable verbose logging. To enable `debug` prefix your build command with `DEBUG=metalsmith-in-place`. So if you normally run `metalsmith` to build, use `DEBUG=metalsmith-in-place metalsmith` (on windows the syntax is [slightly different](https://www.npmjs.com/package/debug#windows-note)).