Home

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

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": "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:

Fields

These are the common fields that apply to all partial types:

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.

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:

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:

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).