Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/postmodern/kramdown-man
Allows you to write man pages in pure markdown.
https://github.com/postmodern/kramdown-man
man-page markdown markdown-converter roff
Last synced: about 20 hours ago
JSON representation
Allows you to write man pages in pure markdown.
- Host: GitHub
- URL: https://github.com/postmodern/kramdown-man
- Owner: postmodern
- License: mit
- Created: 2013-04-28T09:25:38.000Z (over 11 years ago)
- Default Branch: main
- Last Pushed: 2023-12-28T04:55:05.000Z (about 1 year ago)
- Last Synced: 2025-01-03T10:09:09.155Z (8 days ago)
- Topics: man-page, markdown, markdown-converter, roff
- Language: Ruby
- Homepage:
- Size: 189 KB
- Stars: 85
- Watchers: 4
- Forks: 4
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Changelog: ChangeLog.md
- License: LICENSE.txt
Awesome Lists containing this project
README
# kramdown-man
[![CI](https://github.com/postmodern/kramdown-man/actions/workflows/ruby.yml/badge.svg)](https://github.com/postmodern/kramdown-man/actions/workflows/ruby.yml)
[![Code Climate](https://codeclimate.com/github/postmodern/kramdown-man.svg)](https://codeclimate.com/github/postmodern/kramdown-man)
[![Gem Version](https://badge.fury.io/rb/kramdown-man.svg)](https://badge.fury.io/rb/kramdown-man)* [Homepage](https://github.com/postmodern/kramdown-man#readme)
* [Issues](https://github.com/postmodern/kramdown-man/issues)
* [Documentation](https://rubydoc.info/gems/kramdown-man)## Description
Allows you to write man pages for commands in pure Markdown and convert them to
roff using [Kramdown][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][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 outputExamples:
kramdown-man -o man/myprogram.1 man/myprogram.1.md
kramdown-man man/myprogram.1.md```
Render a man page from markdown:
```shell
kramdown-man -o man/myprogram.1 man/myprogram.1.md
```Preview the rendered man page:
```shell
kramdown-man man/myprogram.1.md
```## Examples
Render a man page from a markdown file:
```ruby
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:```ruby
require 'kramdown/man/task'
Kramdown::Man::Task.new
```Then you can generate man pages for all `*.md` in the `man/` directory:
```shell
$ rake man
```## Syntax
### Code
```markdown
`code`
````code`
### Emphasis
```markdown
*emphasis*
```*emphasis*
### Strong
```markdown
**strong**
```**strong**
### Paragraph
```markdown
Normal paragraph.
```Normal paragraph.
#### Usage String
```markdown
`command` [`--foo`] **FILE**
````command` [`--foo`] **FILE**
#### Argument Definitions
```markdown
*ARG*
: Description here.
```*ARG*
: Description here.#### Option Definitions
```markdown
`-o`, `--option` *VALUE*
: Description here.
````-o`, `--option` *VALUE*
: Description here.### Links
```markdown
[website](http://example.com/)
```[website](http://example.com/)
#### Man Pages
Link to other man pages in a project:
```markdown
[kramdown-man](kramdown-man.1.md)
```[kramdown-man](https://github.com/postmodern/kramdown-man/blob/main/man/kramdown-man.1.md)
Link to other system man page:
```markdown
[bash](man:bash(1))
```[bash](man:bash(1))
**Note:** only works on [firefox] on Linux.
[firefox]: https://www.mozilla.org/en-US/firefox/new/
#### Email Addresses
```markdown
```### Lists
```markdown
* one
* two
* three
```* one
* two
* three#### Numbered Lists
```markdown
1. one
2. two
3. three
```
1. one
2. two
3. three#### Definition Lists
```markdown
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
```markdown
> 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
```markdown
#includeint main()
{
printf("hello world\n");
return 0;
}
```#include
int main()
{
printf("hello world\n");
return 0;
}#### Code Fences
```
puts "hello world"
``````
puts "hello world"
```## Requirements
* [kramdown] ~> 2.0
## Install
```shell
gem install kramdown-man
```## Alternatives
* [Redcarpet::Render::ManPage](https://rubydoc.info/gems/redcarpet/Redcarpet/Render/ManPage)
* [ronn](https://github.com/rtomayko/ronn#readme)
* [md2man](https://github.com/sunaku/md2man#readme)## Copyright
Copyright (c) 2013-2023 Hal Brodigan
See {file:LICENSE.txt} for details.
[kramdown]: https://kramdown.gettalong.org/
[roff]: https://en.wikipedia.org/wiki/Roff_(software)[Ruby]: https://www.ruby-lang.org/
[JRuby]: https://jruby.org/
[TruffleRuby]: https://github.com/oracle/truffleruby#readme