mkdoc

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.

---

• Install
• Features
• Usage
• Modules
• Command Line Tools
  • mk
  • mkcat
  • mkpi
  • mkmsg
  • mkref
  • mkabs
  • mkfilter
  • mklevel
  • mktransform
  • mktoc
  • mkhigh
  • mkpage
  • mkout
  • mkparse
  • mkapi
• API
  • doc
• License

---

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.

Source Code | CLI Help

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.

Source Code | CLI Help

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.

Source Code | CLI Help

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.

Source Code | CLI Help

mkref

Collates link references and appends them to the stream.

mkcat doc/readme.md | mkpi | mkref | mkout > README.md

Source Code | CLI Help

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

Source Code | CLI Help

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

Source Code | CLI Help

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

Source Code | CLI Help

mktransform

Add stream classes from files to a pipeline:

mkcat README.md | mktransform file.js transformer.js | mkout

Source Code | CLI Help

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

Source Code | CLI Help

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.

Source Code | CLI Help

mkpage

Create an HTML page:

mkcat file.md | mkpage --title=TITLE --style=style.css | mkout --html

Source Code | CLI Help

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:

• mkman - render to man page
• mktext - render to plain text
• mkhtml - render to HTML page

Source Code | CLI Help

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.

Source Code | CLI Help

mkapi

Generate API documentation from comments in source files.

mkapi index.js lib/*.js --title=API > API.md

Source Code | CLI Help

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