开源软件名称（OpenSource Name）：

开源软件地址(OpenSource Url)：

开源编程语言(OpenSource Language)：

开源软件介绍(OpenSource Introduction)：

Table of contents

• Markdown processor
  • Setup
  • Generating HTML
  • Options
  • Use cases
    • User land features
    • Use Vue as the rendering layer
    • Validate cross referenced links
    • Collect todos in a document
  • Macros
    • Existing
    • Adding your own
  • Plugins
    • Shiki

Markdown processor

An improved markdown processor built on top of remark

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