Markdown processing tools
Make markdown documents
Creates stream pipelines that convert input commonmark to an abstract syntax tree and transforms the tree; the result is then typically converted back to markdown or to another format such as HTML, XML or JSON.
npm i -g mkdoc
This example illustrates how to create a readme file like this one from a source file and some include files:
var doc = require('mkdoc')
, pi = require('mkpi')
, ref = require('mkref')
, abs = require('mkabs')
, msg = require('mkmsg')
, toc = require('mktoc')
, out = require('mkout');
doc('doc/readme.md') // read markdown source document
.pipe(pi()) // parse processing instructions, includes etc.
.pipe(ref()) // include link references
.pipe(abs()) // make links absolute
.pipe(msg()) // append generator message
.pipe(toc()) // create and inject table of contents list
.pipe(out()) // convert abstract syntax tree to markdown
.pipe(process.stdout); // print the document
The equivalent command line:
mkcat doc/readme.md | mkpi | mkref | mkabs | mkmsg | mktoc | mkout
But the javascript version will be faster as it does not need to launch multiple processes and does not convert the stream to JSON.
Designed to be modular, a brief overview:
Runs tasks in build files, by default searches for mkdoc.js
in the current working directory and parent directories.
mk
When called with no arguments if a main
task is available it is invoked otherwise all tasks are executed in sequence.
Specified tasks are executed in sequence:
mk api readme
See the mkdoc.js file for an example and mktask for information on creating task functions.
Reads one or more markdown documents and serializes them to the output stream, this program is normally used at the beginning of a transform pipeline before being sent to mkout
:
mkcat file.md | mkout --xml
It can also accept input from stdin
:
cat file.md | mkcat | mkout
However this is not recommended because file path information is lost which is important for some processing tools such as mkpi which uses the file path to resolve relative include files.
Include markdown documents, source files and the output of commands:
mkcat doc/readme.md | mkpi | mkout > README.md
This program parses and executes processing instructions such as <? @include intro.md install.md ?>
.
You can inline macro functions for application-specific logic or create custom macro functions that may be shared between projects, see the mkpi docs for more details.
Appends or prepends a document to the stream:
mkcat doc/readme.md | mkpi | mkmsg | mkout > README.md
Typically used to append a generator message but may be used to inject any document at the beginning or end of the stream.
Collates link references and appends them to the stream.
mkcat doc/readme.md | mkpi | mkref | mkout > README.md
Make relative links absolute using the data in package.json
if no base URL is given.
mkcat doc/readme.md | mkpi | mkref | mkabs | mkout > README.md
Filters nodes by type from a stream.
To remove all headings from a document:
mkcat doc/readme.md | mkfilter --heading | mkout
Remove everything but code blocks from a document:
mkcat doc/readme.md | mkfilter --code-block --invert | mkout
Converts heading levels, use this to indent or outdent headings.
To increment all headings:
mkcat README.md | mklevel --all=1 | mkout
To convert level 3 headings to level 2:
mkcat README.md | mklevel -3=-1 | mkout
Add stream classes from files to a pipeline:
mkcat README.md | mktransform file.js transformer.js | mkout
Create a standalone table of contents:
mkcat README.md | mktoc -s | mkout > TOC.md
Inject the table of contents into a document containing the <!-- @toc -->
marker:
mkcat README.md | mktoc | mkout > README.md
Highlight code blocks with ANSI escape characters suitable for printing to a terminal:
mkcat README.md | mkhigh -o esc | mkout
Generate a standalone HTML page with highlighted code blocks converted to <pre>
elements:
mkcat README.md | mkhigh | mkpage | mkhtml > README.html
This program requires that source-highlight is installed.
Create an HTML page:
mkcat file.md | mkpage --title=TITLE --style=style.css | mkout --html
Render a stream to markdown, XML, HTML and JSON.
mkcat file.md | mkout --html
There are also some specialized output programs for certain types that expose more options:
Parse comments and tag annotations from source files.
mkparse index.js > index.doc.js
Low-level parser for working with comments and tag annotations, see mkparse. The command line interface provides the means to quickly inspect the comments in a document, extract comments to a separate file or strip comments from a document.
Generate API documentation from comments in source files.
mkapi index.js lib/*.js --title=API > API.md
doc(files[, opts])
Creates a stream pipeline using mkcat from the given source files.
Rather than an array you can pass file paths in the form:
doc('intro.md', 'install.md', {});
Returns an output stream.
files
Array source markdown files.opts
Object processing options.MIT
Created by mkdoc on August 3, 2016