Markdown partial processor
Markdown partial processor.
Designed to generate markdown documents from a series of partials.
- Synchronize your
READMEwith your code.
txtdocuments 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.
npm i -g mdp
Usage: mdp [-vfh] [--color|--no-color] [--debug] [-v|--verbose][-f|--force] [--pandoc] [--inspect][--pedantic|--no-pedantic] [--toc|--no-toc] [-h|--help][--version] [--log-level=<level>] [--log-file=<file>][--section=<1-8>] [-n|--filename=<name>][--toc-title=<title>] [-p|--print=<format>][--timeout=<ms>] [-t|--title=<title>][-i|--input=<file...>] [-o|--output=<file...>][-w|--middleware=<file...>] <args>Markdown partial processor.Options:--[no]-pedantic Enable or disable pedantic middleware.--[no]-color Enable or disable terminal colors.--log-file=[file] Redirect to log file.--debug Enable stack traces.-v, --verbose Print more information.-f, --force Force file overwrite.--pandoc Include pandoc meta data.--inspect Enable inspect middleware.--section=[1-8] Set the man page section.-n, --filename=[name] Set the output file name.--log-level=[level] Set the log level.--[no]-toc Enable or disable the table of contents middleware,this overrides a toc value in the meta data.--toc-title=[title] Set the title for the table of contents, thisoverrides --no-toc and the toc meta data property.-p, --print=[format] Print document to stdout.--timeout=[ms] Millisecond timeout for middleware.-t, --title=[title] Document title.-i, --input=[file ...] Meta definition file(s).-o, --output=[file ...] Output file(s), may be specified once for eachformat. The output format is determined by the fileextension, md, txt, html, xhtml or [1-8]. If nooutput files are specified then README.md isgenerated in the current directory. If the outputpath is a directory then a file is created for eachsupported format.-w, --middleware=[file ...]Require custom middleware.-h, --help Display this help and exit.--version Output version information and exit.Report bugs to muji <firstname.lastname@example.org>.
The program help output is also available as markdown see MANUAL.
This document was generated with the following configuration (see package.json):
Note this is not necessarily the optimal configuration it is designed to showcase the partial functionality.
Meta data describes processing options and how you want to collate the partials.
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 if
links: The name of a links include file, resolved relative to
toc: Enable the table of contents middleware with
trueor set to a string to include a title above the table of contents.
order: A boolean that indicates the
tocmiddleware 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 for
titleproperties 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 specifying
envon a partial object, see environment.
"generator": "Generated by [mdp(1)]().""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
A partial may be one of:
literal|lit: A string literal.
reference|ref: A property reference.
include|inc: Include a file, normally a markdown document but not necessarily.
binary|bin: Execute a command and use
stdoutas the content.
require|req: Require a
.jsmodule or a
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 the
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:
language: A language to assign when wrapping as a
footer: Markdown text to inject after the partial content.
trim: Remove leading and trailing whitespace from the transformed result.
reqetc.) this indicates that the result should be converted to
JSON.stringify. The stringify implementation is circular reference safe and uses two spaces as the indentation but you may modify this with the
indent: An integer indicating the number of spaces to indent when converting to a
format: A custom format string to use to wrap the partial result, should have a single
%sthat will be replaced with the partial content.
env: If environment variable replacement has been enabled in the configuration then you may set this to
falseon a partial to disable environment variable replacement for the partial.
At it's simplest a partial may be a string that contains markdown text.
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
A reference to an object or a json object definition.
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 to
falsedisables the default behaviour of removing trailing whitespace from the file contents.
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 command
stderrstream should be used instead of the
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.
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.
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
false for the partial.
Environment variables are replaced using the forms:
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:
When replacement is performed the backslash will be removed, resulting in literal variable references:
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
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 use
tokens.peek()to look ahead but you should not modify the array.
next: A callback to invoke when the token has been processed, signature is:
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.
inspect middleware is shown below:
You can enable it by declaring it in the meta data (or by using
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).