This project pulls together a number of other projects, along with some custom extensions, to provide rendering to HTML for a custom, extended version of Markdown.

These are the primary projects used to render various types of content:

Install from npm

# Update project npm config to refer to correct registry for the @doc-utils scope
echo '@doc-utils:registry=https://gitea.jbrumond.me/api/packages/doc-utils/npm/' >> ./.npmrc

# Install package for programatic use
npm install --save @doc-utils/markdown2html

# Install globally for CLI usage
npm install --global @doc-utils/markdown2html

Building from source

npm run tsc

Programatic Use

import { MarkdownOptions, render_markdown_to_html } from '@doc-utils/markdown2html';

async function main() {
  const options: MarkdownOptions = {
    base_url: 'https://example.com',
  };

  const html = await render_markdown_to_html('# This is some markdown', options);
}

Handling front matter

import { process_frontmatter } from '@doc-utils/markdown2html';

const raw_content = `---
title: Example Markdown with front matter
foo:
- bar
- baz
---

# This is some markdown
`;

const { frontmatter, document } = process_frontmatter(raw_content);

console.log(frontmatter.title);  // "Example Markdown with front matter"
console.log(frontmatter.foo);    // [ "bar", "baz" ]
console.log(document);           // "\n# This is some markdown\n"

Command Line Use

echo '# This is some markdown' | ./bin/markdown2html --base-url 'https://example.com' > output.html

Handling front matter

filecontents="---
title: Example Markdown with front matter
foo:
- bar
- baz
---

# This is some markdown
"

echo "$filecontents" | ./bin/strip-frontmatter frontmatter.json > markdown.md

Options

options.base_url / --base-url - Sets the Marked baseUrl option
options.breaks / --breaks - Sets the Marked breaks option
options.inline / --inline - Sets the Marked inline option
options.katex_macros / --katex-macro - Defines any global Katex macros to be used.
options.extensions - Any additional Marked extension factories to use

Katex Macro Examples

const options: MarkdownOptions = {
  katex_macros: {
    '\\foobar': '\\text{foo} + \\text{bar}',
    '\\bazqux': '\\text{baz} + \\text{qux}',
  }
};

./bin/markdown2html \
  --katex-macro '\foobar' '\text{foo} + \text{bar}' \
  --katex-macro '\bazqux' '\text{baz} + \text{qux}'

Extensions

// extension.ts
import type { marked } from 'marked';
import type { MarkdownOptions } from '@doc-utils/markdown2html';

export interface MyCustomToken extends marked.Tokens.Generic {
  // ...
}

export function my_extension(renderer: marked.Renderer, options: MarkdownOptions) : marked.TokenizerExtension & marked.RendererExtension {
  return {
    name: 'my_extension',
    level: 'inline',
    start: (src) => src.match(/...../)?.index,
    tokenizer(src, tokens) : MyCustomToken {
      const rule = /...../;
      const match = rule.exec(src);

      if (match) {
        return {
          // ...
        };
      }
    },
    renderer(token: MyCustomToken) {
      return '<!-- rendered html -->';
    }
  };
};



// ----------

// main.ts
import { my_extension } from './extension';
import { MarkdownOptions, render_markdown_to_html } from '@doc-utils/markdown2html';

async function main() {
  const options: MarkdownOptions = {
    // ...
    extensions: [
      my_extension
    ]
  };

  const html = await render_markdown_to_html('# This is some markdown', options);
}