remark-man
remark plugin to compile markdown to man pages.
Contents
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 rehyperemark-stringify— compile markdownremark-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.