hagenburger / pimd

PIMD – Processing Instructions for Markdown
https://hagenburger.github.io/pimd-docs/
MIT License
20 stars 5 forks source link
design-systems documentation javascript livingstyleguide markdown

PIMD

Build status (Travis CI) Dependency status (Greenkeeper) JavaScript Style Guide

Processing Instructions for MarkDown.

PIMD will be the base for the JavaScript version of LivingStyleGuide – an API to extend Markdown by DOM manipulations as known from the browsers.

Main targets

RailsGirls Summer of Code

This project is as part of LivingStyleGuide chosen for the [RailsGirls Summer of Code 2018]: Our team is @artnerdnet and @dianavile


Setup

npm install --save pimd

Usage

Render inline

const { Document } = require("pimd")
const markdown = `
# Headline
`
const doc = new Document(markdown)
console.log(doc.render())

Result:

<h1>
  Headline
</h1>

Render document

const { Document } = require("pimd")
const markdown = `
# Headline
`
const doc = new Document(markdown)
doc.renderDocument().then(html => {
  console.log(html)
})

Result:

<html>
  <head>
    <title>Headline</title>
  </head>
  <body>
    <h1>
      Headline
    </h1>
  </body>
</html>

Plugins

Plugins unleash the full power of PIMD. The official plugins offer functionality to create living style guides and to improve code documentation in general.

Extending

Output generated data with JavaScript

PIMD extends Markdown with Processing Instructions known from XML. This is compliant with the CommonMark specs.

const { Document } = require("pimd")
const Config = require("pimd/lib/config")

const config = new Config()
config.commands["year"] = () => new Date().getFullYear()

const markdown = `
# Year <?year?>
`
const doc = new Document(markdown, config)
console.log(doc.render())

Result:

<h1>Year 2018</h1>

Accessing the DOM

PIMD uses the DOM internally to provide a well-known API to its users.

const { Document } = require("pimd")
const Config = require("pimd/lib/config")

const config = new Config()
config.commands["important"] = context => {
  context.element.style.background = "yellow"
}

const markdown = `
# Headline <?important?>
`
const doc = new Document(markdown, config)
console.log(doc.render())

Result:

<h1 style="background: yellow">Headline</h1>

Writing plugins

const { Document } = require("pimd")
const Config = require("pimd/lib/config")

const myPlugin = function(config) {
  config.addInfoStringCommand("info", { types: ["string"] }, function(text) {
    const div = this.renderer.dom.window.document.createElement("div")
    div.textContent = text
    this.element.appendChild(div)
  })
}

const config = new Config()
config.use(myPlugin)

const markdown = `
~~~html +info="Hello world!"
<p>Test</p>
~~~
`
const doc = new Document(markdown, config)
console.log(doc.render())

Result:

<div class="pimd-example">
  <div class="pimd-code">
    <pre>
      <code class="lang-html">
        &lt;p&gt;Test&lt;/p&gt;
      </code>
    </pre>
  </div>
  <div>Hello world!</div>
</div>

Tip: Check out the source code of PIMD’s official plugins for further inspiration.


Coding style

PIMD uses the Prettier style for all supported documents. To save the environment, semicolons are not required.


Copyright

Copyright 2018++ Nico Hagenburger. See MIT-LICENSE for details. Get in touch with @hagenburger on Twitter or open an issue.