markdown-them
v1.0.17
Published
Markdown-them - useful markdown parser. Based on markdown-it.
Downloads
45
Maintainers
billxiaReadme
markdown-them
Useful markdown parser done right. Based on markdown-it. More useful features included than markdown-it, such as LaTeX formulas, GFM todo list, diagrams, etc. Aims to support every feature that Typora supports.
Table of content
Install
node.js:
npm install markdown-them --saveUsage examples
See also:
- API documentation - for more info and examples.
- Development info - for plugins writers.
demo.js
The file demo.js is included in the markdown-them package. Let's suppose you ran npm install markdown-them in directory ~/newfolder. Now you got an node_modules folder. To use the demo, copy the ~/newfolder/node_modules/markdown-them/mddocs/ folder, ~/newfolder/node_modules/markdown-them/htmldocs/ folder and ~/newfolder/node_modules/markdown-them/demo.js to the ~/newfolder directory. Then put some of your markdown file into the mddocs/ directory, and run node demo.js in your terminal. It should generate same name .html files in htmldocs/ directory.
If anything goes wrong, such as error in running demo.js, sth not rendered or sth rendered unexpected, please submit an issue.
Simple
// node.js, "classic" way:
var MarkdownIt = require('markdown-them'),
md = new MarkdownIt();
var result = md.render('# markdown-them rulezz!');
// node.js, the same, but with sugar:
var md = require('markdown-them')();
var result = md.render('# markdown-them rulezz!');Single line rendering, without paragraph wrap:
var md = require('markdown-them')();
var result = md.renderInline('__markdown-them__ rulezz!');Useful features
If you don't use some of these features, just do nothing with them. In very scarce conditions, you may trigger some syntaxs below, please submit an issue. Every feature below will become configurable in future versions.
Highlight
Opened by default, using highlight.js, but you still have to include a style sheet to see the result. Add
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/highlight.js/styles/xcode.min.css">inside the <head> tag of the html doc. Change xcode to any theme you like, here's the list.
LaTeX formula
LaTeX formula rendering:
var md = require('markdown-them')();
var result = md.render(`An inline formula $E=mc^2$ by Albert Einstein, and a display formula $$E=mc^2$$ again. Let\'s display
$$
E=mc^2
$$
one more time because it's so great!`);This project handles math formulas by KaTeX while rendering (not in browser!), but you still need to include css from KaTeX to make them look right. Add
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/[email protected]/dist/katex.min.css" integrity="sha384-t5CR+zwDAROtph0PXGte6ia8heboACF9R5l/DiY+WZ3P2lxNgvJkQk5n7GPvLMYw" crossorigin="anonymous">in your html <head></head> tag. Default supports $formula$ and \\(formula\\)for inline formulas, $$formula$$ and $$\nformula\n$$ for display formulas. Macros share in the whole markdown file, while not share between seperate files.
If any of your mathjax formula is available before but fails here, please submit an issue to let me know. That may take some time of yours, so if you do so, big thank for your contribution to the project!
Diagrams
This project supports diagrams written in mermaid, flowchartjs and sequence. Just the same as Typora.
Mermaid
Mermaid diagram rendering:
var md = require('markdown-them')();
var result = md.render(
`
\`\`\` mermaid
graph TD
A[Client] --> B[Load Balancer]
\`\`\`
`);This only keeps the code inside the fence unmodified and assign a mermaid class to the outside <div> tag, so you need to include mermaid.js in your html file to generate the chart. Add
<script src="https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.min.js"></script>at the end of the <body> tag. This will automaticly render the diagrams. You can change the cdn, or download the js file on your server and link to it.
Flowchart.js
var md = require('markdown-them')();
var result = md.render(
`
\`\`\`flow
st=>start: Start:>http://www.google.com[blank]
e=>end:>http://www.google.com
op1=>operation: My Operation
sub1=>subroutine: My Subroutine
cond=>condition: Yes
or No?:>http://www.google.com
io=>inputoutput: catch something...
para=>parallel: parallel tasks
st->op1->cond
cond(yes)->io->e
cond(no)->para
para(path1, bottom)->sub1(right)->op1
para(path2, top)->op1
\`\`\`
`);This only keeps the code inside the fence unmodified and assign a flowchartjs class to the outside <div> tag, so you need to include flowchart.js in your html file, which depends on jquery.js and raphael.js as a support. Sums up, add
<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/jquery.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/[email protected]/raphael.min.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/flowchart/1.15.0/flowchart.min.js"></script>
<script>$('.flowchartjs').flowChart();</script>at the end of the <body> tag. This will automaticly render the flowchart.js diagrams. You can change the cdn, or download the js file on your server and link to it. This cdn is somehow slow at my place, so I downloaded the js file for my using.
Sequence
Sequence diagram rendering:
var md = require('markdown-them')();
var result = md.render(
`
\`\`\`sequence
Andrew->China: Says Hello
Note right of China: China thinks\nabout it
China-->Andrew: How are you?
Andrew->>China: I am good thanks!
\`\`\`
`);This only keeps the code inside the fence unmodified and assign a sequence-diagram class to the outside <div> tag, so you need to include sequence-diagram-min.js and every file it depends on in your html file. It is to add
<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/jquery.min.js"></script>
<script src="./webfont.js"></script>
<script src="./snap.svg-min.js"></script>
<script src="./underscore-min.js"></script>
<script src="./sequence-diagram-min.js"></script>
<script>
var options = {theme: 'hand'};
$(".sequence-diagram").sequenceDiagram(options);
</script>at the end of the body tag. I downloaded all these files on the official website for my using. If you have included jquery.js in the doc before, you don't need to do it again. (Be ready, this js could run somehow slow)
GFM todo list
GFM todo list rendering:
var md = require('markdown-them')();
var result = md.render(
`todo-list:
- [x] LaTeX formula
- [X] mermaid diagram
- [x] GFM todo list
- [ ] highlight`
);Other usage
See the page for markdown-it.
Todo
- TOC
- blockcode linenumber
Authors
- Alex Kocharin github/rlidwka
- Vitaly Puzrin github/puzrin
markdown-it is the result of the decision of the authors who contributed to 99% of the Remarkable code to move to a project with the same authorship but new leadership (Vitaly and Alex). It's not a fork.
- Ze Xia github/bill-xia
I merged some plugins into this great project.
References / Thanks
Big thanks to John MacFarlane for his work on the CommonMark spec and reference implementations. His work saved us a lot of time during this project's development.
Big thanks to markdown-it markdown parser, it's a great project. And also thanks to every plugin writer for markdown-it, all of you gave me some ideas on how to implement some features.