doc-utils
Repositories
7
 Projects Packages

@doc-utils/markdown2html (0.3.6)

Published 2023-08-19 23:03:50 +00:00 by drone in doc-utils/markdown2html

Installation

@doc-utils:registry=
npm install @doc-utils/markdown2html@0.3.6
"@doc-utils/markdown2html": "0.3.6"

About this package

Markdown to HTML Converter

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);
}

Dependencies

Dependencies

ID Version
bytefield-svg ^1.6.1
dompurify ^2.3.6
jsdom ^20.0.1
katex ^0.16.7
marked ^5.0.2
nomnoml ^1.5.2
pikchr ^0.0.5
prismjs ^1.29.0
qrcode ^1.5.1
vega ^5.22.1
yaml ^2.2.2

Development Dependencies

ID Version
@types/dompurify ^2.3.3
@types/jsdom ^20.0.0
@types/katex ^0.16.0
@types/luxon ^3.1.0
@types/marked ^5.0.0
@types/node ^18.11.18
@types/prismjs ^1.26.0
@types/qrcode ^1.5.0
typescript ^5.0.4
Details
npm
doc-utils/markdown2html
2023-08-19 23:03:50 +00:00
92
latest
2.3 MiB
Assets (1)
markdown2html-0.3.6.tgz 2.3 MiB
Versions (36) View all
0.3.6 2023-08-19
0.3.5 2023-08-19
0.3.4 2023-06-11
0.3.3 2023-06-04
0.3.2 2023-05-28
Issues