From 1cf8fd043d822564d225d405174ee10c3351854a Mon Sep 17 00:00:00 2001 From: Nico Hagenburger Date: Tue, 21 Aug 2018 22:41:56 +0200 Subject: [PATCH] Add basic documentation fixes #12 --- README.md | 150 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 150 insertions(+) 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 +
+
+ 
+      
+        <p>Test</p>
+      
+
+
+
Hello world!
+
+``` + ---