@jhuix/imark

v0.1.2

Published

4 months ago

a markdown to html converter

0High
0Medium
0Low

iMark is a javascript's lib that make markdown to html with some extensions features(include extensions of abcjs, echarts, mermaid, plantuml, railroad, wavedrom, katex, gird tables, gfm extended tables etc.).

If you think the imark library can help you or also hope to encourage the author, click on the top right corner to give me a Star⭐️.

Feature highlights

compliant — 100% to CommonMark, 100% to GFM or MDX with a plugin

MDAST — markdown ASTs that inspecting and changing content made easy

HAST — HTML ASTs that inspecting and changing content made easy

Syntax

Markdown is parsed and serialized according to CommonMark. Other plugins can add support for syntax extensions.

It's used by micromark for it's parsing. See its documentation for more information on markdown, CommonMark, and extensions.

MarkDown Syntax tree

The syntax tree used in iMark is mdast by remark-parse. It represents markdown constructs as JSON objects.

This markdown:

## Hello *Pluto*!

…yields the following tree (positional info remove for brevity):

{
  type: 'heading',
  depth: 2,
  children: [
    {type: 'text', value: 'Hello '},
    {type: 'emphasis', children: [{type: 'text', value: 'Pluto'}]}
    {type: 'text', value: '!'}
  ]
}

HTML Syntax tree

The syntax tree used in iMark is hast by remark-rehype.

Intro

iMark is an ecosystem of plugins that work with markdown as structured data, specifically ASTs (abstract syntax trees). ASTs make it easy for programs to deal with markdown. We call those programs plugins. Plugins inspect and change trees. You can use the many existing plugins or you can make your own.

iMark integrated some packages that contains the following:

unified — it is the core project that transforms content with ASTs.
remark-parse — plugin to take markdown as input and turn it into the markdown ASTs (mdast)
remark-rehype — plugin to turn markdown into the HTML ASTs (hast)
rehype-format — plugin to format a HTML ASTs (hast)
rehype-stringify — plugin to take a HTML ASTs (hast) and turn it into HTML as output

It supports CommonMark by default. Non-standard markdown extensions can be enabled with plugins. For example, it support for GFM (autolink literals, footnotes, strikethrough, tables, tasklists) in @jhuix/remark-gfm. It also support Kroki diagrams server, kroki provides a unified API with support for BlockDiag (BlockDiag, SeqDiag, ActDiag, NwDiag, PacketDiag, RackDiag), BPMN, Bytefield, C4 (with PlantUML), D2, DBML, Ditaa, Erd, Excalidraw, GraphViz, Mermaid, Nomnoml, Pikchr, PlantUML, Structurizr, SvgBob, Symbolator, TikZ, UMLet, Vega, Vega-Lite, WaveDrom, WireViz..

Supports extensions features as follows, preview as the document -- iMark's Features:

Usage

Installation

Using npm:
```
npm install @jhuix/imark
```
Note: add --save if you are using npm < 5.0.0
In a browser:
put the following line into your HTML page <body>:
```
<script src="dist/imark.js"></script>
```

Quick Example

Browser

Put the following line into your HTML page <body>:

    <div id="main" class="workspace-container main-toc-row"></div>
    <script type="module">
      import imark from "../dist/imark.js";
      (function(element) {
        window
          .fetch("../docs/imark-features.md")
          .then(function(response) {
            if (response.ok) {
              return response.text();
            }
          })
          .then(function(text) {
            imark.render(text, element, {render:{toc:{title:'大纲',compatible:false}}})
          })
          .catch(function(error) {
            console.log(error);
          });
      })(document.getElementById("main"));
    </script>

Options

iMark's Options be defined as follows:

interface IMarkOptions {
    remark?: RemarkSetting
    rehype?: RehypeOptions
    render?: RenderOptions
  }

See iMark's Options

`remark` (RemarkSetting)

type RemarkSetting = HeadOptions | KatexDelimiters | GfmOptions | EmojiOptions

`rehype` (RehypeOptions)

The configuration for remark rehype.

interface RehypeOptions extends rehypeOptons {
  outFormat?: boolean;
}

`render` (RenderOptions)

The configuration for render html.

type RenderOptions = {
  katex: KatexOptions;
  toc: TocOptions;
  mermaid: MermaidConfig;
  echarts: EChartsInitOpts;
  abc: AbcVisualParams;
  uml: UmlOptions;
  wavedrom: WaveDromOptions;
  vega: VegaEmbedOptions;
}

API

Global imark object, which can be accessed after including imark.js in script tag or through require('imark') in AMD environment. See iMark's API.

imark.use
```
(vaule: Schema | IMarkPlugins) => IMark
```
Use sanitize options or imark plugins. Return imark instance.
imark.setting
```
(name: string, remarkOptions: RemarkSetting) => IMark
```
Set the necessary settings for parsing markdown. Return imark instance.

imark.parse

(md: string, remarkOptions?: RemarkSetting, rehypeOptions?: RehypeOptions) => Promise<RenderContext>

Parse markdown to html with additional renders.

imark.render

render(md: string, root?: HTMLElement, imarkOptions?: IMarkOptions)

Render markdown to a html element.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme