warrior286/remark-man

plugin to compile markdown to man pages

remark-man

remark plugin to compile markdown to man pages.

Contents

• What is this?
• When should I use this?
• Install
• Use
• API
  • unified().use(remarkMan[, options])
• Types
• Compatibility
• Security
• Related
• Contribute
• License

What is this?

This package is a unified (remark) plugin that compiles markdown to roff/groff/troff (the format used for man pages).

unified is a project that transforms content with abstract syntax trees (ASTs). remark adds support for markdown to unified. mdast is the markdown AST that remark uses. This is a remark plugin that adds a compiler to compile mdast to a string.

When should I use this?

This plugin adds a compiler for remark, which means that it turns the final markdown (mdast) syntax tree into a string.

This plugin, combined with remark, is quite good at turning markdown into man pages. It has good unicode support, proper support for nested lists and block quotes, supports tables, and more.

Install

This package is ESM only. In Node.js (version 12.20+, 14.14+, or 16.0+), install with npm:

npm install remark-man

In Deno with esm.sh:

import remarkMan from 'https://esm.sh/remark-man@8'

In browsers with esm.sh:

<script type="module">
  import remarkMan from 'https://esm.sh/remark-man@8?bundle'
</script>

Use

Say we have some markdown in example.md:

# ls(1) -- list directory contents

## SYNOPSIS

`ls` \[`-ABCFGHLOPRSTUW@abcdefghiklmnopqrstuwx1`] \[*file* *...*]

And our module example.js looks as follows:

import {read, write} from 'to-vfile'
import {unified} from 'unified'
import remarkParse from 'remark-parse'
import remarkMan from 'remark-man'

main()

async function main() {
  const file = await unified()
    .use(remarkParse)
    .use(remarkMan)
    .process(await read('example.md'))

  file.extname = '.1'
  await write(file)
}

Now running node example.js creates a file example.1 that contains:

.TH "LS" "1" "November 2021" "" ""
.SH "NAME"
\fBls\fR - list directory contents
.SH "SYNOPSIS"
.P
\fBls\fR \[lB]\fB-ABCFGHLOPRSTUW@abcdefghiklmnopqrstuwx1\fR\[rB] \[lB]\fIfile\fR \fI...\fR\[rB]

That’s not very readable but a man page viewer can solve that. Run man ./example.1 to view the rendered result.

API

This package exports no identifiers. The default export is remarkMan.

unified().use(remarkMan[, options])

Plugin to compile Markdown to man pages.

options

Configuration (optional).

options.name

Title of the page (string, optional). Is inferred from the main heading (# hello-world(7) sets name to 'hello-world') or from the file’s name (hello-world.1.md sets name to 'hello-world').

options.section

Man section of page (number or string, optional). Is inferred from the main heading (# hello-world(7) sets section to 7) or from the file’s name (hello-world.1.md sets section to 1).

options.description

Description of page (string, optional). Is inferred from the main heading (# hello-world(7) -- Two common words sets description to 'Two common words').

options.date

Date of page (number, string, or Date, optional). Given to new Date(date) as date, so when null or undefined, defaults to the current date. Dates are centered in the footer line of the displayed page.

options.version

Version of page (string, optional). Versions are positioned at the left of the footer line of the displayed page (or at the left on even pages and at the right on odd pages if double-sided printing is active).

options.manual

Manual of page (string, optional). Manuals are centered in the header line of the displayed page.

Types

This package is fully typed with TypeScript. It exports an Options type, which specifies the interface of the accepted options.

Compatibility

Projects maintained by the unified collective are compatible with all maintained versions of Node.js. As of now, that is Node.js 12.20+, 14.14+, and 16.0+. Our projects sometimes work with older versions, but this is not guaranteed.

This plugin works with unified version 6+ and remark version 7+.

Security

Use of remark-man does not involve rehype (hast) or user content so there are no openings for cross-site scripting (XSS) attacks.

Related

• remark-rehype — turn markdown into HTML to support rehype
• remark-stringify — compile markdown
• remark-vdom — compile markdown to VDOM

Contribute

See contributing.md in remarkjs/.github for ways to get started. See support.md for ways to get help.

This project has a code of conduct. By interacting with this repository, organization, or community you agree to abide by its terms.

License

MIT © Titus Wormer