mmarkdown/mmark

Mmark: a powerful markdown processor in Go geared towards the IETF

title	date	aliases
About	2018-07-22 14:05:51 +0100	/about/

Mmark is a powerful markdown processor written in Go, geared towards writing IETF documents. It is, however, also suited for writing complete books and other technical documentation, like the Learning Go book (mmark source, and I-D text output).

Also see this repository on how to write RFC using Markdown.

It provides an advanced markdown dialect that processes file(s) to produce internet-drafts in XML RFC 7991 format. Mmark can produce xml2rfc (aforementioned RFC 7991), HTML5 output, and manual pages.

Example RFCs in Mmark format can be found in the Github repository.

Mmark uses gomarkdown which is a fork of blackfriday. See its README.md for more documentation.

Syntax

Mmark's syntax and the extra features compared to plain Markdown are detailed in syntax.md.

Mmark adds the following syntax elements to gomarkdown/markdown:

• (Extended) title block.
• Special sections.
• Including other files with the option to specify line ranges, regular expressions and/or prefix each line with a string. By default only files on the same level, or below are allowed to be included (see the -unsafe flag).
• Document divisions.
• Captions for code, tables and quotes
• Asides.
• Figures and Subfigures - bundle (sub)figures into a larger figure.
• Block Level Attributes that allow to specify attributes, classes and IDs for elements.
• Indices to mark an item (and/or a subitem) to be referenced in the document index.
• Citations and adding XML References
• In document cross references, short form of referencing a section in the document.
• Super- and Subscript.
• Callouts in code and text.
• BCP14 (RFC 2119) keyword detection.

Usage

You can download a binary or optionally build mmark your self. You'll need a working Go environment, then check out the code and:

% go get && go build
% ./mmark -version
2.0.0

To output XML2RFC v3 xml just give it a markdown file and:

% ./mmark rfc/3514.md

Making a draft in text form (v3 output)

% ./mmark rfc/3514.md > x.xml
% xml2rfc --v3 --text x.xml

Outputting HTML5 is done with the -html switch.

Files edited under Windows/Mac and using Windows style will be converted into Unix style line ending before parsing. Any output from mmark will use Unix line endings.

Note there are no wrong markdown documents, so mmark will only warn about things that are not right. This may result in invalid XML. Any warning from mmark are send to standard error, to see and check for those you can discard standard output to just leave standard error: ./mmark rfc/3515.md > /dev/null.

Example RFC

The rfc/ directory contains a couple of example RFCs that can be build via v3 tool chain. The build the text files, just run:

cd rfc
make txt

Official RFCs are in rfc/orig (so you can compare the text output from mmark).

Also See

Kramdown-rfc2629 is another tool to process markdown and output XML2RFC XML.

See Syntax.md for a primer on how to use the Markdown syntax to create IETF documents.