/kramdown-man

Allows you to write man pages in pure markdown.

Primary LanguageRubyMIT LicenseMIT

kramdown-man

CI Code Climate Gem Version

Description

Allows you to write man pages for commands in pure Markdown and convert them to roff using Kramdown.

Features

  • Converts markdown to roff:
    • Supports codespans, emphasis, and strong fonts.
    • Supports normal and tagged paragraphs.
    • Supports codeblocks and blockquotes.
    • Supports bullet, numbered, and definition lists.
    • Supports multi-paragraph list items and blockquotes.
    • Supports converting [foo-bar](foo-bar.1.md) and [bash](man:bash(1)) links into SEE ALSO man page references.
  • Provides a handy kramdown-man command for converting or previewing markdown man pages.
  • Provides a rake task for converting man/*.md into man pages.
  • Uses the pure-Ruby Kramdown markdown parser.
  • Supports Ruby 3.x, JRuby, and TruffleRuby.

Synopsis

usage: kramdown-man [options] MARKDOWN_FILE
    -o, --output FILE                Write the man page output to the file
    -V, --version                    Print the version
    -h, --help                       Print the help output

Examples:
    kramdown-man -o man/myprogram.1 man/myprogram.1.md
    kramdown-man man/myprogram.1.md

Render a man page from markdown:

kramdown-man -o man/myprogram.1 man/myprogram.1.md

Preview the rendered man page:

kramdown-man man/myprogram.1.md

Examples

Render a man page from a markdown file:

require 'kramdown/man'

doc = Kramdown::Document.new(File.read('man/kramdown-man.1.md'))
File.write('man/kramdown-man.1',doc.to_man)

system 'man', 'man/kramdown-man.1'

Rake Task

Define a man and file tasks which render all *.md files within the man/ directory:

require 'kramdown/man/task'
Kramdown::Man::Task.new

Then you can generate man pages for all *.md in the man/ directory:

$ rake man

Syntax

Code

`code`

code

Emphasis

*emphasis*

emphasis

Strong

**strong**

strong

Paragraph

Normal paragraph.

Normal paragraph.

Usage String

`command` [`--foo`] **FILE**

command [--foo] FILE

Argument Definitions

*ARG*
: Description here.

ARG : Description here.

Option Definitions

`-o`, `--option` *VALUE*
: Description here.

-o, --option VALUE : Description here.

Links

[website](http://example.com/)

website

Man Pages

Link to other man pages in a project:

[kramdown-man](kramdown-man.1.md)

kramdown-man

Link to other system man page:

[bash](man:bash(1))

bash

Note: only works on firefox on Linux.

Email Addresses

Email <bob@example.com>

Email bob@example.com

Lists

* one
* two
* three
  • one
  • two
  • three

Numbered Lists

1. one
2. two
3. three
  1. one
  2. two
  3. three

Definition Lists

ex·am·ple
: a thing characteristic of its kind or illustrating a general rule.

: a person or thing regarded in terms of their fitness to be imitated or the likelihood of their being imitated.

ex·am·ple : a thing characteristic of its kind or illustrating a general rule.

: a person or thing regarded in terms of their fitness to be imitated or the likelihood of their being imitated.

Blockquotes

> Perfection is achieved, not when there is nothing more to add, but when there is nothing left to take away.
>
> --Antoine de Saint-Exupéry

Perfection is achieved, not when there is nothing more to add, but when there is nothing left to take away.

--Antoine de Saint-Exupéry

Code Blocks

    #include <stdio.h>

    int main()
    {
        printf("hello world\n");
        return 0;
    }
#include <stdio.h>

int main()
{
    printf("hello world\n");
    return 0;
}

Code Fences

```
puts "hello world"
```

puts "hello world"

Requirements

Install

gem install kramdown-man

Alternatives

Copyright

Copyright (c) 2013-2023 Hal Brodigan

See {file:LICENSE.txt} for details.