131 lines
2.8 KiB
Markdown
131 lines
2.8 KiB
Markdown
|
|
# 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:
|
|
|
|
- [Marked](https://marked.js.org/)
|
|
- [Prism.js](https://prismjs.com/)
|
|
- [Vega](https://vega.github.io/vega/)
|
|
- [nomnoml](https://www.nomnoml.com/)
|
|
- [bytefield-svg](https://bytefield-svg.deepsymmetry.org/bytefield-svg/1.6.1/intro.html)
|
|
- [Katex](https://katex.org/)
|
|
- [Pikchr](https://pikchr.org/home/doc/trunk/homepage.md)
|
|
- [node-qrcode](https://github.com/soldair/node-qrcode)
|
|
|
|
|
|
|
|
## Building from source
|
|
|
|
```bash
|
|
npm run tsc
|
|
```
|
|
|
|
|
|
|
|
## Programatic Use
|
|
|
|
```ts
|
|
import { MarkdownOptions, render_markdown_to_html } from './build';
|
|
|
|
async function main() {
|
|
const options: MarkdownOptions = {
|
|
base_url: 'https://example.com',
|
|
};
|
|
|
|
const html = await render_markdown_to_html('# This is some markdown', options);
|
|
}
|
|
```
|
|
|
|
|
|
|
|
## Command Line Use
|
|
|
|
```bash
|
|
echo '# This is some markdown' | ./bin/markdown2html --base-url 'https://example.com' > output.html
|
|
```
|
|
|
|
|
|
|
|
## 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
|
|
|
|
```ts
|
|
const options: MarkdownOptions = {
|
|
katex_macros: {
|
|
'\\foobar': '\\text{foo} + \\text{bar}',
|
|
'\\bazqux': '\\text{baz} + \\text{qux}',
|
|
}
|
|
};
|
|
```
|
|
|
|
```bash
|
|
./bin/markdown2html \
|
|
--katex-macro '\foobar' '\text{foo}' '\text{bar}' \
|
|
--katex-macro '\bazqux' '\text{baz}' '\text{qux}'
|
|
```
|
|
|
|
|
|
|
|
|
|
## Extensions
|
|
|
|
```ts
|
|
// extension.ts
|
|
import type { marked } from 'marked';
|
|
import type { MarkdownOptions } from './build';
|
|
|
|
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 './build';
|
|
|
|
async function main() {
|
|
const options: MarkdownOptions = {
|
|
// ...
|
|
extensions: [
|
|
my_extension
|
|
]
|
|
};
|
|
|
|
const html = await render_markdown_to_html('# This is some markdown', options);
|
|
}
|
|
```
|
|
|