@dimerapp/markdown

Dimer is an open source project and CMS to help you publish your documentation online.

_{We believe every project/product is incomplete without documentation.
We want to help you publish user facing documentation, without worrying about tools or code to write.}

Dimer markdown

The meat of Dimer

This repo has the code to convert Markdown to HTML or to JSON. It also adds support for custom syntax to extend the feature set of Markdown.

Dimer uses this inside it's CMS and the CLI to transform your Markdown files to JSON and then saves with the server.

Installation

npm i @dimerapp/markdown

# Yarn
yarn add @dimerapp/markdown

Usage

After installation, import the module and use it as follows.

const Markdown = require('@dimerapp/markdown')

const content = `
# Hello world

Some stuff goes here.
`

const md = new Markdown(content, options)

await md.toHTML()

// or toJSON
await md.toJSON()

Options

Here's the list of available options.

Key	Value	Description
title	String	A custom title for the document. This will be used, if there is no top-level `H1`
skipToc	Boolean	Do not generate the TOC
onUrl	Function	Invoked everytime a relative URL is detected inside the markdown links or images. You can return a custom URL, which will replace the existing one. Read more about assets detection.

Macros

Dimer extends the markdown using Macro's. All macros shares the same syntax structure (to keep it easier to consume) and new one's can be added to this library.

A macro can be an inline macro or a block level macro.

note (block)

The note macro creates a div with className=alert-note and can be used as follows.

[note]
This is a note
[/note]

Following are the alert style macros and creates a div like the note macro.

Macro	Div class
warn	alert-warning
tip	alert-tip

codepen (inline)

Adds a codepen embed to the document.

[codepen url="https://codepen.io/ge1doot/pen/vRJyVG", theme="light"]

youtube (inline)

Adds a youtube embed

[youtube url="", height="", width=""]

collapse (block)

[collapse title=""]
Inner content
[/collapse]

Output

<div class="collapse">
  <div class="collapsible-toggle"> TITLE </div>
  <div class="collapsible-content"> Inner content </div>
</div>

codegroup (block)

Creates a tabbed group of multiple codeblocks.

[codegroup]

```js
Tab one
```

```js
Tab two
```

[/codegroup]

include(inline)

Include other markdown files as partials.

[include path="./relative-path.md"]

Also, you can tell the include block to include the file inside codeblocks. This is helpful, when you want to lint the source file using some external linter and include it inside the markdown.

[include path="./relative-path.json", codeblock="true", language="json", lineHighlight="1-4,8-10", displayName="users.json"]

path is the relative path to the file to include.
codeblock with the value of true will wrap the content inside the codeblocks.
language (valid when codeblock=true) the source language to highlight the code.
lineHighlight (valid when codeblock=true) The lines to highlight inside the source block.
displayName (valid when codeblock=true) The name of the tab when include is inside a codegroup.

video (inline)

Embed a video using the source url. Do not, videos are not part of assets detection.

[video url="https://somevideo.mp4", autoplay, controls]

Adding new macro

You can also add your own macros as follows.

NOTE: Macros are added at the global level and not per instance level.

addMacro(name, callback, [inline = false])

Markdown.addMacro('button', function (props) {
  return {
    type: 'ButtonNode',
    data: {
      hName: 'button',
      hProperties: {
        className: ['button']
      }
    },
    children: [{
      type: 'text',
      value: props.text
    }]
  }
}, false)

const md = new Markdown(`
[button text="Click here to login"]
`)

await md.toHTML()
// returns: <button class="button">Click here to login</button>

JSON AST

The biggest feature of this module is the ability to output the JSON AST for your markdown. AST makes it super easy compose custom layouts, whereas the concrete HTML is harder to modify and customise.

Following the nodes structure of the AST.

Top level node

{
  type: 'root',
  children: [] // array of child nodes
}

Element node

{
  type: 'element',
  tag: 'p',
  props: {},
  children: [] // nested childs
}

Text node

{
  type: 'text',
  value: 'The raw text'
}

Assets detection

Dimer has a feature, where it will detect the relative images inside markdown and uploads them to the CDN. Also it will transparently replace the relative links with the uploaded file URL.

You do need the infrastructure and code around adding this feature when using this module. However, this module does let you define a custom callback, which can be used for detecting image URL's and returning a different URL to be replaced with.

Here's an example of same

const markdown = new Markdown({
  onUrl: async function (relativeUrl, file) {
    await fs.copyFile('DEST_PATH')
    return {
      url: NEW_URL,
      data: {
        hProperties: {
          dataSrc: '',
          rel: ''
        }
      } // optional
    }
  }
})

Syntax guide

The syntax guide is available here. It shows the Markdown code with the output in HTML and JSON.

Development

Fork and clone the repo.
Make your changes with good commit messages.
Once done, share a PR.

License

The code is released under MIT License.

Contributors

thetulage and everyone who has committed to this repo are proud contributors.

npm