remark-man
remark plugin to compile Markdown to man pages.
- Great unicode support
- Name, section, and description detection
- Nested block quotes and lists
- Tables
- and much more
Note!
This plugin is ready for the new parser in remark (micromark
, see remarkjs/remark#536
). No change is needed: it works exactly the same now as it did before!
Install
npm:
npm install remark-man
Use
Say we have the following file, example.md
:
# ls(1) -- list directory contents
## SYNOPSIS
`ls` \[`-ABCFGHLOPRSTUW@abcdefghiklmnopqrstuwx1`] \[*file* *...*]
And our script, example.js
, looks as follows:
var vfile = require('to-vfile')
var unified = require('unified')
var markdown = require('remark-parse')
var man = require('remark-man')
unified()
.use(markdown)
.use(man)
.process(vfile.readSync('example.md'), function(err, file) {
if (err) throw err
file.extname = '.1'
vfile.writeSync(file)
})
Now, running node example
and cat example.1
yields:
.TH "LS" "1" "June 2019" "" ""
.SH "NAME"
\fBls\fR - list directory contents
.SH "SYNOPSIS"
.P
\fBls\fR \[lB]\fB-ABCFGHLOPRSTUW@abcdefghiklmnopqrstuwx1\fR\[rB] \[lB]\fIfile\fR \fI...\fR\[rB]
Now, that in my opinion isn’t very readable, but that’s roff/groff/troff. 😉
To properly view that man page, use something like this: man ./example.1
.
remark().use(man[, options])
Plugin to compile Markdown to man pages.
options
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
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.
options.commonmark
Parsing mode (boolean
, default: false
). The default behavior is to prefer the last duplicate definition. Set to true
to prefer the first when duplicate definitions are found.
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-react
— Compile to Reactremark-vdom
— Compile to VDOMremark-html
— Compile to HTMLremark-rehype
— Properly transform to HTML
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.