https://github.com/hagenburger/pimd
PIMD – Processing Instructions for Markdown
https://github.com/hagenburger/pimd
design-systems documentation javascript livingstyleguide markdown
Last synced: 2 months ago
JSON representation
PIMD – Processing Instructions for Markdown
- Host: GitHub
- URL: https://github.com/hagenburger/pimd
- Owner: hagenburger
- License: mit
- Created: 2018-05-14T05:55:20.000Z (about 7 years ago)
- Default Branch: master
- Last Pushed: 2022-12-30T17:14:51.000Z (over 2 years ago)
- Last Synced: 2025-04-01T12:54:59.879Z (2 months ago)
- Topics: design-systems, documentation, javascript, livingstyleguide, markdown
- Language: JavaScript
- Homepage: https://hagenburger.github.io/pimd-docs/
- Size: 2.42 MB
- Stars: 20
- Watchers: 3
- Forks: 5
- Open Issues: 65
-
Metadata Files:
- Readme: README.md
- License: MIT-LICENSE
Awesome Lists containing this project
README
# PIMD
[](https://prettier.io)
**P**rocessing **I**nstructions for **M**ark**D**own.
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
[livingstyleguide]: https://github.com/livingstyleguide/livingstyleguide
[dom]: https://developer.mozilla.org/en-US/docs/Web/API/Document_Object_Model
[commonmark specs]: https://commonmark.org
#### 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
[railsgirls summer of code 2018]: https://railsgirlssummerofcode.org
---
## Setup
```sh
npm install --save pimd
```
## Usage
### Render inline
```javascript +highlight=/#/,/Headline/
const { Document } = require("pimd")
const markdown = `
# Headline
`
const doc = new Document(markdown)
console.log(doc.render())
```
Result:
```html +highlight=/<\/?h1>/g,/Headline/
Headline
```
### Render document
```javascript +highlight=/#/,/Headline/
const { Document } = require("pimd")
const markdown = `
# Headline
`
const doc = new Document(markdown)
doc.renderDocument().then(html => {
console.log(html)
})
```
Result:
```html +highlight=/<\/?h1>/g,/Headline/
Headline
Headline
```
## 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.
- [Classes](https://github.com/hagenburger/pimd/tree/master/plugins/classes#readme):
Add classes to code blocks or other elements for easy additional styling
- [ID](https://github.com/hagenburger/pimd/tree/master/plugins/id#readme): Add
an ID to code blocks or other elements for easily accessing elements in the
HTML preview via JavaScript to bring code examples to live
- [Preview](https://github.com/hagenburger/pimd/tree/master/plugins/preview#readme):
Add an HTML preview to code blocks for pattern libraries/living style guides
- [Highlight](https://github.com/hagenburger/pimd/tree/master/plugins/highlight#readme):
Visually highlight important parts of code blocks in different background
colors
- [Showmore](https://github.com/hagenburger/pimd/tree/master/plugins/showmore#readme):
Hide less important parts of code blocks
- [Prism](https://github.com/hagenburger/pimd/tree/master/plugins/prism#readme):
Syntax highlighting with PrismJS
- [HTML injector](https://github.com/hagenburger/pimd/tree/master/plugins/html-injector#readme):
a plugin to create new plugins that manipulate the code blocks (already used
by Highlight and Showmore)
## Extending
### Output generated data with JavaScript
PIMD extends Markdown with Processing Instructions known from XML. This is
compliant with the [CommonMark specs].
```javascript +highlight=/year/g,/new Date\(\).getFullYear\(\)/
const { Document } = require("pimd")
const Config = require("pimd/lib/config")
const config = new Config()
config.commands["year"] = () => new Date().getFullYear()
const markdown = `
# Year
`
const doc = new Document(markdown, config)
console.log(doc.render())
```
Result:
```html +highlight="_",/2018/
Year 2018
```
### Accessing the DOM
PIMD uses the [DOM] internally to provide a well-known API to its users.
```javascript +highlight=/important/g,/background = "yellow"/,/style/,/element/g
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
`
const doc = new Document(markdown, config)
console.log(doc.render())
```
Result:
```html +highlight="_",/background: yellow/,/style/,/
|>/g
Headline
```
[dom]: https://developer.mozilla.org/en-US/docs/Glossary/DOM
### Writing plugins
```javascript +highlight=/info/g,/"Hello world!"|(?Test
~~~
`
const doc = new Document(markdown, config)
console.log(doc.render())
```
Result:
```html +highlight="_",/Hello world!/g,/
.+?<\/div>/g,/|^<\/div>/g
<p>Test</p>
Hello world!
```
Tip: Check out the source code of [PIMD’s official plugins](#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](https://www.hagenburger.net). See
[MIT-LICENSE](MIT-LICENSE) for details. Get in touch with
[@hagenburger](https://twitter.com/hagenburger) on Twitter or
[open an issue](https://github.com/hagenburger/pimd/issues/new).
[prettier]: https://prettier.io