Skip to content

Latest commit

 

History

History
267 lines (179 loc) · 6.97 KB

readme.md

File metadata and controls

267 lines (179 loc) · 6.97 KB
Raw

remark-man

Build Coverage Downloads Size Sponsors Backers Chat

remark plugin to turn markdown to man pages.

Contents

What is this?

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

It adds a compiler for unified that turns the final markdown (mdast) syntax tree into roff/groff/troff (the format used for man pages).

When should I use this?

Use this when you know a bit about remark and ASTs and need mang pages. 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 16+), install with npm:

npm install remark-man

In Deno with esm.sh:

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

In browsers with esm.sh:

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

Use

Say we have the following file example.md:

# ls(1) -- list directory contents

## SYNOPSIS

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

…and a module example.js:

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

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

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

…then running node example.js generates an example.1 file, which contains:

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

Running man ./example.1 opens that in a manual viewer, which interprets it.

API

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

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

Turn markdown into a man page.

Parameters
  • options (Options, optional) — configuration
Returns

Transform (Transformer).

Options

Configuration (TypeScript type).

Fields
  • date (Date | number | string, default: new Date()) — date of page; given to new Date(x); dates are centered in the footer line of the displayed page
  • description (string, optional) — description of page; inferried from the main heading: # hello-world(7) -- Two common words defaults to 'Two common words'
  • manual (string, optional) — manual of page; manuals are centered in the header line of the displayed page
  • name (string, optional) — title of the page; inferried from the main heading (# hello-world(7) defaults to 'hello-world') or the file name (hello-world.1.md defaults to 'hello-world')
  • section (number, optional) — manual section of page; inferred from the main heading (# hello-world(7) defaults to 7) or the file name (hello-world.1.md defaults to 1)
  • version (string, optional) — version of page; versions are positioned at the left of the footer line of the displayed page

Types

This package is fully typed with TypeScript. It exports the additional type Options.

Compatibility

Projects maintained by the unified collective are compatible with maintained versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of Node. This means we try to keep the current release line, remark-man@^9, compatible with Node.js 16.

This plugin works with unified version 11+ and remark version 15+.

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

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