diff --git a/README.md b/README.md
index 3c5c9eb..cf327fe 100644
--- a/README.md
+++ b/README.md
@@ -30,6 +30,156 @@ This project is as part of [LivingStyleGuide] chosen for the [RailsGirls Summer
It’s part of the RailsGirls Summer of Code to [extend this Readme file](https://github.com/hagenburger/pimd/issues/12). This will be done when PIMD officially gets released. For now: **All functionality is documented in the tests** which you can find in the `tests` folder and `test.js` of each plugin found in `plugins/*`.
+---
+
+
+## Setup
+
+``` bash
+npm install --save pimd
+```
+
+## Usage
+
+### Render inline
+
+``` javascript
+const {Document} = require('pimd')
+const markdown = '# Headline'
+const doc = new Document(markdown)
+console.log(doc.render())
+```
+
+Result:
+
+``` html
+Headline
+```
+
+### Render document
+
+``` javascript
+const {Document} = require('pimd')
+const markdown = '# Headline'
+const doc = new Document(markdown)
+doc.renderDocument().then((html) => {
+ console.log(html)
+})
+```
+
+Result:
+
+``` html
+
+
+ Headline
+
+
+ Headline
+
+
+```
+
+
+## Plugins
+
+- [Add classes to code blocks or other elements](https://github.com/hagenburger/pimd/tree/master/plugins/classes#readme)
+- [Add an ID to code blocks or other elements](https://github.com/hagenburger/pimd/tree/master/plugins/ids#readme)
+- [Add an HTML preview to code blocks](https://github.com/hagenburger/pimd/tree/master/plugins/preview#readme)
+
+
+## Extending
+
+### Output generated data with JavaScript
+
+PIMD extends Markdown with Processing Instructions known from XML. This is complient with the [CommonMark specs].
+
+``` javascript
+const {Document} = require('pimd')
+const Config = require('pimd/lib/config')
+const markdown = '# Year '
+
+const config = new Config()
+config.commands['year'] = () => new Date().getFullYear()
+
+const doc = new Document(markdown, config)
+console.log(doc.render())
+```
+
+Result:
+
+``` html
+Year 2018
+```
+
+
+### Accessing the DOM
+
+PIMD uses the [DOM] internally to provide a well-known API to its users.
+
+``` javascript
+const {Document} = require('pimd')
+const Config = require('pimd/lib/config')
+const markdown = '# Headline '
+
+const config = new Config()
+config.commands['date'] = (context) => { context.element.style.background = 'yellow' }
+
+const doc = new Document(markdown, config)
+console.log(doc.render())
+```
+
+Result:
+
+``` html
+Headline
+```
+
+[DOM]: https://developer.mozilla.org/en-US/docs/Glossary/DOM
+
+
+### Writing plugins
+
+``` javascript
+const {Document} = require('pimd')
+const Config = require('pimd/lib/config')
+
+const markdown = `
+~~~ html info="Hello world!"
+Test
+~~~
+`
+
+const myPlugin = function (config) {
+ config.addInfoStringParser(/info="(.+?)"/, function (match, string) {
+ const element = this.renderer.dom.window.document.createElement('div')
+ element.textContent = string
+ this.element.appendChild(element)
+ })
+}
+
+const config = new Config()
+config.use(myPlugin)
+
+const doc = new Document(markdown, config)
+console.log(doc.render())
+```
+
+Result:
+
+``` html
+
+```
+
---