Not Providing Milkshakes


    3.2.2 • Public • Published
    Dimer App

    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.


    npm i @dimerapp/markdown
    # Yarn
    yarn add @dimerapp/markdown


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


    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.


    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.

    This is a 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="", theme="light"]

    youtube (inline)

    Adds a youtube embed

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

    collapse (block)

    [collapse title=""]
    Inner content


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

    codegroup (block)

    Creates a tabbed group of multiple codeblocks.

    Tab one
    Tab two


    Include other markdown files as partials.

    [include path="./"]

    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>


    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.


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


    The code is released under MIT License.


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


    npm i @dimerapp/markdown

    DownloadsWeekly Downloads






    Unpacked Size

    46.2 kB

    Total Files


    Last publish


    • virk
    • prasanjit
    • atinux