https://github.com/danielbayley/homebrew-pandoc-mandown
Pandoc template and filters for converting markdown to man pages.
https://github.com/danielbayley/homebrew-pandoc-mandown
gfm lua manpages markdown pandoc pandoc-filter template
Last synced: 5 months ago
JSON representation
Pandoc template and filters for converting markdown to man pages.
- Host: GitHub
- URL: https://github.com/danielbayley/homebrew-pandoc-mandown
- Owner: danielbayley
- License: mit
- Created: 2018-11-11T19:19:53.000Z (almost 8 years ago)
- Default Branch: master
- Last Pushed: 2019-01-22T04:25:30.000Z (over 7 years ago)
- Last Synced: 2025-04-06T06:28:11.530Z (over 1 year ago)
- Topics: gfm, lua, manpages, markdown, pandoc, pandoc-filter, template
- Language: Lua
- Homepage: https://pandoc.org/lua-filters
- Size: 4.88 KB
- Stars: 1
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE.md
Awesome Lists containing this project
README
[man]down
=========
_[Pandoc]_ [template] and [filter]s for converting markdown to [`man` page][man]s.
[Filter]s
---------
Filters can be specified individually with `--lua-filter filter`, but the default _[mandown]_ filter is recommended to apply all of the filters, in appropriate order:
| Filter `.lua` | Description |
|:-------------------------|:---------------------------------------------------------------|
| [mandown] | Applies all filters in appropriate order. |
| [metadata][metadata.lua] | Extract the below [metadata](#metadata) as Pandoc [variable]s. |
| [code-bold] | Render `inline` and [fenced] code blocks as **bold**. |
| [refs] | Add [man page][man] section `(n)` references to applicable `command`s, and ensure a `SEE ALSO` section listing them. |
| [links] | Underline `http` links, and ensure a `SEE ALSO` section listing all reference links. |
| [headings] | UPPERCASE, [replace], and set the correct `##` level for headings. |
### [Metadata]
[`--metadata`]/[`--variable`][variable]s can be passed directly on the command line, else are extracted from the markdown source as follows:
| [Variable] | Source |
|:----------------------|:--------------------------------------------------------------------------|
| [`author`][variable] | Extract [`GIT_AUTHOR`] details from the latest [GitHub Release] `commit`. |
| [`date`][variable] | Latest [GitHub Release] date. |
| [`title`][variable] | The `command` first described in the `SYNOPSIS` section. |
| [`section`][`header`] | Any `(n)` immediately following `command`, else `(1)`. |
| [`header`] | Taken from the main `h1` header, and stripped of any formatting. |
| [`footer`][`header`] | [Semantic version] tag `v0.0.0` of the latest [GitHub Release]. |
Example
-------
~~~ sh
pandoc --from gfm src.md --lua-filter mandown --to man --template mandown > bin.1
~~~
Install
-------
easily with _[Homebrew]_:
~~~ sh
brew tap danielbayley/pandoc
brew install pandoc pandoc-mandown
~~~
then, in your _[formula]_:
~~~ rb
depends_on "pandoc" #=> :build
depends_on "danielbayley/pandoc/pandoc-mandown" #=> :build
~~~
License
-------
[MIT] © [Daniel Bayley]
[MIT]: LICENSE.md
[Daniel Bayley]: https://github.com/danielbayley
[pandoc]: https://pandoc.org
[template]: https://pandoc.org/MANUAL#templates
[filter]: https://pandoc.org/lua-filters
[metadata]: https://pandoc.org/MANUAL.html#metadata-blocks
[`--metadata`]: https://pandoc.org/MANUAL.html#templates
[variable]: https://pandoc.org/MANUAL.html#variables-set-by-pandoc
[`header`]: https://pandoc.org/MANUAL.html#variables-for-man-pages
[mandown]: filters/mandown.lua
[metadata.lua]: filters/metadata.lua
[code-bold]: filters/code-bold.lua
[refs]: filters/refs.lua
[links]: filters/links.lua
[headings]: filters/headings.lua
[replace]: libexec/aliases.lua
[man]: https://en.wikipedia.org/wiki/Man_page
[`GIT_AUTHOR`]: https://git-scm.com/book/en/v2/Git-Internals-Environment-Variables#_committing
[fenced]: https://help.github.com/articles/creating-and-highlighting-code-blocks/#fenced-code-blocks
[github release]: https://help.github.com/articles/about-releases
[semantic version]: https://semver.org
[homebrew]: https://brew.sh
[formula]: https://docs.brew.sh/Formula-Cookbook