Mmark: a powerful markdown processor in Go geared towards the IETF
Go Other
Clone or download
Pull request Compare This branch is 888 commits ahead, 158 commits behind russross:master.
Permalink
Failed to load latest commit information.
logo Add logo Oct 11, 2015
mmark Up version Mar 5, 2016
rfc more gotchas May 9, 2016
.gitignore Fix codeblock prefix Feb 22, 2016
.rel.sh remove these from the release dist Mar 2, 2016
.travis.yml Only test go 1.7 Sep 27, 2016
CONVERSION_RFC7328.md tweaks to conversion doc Oct 3, 2015
COPYRIGHT Add in blackfriday license Sep 19, 2015
LICENSE Add in blackfriday license Sep 19, 2015
Makefile Better toplevel Makefile Sep 27, 2016
Makefile.release Fix release Jul 10, 2017
README.md Fix small typo in README (#117) Aug 31, 2017
block.go Only check for TOML block at the start May 14, 2016
block_test.go Add Task Lists May 7, 2016
cm_test.go Patch blackfriday's fix for issue 122 in Oct 31, 2015
code.go Allow address specification in file include (#77) May 7, 2016
common_render.go split of prefix code and fix it Feb 22, 2016
doc_test.go Fix tests and make notes work Dec 8, 2015
html.go Add Task Lists May 7, 2016
ial.go squash last bug Mar 4, 2016
ial_test.go Add IAL test and fix doc Mar 2, 2016
inline.go pr #266 from blackfriday May 25, 2016
inline_test.go Update bibliography links to secure ones (#100) Nov 3, 2016
issue_test.go Add RFC7511 May 9, 2016
log.go Backout "smart" unicode functions Feb 27, 2016
markdown.go Release 1.3.6 Jul 10, 2017
quote.go Stringify the ial on per renderer basis Feb 29, 2016
rfc7328.go Small fixes and gofmt -s -w May 6, 2016
rfc7328_test.go Add conversion tests Sep 27, 2015
smartypants.go Integrate smartypants.go from blackfriday, adjust tests. Feb 24, 2016
table_test.go update docs Oct 10, 2015
toml.go Allow number attribute Apr 7, 2017
xml2rfc.go titleblock: *use* the role attribute (#106) May 19, 2017
xml2rfcv2.go Allow number attribute Apr 7, 2017
xml2rfcv3.go Allow number attribute Apr 7, 2017
xml2rfcv3.rnc add comment Sep 10, 2015

README.md

Mmark

Mmark is a powerful markdown processor written in Go geared towards writing IETF documents. It is, however, also suited for writing books and other technical documentation.

Further documentation can be found at my site. A complete syntax document can be found here.

With Mmark you can write RFCs using markdown. Mmark (written in Go) provides an advanced markdown dialect that processes a (single) file to produce internet-drafts in XML format. Internet-drafts written in mmark can produce xml2rfc v2, xml2rfc v3 and HTML5 output.

It also allows for writing large documents such as technical books, like my Learning Go book. Sample text output of this book (when rendered as an I-D) can be found here. It is not perfect due to limitations in xml2rfc version 2. Fully rendered HTML version can be found here.

Mmark is a fork of blackfriday which is a Markdown processor implemented in Go. It supports a number of extensions, inspired by Leanpub, kramdown and Asciidoc, that allows for large documents to be written.

Example documents written in Mmark can be found in the rfc/ directory.

Mmark adds the following syntax elements to black friday:

  • TOML titleblock.
  • Including other files.
  • More enumerated lists and task-lists.
  • Table and codeblock captions.
  • Quote attribution (quote "captions").
  • Table footers, header and block tables.
  • Subfigures.
  • Inline Attribute Lists.
  • Indices.
  • Citations.
  • Abstract/Preface/Notes sections.
  • Parts.
  • Asides.
  • Main-, middle- and backmatter divisions.
  • Math support.
  • Example lists.
  • HTML Comment parsing.
  • BCP14 (RFC2119) keyword detection.
  • Include raw XML references.
  • Abbreviations.
  • Super- and subscript.
  • Callouts in code blocks.

Usage

In the mmark subdirectory you can build the mmark tool:

% cd mmark
% go build
% ./mmark -version
1.3.4

To output v2 xml just give it a markdown file and:

% ./mmark/mmark -xml2 -page mmark2rfc.md

Making a draft in text form:

% ./mmark/mmark -xml2 -page mmark2rfc.md > x.xml \
&& xml2rfc --text x.xml \
&& rm x.xml && mv x.txt mmark2rfc.txt

Outputting v3 xml is done with the -xml switch. There is not yet a processor for this XML, but you should be able to validate the resulting XML against the schema from the xml2rfc v3 draft. I'm trying to stay current with the latest draft for the V3 spec: https://tools.ietf.org/html/draft-iab-xml2rfc-03

Running from a Docker Container

To use mmark and xml2rfc without installing and configuring the separate software packages and dependencies, you can also use mmark via a Docker container. You can use https://github.com/paulej/rfctools to build a Docker image or you can use the one already created and available in Docker Hub (https://hub.docker.com/r/paulej/rfctools/).

To use Docker, you invoke commands like this:

% docker run --rm paulej/rfctools mmark -version
1.3.4

To output a v2 XML file as demonstrated in the previous section, use this command:

% docker run --rm -v $(pwd):/rfc paulej/rfctools mmark -xml2 -page mmark2rfc.md

Making a draft in text form:

% docker run --rm -v $(pwd):/rfc paulej/rfctools mmark -xml2 -page mmark2rfc.md >x.xml \
&& docker run --rm -v $(pwd):/rfc -v $HOME/.cache/xml2rfc:/var/cache/xml2rfc \
--user=$(id -u):$(id -g) paulej/rfctools xml2rfc --text x.xml \
&& rm x.xml && mv x.xml mmark2rfc.txt

The docker container expects source files to be stored in /rfc, so the above command maps the current directory to /rfc. Likewise, xml2rfc will attempt to write cache files to /var/cache/xml2rfc, so the above command maps the user's cache directory in the container.

Note also that the xml2rfc program will write an output file that will be owned by "root". To prevent that (and the cache files) from being owned by root, we instruct docker to run using the user's default user ID and group ID via the --user switch.

There is a script available called "md2rfc" simplifies the above to this:

% docker run --rm -v $(pwd):/rfc -v $HOME/.cache/xml2rfc:/var/cache/xml2rfc \
--user=$(id -u):$(id -g) paulej/rfctools mmark2rfc.md

Still appreciating that is a lot to type, there is an example directory in the https://github.com/paulej/rfctools repository that contains a Makefile. Place your .md file in a directory along with that Makefile and just type "make" to produce the .txt file.

Syntax

See the syntax document on all syntax elements that are supported by Mmark.