mkdoc
v1.0.49
Published
Markdown processing tools
Downloads
65
Readme
Markdown 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.
Install
npm i -g mkdoc
Features
- Command line and programmatic control.
- Streaming build system, see mktask.
- DSL for including files, executing commands and more, see mkpi.
- Comment parser for 30+ languages, see mkparse.
- Fast, modular code with good coverage.
Usage
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.
Modules
Designed to be modular, a brief overview:
- mktask is a streaming build system.
- mkcat loads source markdown files.
- mkast is a library for converting tree nodes to JSON.
- mkpi parses processing instructions and runs macro functions.
- mkmsg injects a message into a stream.
- mkref injects link references into a stream.
- mkabs makes links absolute.
- mktoc creates a table of contents list.
- mkfilter removes nodes from the stream by type.
- mklevel changes heading levels.
- mktransform add custom stream transformations to the pipeline.
- mkout renders the tree to an output format (XML, HTML etc).
- mkparse parses comments from source files.
- mkapi generates API documentation from comments.
Command Line Tools
mk
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.
mkcat
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.
mkpi
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.
mkmsg
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.
mkref
Collates link references and appends them to the stream.
mkcat doc/readme.md | mkpi | mkref | mkout > README.md
mkabs
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
mkfilter
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
mklevel
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
mktransform
Add stream classes from files to a pipeline:
mkcat README.md | mktransform file.js transformer.js | mkout
mktoc
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
mkhigh
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.
mkpage
Create an HTML page:
mkcat file.md | mkpage --title=TITLE --style=style.css | mkout --html
mkout
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:
mkparse
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.
mkapi
Generate API documentation from comments in source files.
mkapi index.js lib/*.js --title=API > API.md
API
doc
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.
License
MIT
Created by mkdoc on August 3, 2016