Awesome
Table of Contents
mdp(1)
Markdown partial processor.
Deprecated: replaced by mkdoc.
Designed to generate markdown documents from a series of partials.
Read partial to learn how to define partials or get a quick feel by checking the configuration that created this document, see usage for an abbreviated look at the command line options.
Features
- Synchronize your
README
with your code. - Generate
markdown
,html
,man
andtxt
documents from partials. - Flexible middleware design, see middleware.
- Generate a table of contents for markdown document(s).
- Concatenate multiple markdown documents into a single file.
- Include the output of a shell program, great for examples or program usage.
- Convert relative links to absolute links so your readme documents work when displayed on the npm website.
- Be pedantic in presentation, but lazy authoring. Ensure paragraphs are terminated with a period and start out title case.
Install
npm i -g mdp
Configuration
This document was generated with the following configuration (see package.json):
{
"title": {
"ref": "name",
"format": "%s(1)"
},
"pedantic": true,
"include": "doc/readme",
"require": "lib",
"gfm": true,
"branch": "master",
"links": "links.md",
"toc": "Table of Contents",
"order": false,
"base": "https://github.com/tmpfs/mdp",
"env": true,
"partial": [
{
"ref": "description"
},
{
"inc": [
"introduction.md",
"features.md",
"install.md"
]
},
{
"title": "Usage",
"bin": "mdp --help",
"type": "code",
"footer": "The program help output is also available as markdown see [MANUAL](/MANUAL.md)"
},
{
"title": "Configuration",
"text": "This document was generated with the following configuration (see [package.json](/package.json)):",
"ref": "mdp",
"stringify": true,
"format": "```json\n%s\n```",
"footer": "***Note this is not necessarily the optimal configuration it is designed to showcase the partial functionality.***"
},
{
"inc": "meta.md"
},
{
"req": "defaults.js",
"type": "code",
"language": "javascript"
},
{
"inc": [
"partial.md",
"environment.md",
"generator.md"
]
},
{
"title": "Middleware",
"inc": "middleware.md"
},
{
"text": "The `inspect` middleware is shown below:",
"req": "middleware/inspect.js",
"type": "code",
"language": "javascript"
},
{
"text": "You can enable it by declaring it in the meta data (or by using `--inspect`):",
"obj": {
"middleware": [
"inspect"
]
},
"type": "code",
"language": "json"
},
{
"inc": [
"license.md",
"footer.md"
]
}
]
}
Note this is not necessarily the optimal configuration it is designed to showcase the partial functionality.
Meta
Meta data describes processing options and how you want to collate the partials.
Options
generator
: A boolean that disables inclusion of the generator text.title
: A string that sets the document title or a partial definition.gfm
: A boolean that indicates that github flavoured markdown is in use.period
: The character used by the pedantic middleware.include
: A directory that is the base path for include partials.require
: A directory that is the base path for require partials.branch
: A branch name to use when resolving links that begin with/
for github, only applicable ifgfm
is set.links
: The name of a links include file, resolved relative toinclude
.toc
: Enable the table of contents middleware withtrue
or set to a string to include a title above the table of contents.order
: A boolean that indicates thetoc
middleware should use ordered lists.base
: Enable the absolute link middleware, specifies the base URL for absolute links.hash
: A boolean that controls whether the absolute middleware operates on URLs that begin with#
.level
: An integer indicating the header level fortitle
properties in partial definitions.partial
: Array of partial definitions, see partial.env
: A boolean that indicates environment variables are substituted in partial contents. You may override this on a partial level by specifyingenv
on a partial object, see environment.
{
"generator": "Generated by [mdp(1)](https://github.com/tmpfs/mdp).",
"title": null,
"gfm": true,
"period": ".",
"pedantic": false,
"include": null,
"require": null,
"branch": "master",
"links": null,
"toc": false,
"order": false,
"base": null,
"hash": false,
"level": 2,
"partial": null,
"env": false
}
Partial
A partial may be one of:
literal|lit
: A string literal.reference|ref
: A property reference.object|obj
: A json or javascript object reference.include|inc
: Include a file, normally a markdown document but not necessarily.binary|bin
: Execute a command and usestdout
as the content.require|req
: Require a.js
module or a.json
file.
Fields
These are the common fields that apply to all partial types:
title
: Injects a markdown heading for the partial, by default this is a level 2 heading although you may adjust this with thelevel
configuration property.text
: Markdown text to inject after the title but before the partial content.type
: A type that indicates how the partial content should be wrapped, eg:code
.language
: A language to assign when wrapping as acode
block.footer
: Markdown text to inject after the partial content.trim
: Remove leading and trailing whitespace from the transformed result.stringify
: When referencing javascript objects (viaref
,req
etc.) this indicates that the result should be converted toJSON
usingJSON.stringify
. The stringify implementation is circular reference safe and uses two spaces as the indentation but you may modify this with theindent
property.indent
: An integer indicating the number of spaces to indent when converting to aJSON
string.format
: A custom format string to use to wrap the partial result, should have a single%s
that will be replaced with the partial content.env
: If environment variable replacement has been enabled in the configuration then you may set this tofalse
on a partial to disable environment variable replacement for the partial.
Literal
At it's simplest a partial may be a string that contains markdown text.
Reference
A reference to a property in the meta definition file. This is useful when you are embedding the partial definition in package.json
and wish to reference the existing meta data such as name
or description
.
Object
A reference to an object or a json object definition.
Include
Include a file as a partial. Files are resolved relative to the include
configuration directory, if the include
configuration property is not set they are resolved relative to the current working directory. Typically this is a markdown document to include literally, but can also be used to wrap other files in markdown code blocks, useful for examples.
Note that when including files trailing whitespace is removed from the file contents before inclusion in the resulting document.
trim
: A boolean that when set tofalse
disables the default behaviour of removing trailing whitespace from the file contents.
Binary
Execute a command and include the command's stdout
in the resulting document. If the command prints markdown then you can use that output, otherwise you can wrap the command's output as a markdown element or just include it literally. This is particularly useful when you want to include a program's help (--help
) output as a section within a document.
Binaries inherit the environment of the parent process (mdp
) and the current working directory. The following fields are specific to the binary
partial type:
stderr
: A boolean that indicates that the commandstderr
stream should be used instead of thestdout
stream.cmd
: A directory that becomes the working directory for the child process.env
: An object containing properties to append to the environment for the child process.
Require
Require a js
module or a json
file. Files are resolved relative to the require
configuration directory, if the require
configuration property is not set they are resolved relative to the current working directory.
Environment
You may enable environment variable replacement by setting the env
configuration property to true
. If you wish to disable environment variable replacement for a partial set env
to false
for the partial.
Environment variables are replaced using the forms:
$variable
${variable}
If the referenced variable is not set then the variable reference is not replaced and will be visible in the result.
You may disable environment variable replacement by preceeding the dollar with a single backslash:
$variable
${variable}
When replacement is performed the backslash will be removed, resulting in literal variable references:
$variable
${variable}
Generator
By default mdp(1)
will append a generator message to the end of the document, it is nice if you wish to leave it in to help spread the word, however you may disable this message by setting the generator
property to false
.
Middleware
Middleware functions are executed asynchronously once for each token encountered in the markdown document.
Implementations are passed a meta
object which is the merged result of processing all the input configuration files (--input
) and should return a closure that will be invoked once for each token in the document.
The closure function must be a named function and should return when zero arguments are passed so that function names may be used within error messages. It is passed the arguments:
token
: The current token being processed.tokens
: The list of all tokens in the document, you may usetokens.peek()
to look ahead but you should not modify the array.next
: A callback to invoke when the token has been processed, signature is:next(err)
.
If you pass an error to next the program will terminate immediately, failure to invoke next()
will result in an error after a timeout (--timeout
) has been exceeded.
The inspect
middleware is shown below:
function middleware(/*meta*/) {
return function inspect(token, tokens, next) {
if(!arguments.length) {
return;
}
console.dir(token);
next();
}
}
You can enable it by declaring it in the meta data (or by using --inspect
):
{
"middleware": [
"inspect"
]
}
License
Everything is MIT. Read the license if you feel inclined.
This program was built using the command module, if you care for excellent documentation and write command line interfaces you should check it out.
Generated by mdp(1).