remark-man

remark-man compiles markdown into man pages. Great unicode support, name, section, and description detection, nested block quotes and lists, tables, and more.

Table of Contents

• Installation

• Command line

• Programmatic

  • remark.use(man, options)

• Configuration

• License

Installation

npm:

npm install remark-man

remark-man is also available for duo, and as an AMD, CommonJS, and globals module, uncompressed and compressed.

Command line

Use remark-man together with remark:

npm install --global remark remark-man

Let’s say example.md looks as follows:

# ls(1) -- list directory contents

## SYNOPSIS

`ls` \[`-ABCFGHLOPRSTUW@abcdefghiklmnopqrstuwx1`\] \[_file_ _..._\]

Then, to run remark-man on example.md:

remark -u remark-man example.md -o
#
# Yields (check out the newly created `example.1` file):
#
# .TH "LS" "1" "June 2015" "" ""
# .SH "NAME"
# \fBls\fR - list directory contents
# .SH "SYNOPSIS"
# .P
# \fBls\fR \[lB]\fB-ABCFGHLOPRSTUW\[at]abcdefghiklmnopqrstuwx1\fR\[rB] \[lB]\fIfile\fR \fI...\fR\[rB]
#

Now, that looks horrible, but that’s how roff/groff/troff are 😉.

To properly view that man page, use something like this: man ./example.1.

Programmatic

remark.use(man, options)

Parameters

• man — This plugin;
• options (Object?) — See below.

Configuration

All options, including the option object itself, are optional:

• name (string);

• section (number or string);

• description (string);

• date (given to new Date());

• version (string);

• manual (string);

• slug (*) — Passed to remark-slug, used for anchor-link detection.

Pass these to remark.use() as a second argument, or on the CLI:

remark --use 'man=name:"foo",section:2,description:"bar"' example.md

You can define these in .remarkrc or package.json files too. An example .remarkrc file could look as follows:

{
  "plugins": {
    "man": {
        "manual": "Phonetic Alphabet",
        "version": "0.1.0",
        "date": "2015-06-01"
    }
  },
  "settings": {
    "commonmark": true
  }
}

Where the object at plugins.man are the options for remark-man. The object at settings determines how remark parses (and compiles) markdown code. Read more about the latter on remark’s readme.

The name and section can also be inferred from the file’s name: hello-world.1.md will set name to "hello-world" and section to "1".

In addition, you can also provide inline configuration with a main heading:

# hello-world(7) -- Two common words

...will set name to "hello-world", section to "7", and description to "Two common words".

The main heading overwrites the file name, and the file name the plugin settings.

License

MIT © Titus Wormer