PIMD

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

Easy to use in JavaScript projects – in build tools and within the browser
Focus on extendibility: The DOM tree known from the browser will be the main API
Compliance with the CommonMark specs – Markdown files will render perfectly on GitHub; all additional commands will be CommanMark compliant and won’t leave ugly artifacts when used in README.md files on GitHub

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

Documentation

It’s part of the RailsGirls Summer of Code to extend this Readme file. 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

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

Extending

Output generated data with JavaScript

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

const { Document } = require("pimd")
const Config = require("pimd/lib/config")
const markdown = "# Year <?year?>"

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

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 markdown = "# Headline <?important?>"

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

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 markdown = `
~~~ html info="Hello world!"
<p>Test</p>
~~~
`

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:

<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>

Coding style

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

dianavile/pimd

PIMD

Main targets

RailsGirls Summer of Code

Documentation

Setup

Usage

Render inline

Render document

Plugins

Extending

Output generated data with JavaScript

Accessing the DOM

Writing plugins

Coding style

Copyright