Sign Up for Free

RunKit +

Try any Node.js package right in your browser

This is a playground to test code. It runs a full Node.js environment and already has all of npm’s 1,000,000+ packages pre-installed, including @dimerapp/markdown with all npm packages installed. Try it out:

var markdown = require("@dimerapp/markdown")

This service is provided by RunKit and is not affiliated with npm, Inc or the package authors.

@dimerapp/markdown v4.0.0

A markdown process

## Table of contents

Markdown processor

An improved markdown processor built on top of remark

circleci-image typescript-image npm-image license-image

Dimer markdown is an opinionated markdown processor built on top of remark with following features and goals.

  • Implements the markdown directives proposal to extend the markdown native capabilities
  • Introduces the concept of macros that builds up on top of directives
  • Selectively allow/dis-allow HTML inside Markdown
  • Register listeners to hook into Markdown compilation phase
  • First class support for frontmatter, generating toc and excerpt from the doc summary

Setup

Install the package from npm registry as follows:

npm i @dimerapp/markdown

# yarn
yarn add @dimerapp/markdown

And import the package to process the markdown files.

import { MarkdownFile } from '@dimerapp/markdown'

const markdownContents = `
# Hello world

This is a markdown doc with some GFM syntax

- [ ] Todo 1
- [ ] Todo 2`

const md = new MarkdownFile(markdownContents)
const ast = await md.process()

Generating HTML

The package encourages using AST vs directly generating the HTML from the markdown. Using AST let you bring your own frontend layer. It is like creating a JSON API and then using Vue or React to create webpages.

However, if also ship with a helper function to convert the markdown file instance to HTML.

import { MarkdownFile, toHTML } from '@dimerapp/markdown'

const md = new MarkdownFile(contents)
await md.process()

const { contents, summary, toc, excerpt } = toHTML(md)
  • contents is the HTML representation of the markdown file contents
  • summary is the HTML representation of the file summary. You can also define summary using frontmatter.
  • toc is the HTML representation of the table of contents. Available only when generateToc option was used.
  • excerpt is the plain text version of summary. Helpful for SEO

Options

You can pass the following options when creating a new instance of the MarkdownFile.

import { MarkdownFile } from '@dimerapp/markdown'

const md = new MarkdownFile(contents, {
  generateToc?: boolean
  allowHtml?: boolean
  filePath?: string
  enableDirectives?: boolean
  collectAssets?: boolean
})
  • generateToc: Define whether you want to generate the table of contents or not. Defaults to false.
  • allowHtml: Control whether you want to allow HTML inside Markdown or not. Defaults to false.
  • filePath: Optionally you can attach the absolute file path to the mdFile instance.
  • enableDirectives: Enable support for the directives proposal. Defaults to false.
  • collectAssets: Decide if you want us to collect the asset links referenced inside your markdown file. Currently image links are only collected.

Use cases

Lets go over all the use cases that this package can serve

User land features

TBD

Use Vue as the rendering layer

TBD

Validate cross referenced links

TBD

Collect todos in a document

TBD

Macros

Existing

Adding your own

Plugins

Shiki

TBD

RunKit is a free, in-browser JavaScript dev environment for prototyping Node.js code, with every npm package installed. Sign up to share your code.
Sign Up for Free