• Home
  • History
  • Annotate
Name Date Size #Lines LOC

..03-May-2022-

logo/H03-May-2022-

mmark/H10-Jul-2017-

rfc/H03-May-2022-

.gitignoreH A D10-Jul-2017137

.rel.shH A D10-Jul-2017730

.travis.ymlH A D10-Jul-2017149

CONVERSION_RFC7328.mdH A D10-Jul-20172.7 KiB

COPYRIGHTH A D10-Jul-2017210

LICENSEH A D10-Jul-20171.4 KiB

MakefileH A D10-Jul-2017100

Makefile.releaseH A D10-Jul-20172 KiB

README.mdH A D10-Jul-20174.8 KiB

block.goH A D10-Jul-201751 KiB

block_test.goH A D10-Jul-201753.2 KiB

cm_test.goH A D10-Jul-20172.5 KiB

code.goH A D10-Jul-20176.9 KiB

common_render.goH A D10-Jul-2017499

doc_test.goH A D10-Jul-20171.6 KiB

html.goH A D10-Jul-201732.9 KiB

ial.goH A D10-Jul-20174.8 KiB

ial_test.goH A D10-Jul-2017364

inline.goH A D10-Jul-201733.1 KiB

inline_test.goH A D10-Jul-201739.1 KiB

issue_test.goH A D10-Jul-20172 KiB

log.goH A D10-Jul-2017212

markdown.goH A D10-Jul-201731.1 KiB

quote.goH A D10-Jul-20174.5 KiB

rfc7328.goH A D10-Jul-20172.3 KiB

rfc7328_test.goH A D10-Jul-20172.2 KiB

smartypants.goH A D10-Jul-20179.8 KiB

table_test.goH A D10-Jul-20171.2 KiB

toml.goH A D10-Jul-20172.2 KiB

xml2rfc.goH A D10-Jul-20178.2 KiB

xml2rfcv2.goH A D10-Jul-201721 KiB

xml2rfcv3.goH A D10-Jul-201720.1 KiB

xml2rfcv3.rncH A D10-Jul-201720.5 KiB

README.md

1# Mmark
2
3Mmark is a powerful markdown processor Go geared towards writing IETF documents. It is, however,
4also suited for writing books and other technical documentation.
5
6Further documentation can be [found at my site](https://miek.nl/tags/mmark/). A complete syntax
7document [can be found here](https://github.com/miekg/mmark/wiki/Syntax).
8
9With Mmark your can write RFCs using markdown. Mmark (written in Go) provides an advanced markdown
10dialect that processes a (single) file to produce internet-drafts in XML format. Internet-drafts
11written in mmark can produce xml2rfc v2, xml2rfc v3 and HTML5 output.
12
13It also allows for writing large documents such as technical books, like my [Learning Go
14book](https://github.com/miekg/learninggo). Sample text output of this book (when rendered as an
15I-D) can [be found
16here](https://gist.githubusercontent.com/miekg/0251f3e28652fa603a51/raw/7e0a7028506f7d2948e4ad3091f533711bf5f2a4/learninggo.txt).
17It is not perfect due to limitations in xml2rfc version 2. Fully rendered HTML version [can be found
18here](http://miek.nl/go).
19
20Mmark is a fork of blackfriday which is a [Markdown][1] processor implemented in [Go][2]. It
21supports a number of extensions, inspired by Leanpub, kramdown and Asciidoc, that allows for large
22documents to be written.
23
24Example documents written in Mmark can be found in the `rfc/` directory.
25
26Mmark adds the following syntax elements to [black friday](https://github.com/russross/blackfriday/blob/master/README.md):
27
28* TOML titleblock.
29* Including other files.
30* More enumerated lists and task-lists.
31* Table and codeblock captions.
32* Quote attribution (quote "captions").
33* Table footers, header and block tables.
34* Subfigures.
35* Inline Attribute Lists.
36* Indices.
37* Citations.
38* Abstract/Preface/Notes sections.
39* Parts.
40* Asides.
41* Main-, middle- and backmatter divisions.
42* Math support.
43* Example lists.
44* HTML Comment parsing.
45* BCP14 (RFC2119) keyword detection.
46* Include raw XML references.
47* Abbreviations.
48* Super- and subscript.
49* Callouts in code blocks.
50
51## Usage
52
53In the mmark subdirectory you can build the mmark tool:
54
55    % cd mmark
56    % go build
57    % ./mmark -version
58    1.3.4
59
60To output v2 xml just give it a markdown file and:
61
62    % ./mmark/mmark -xml2 -page mmark2rfc.md
63
64Making a draft in text form:
65
66    % ./mmark/mmark -xml2 -page mmark2rfc.md > x.xml \
67    && xml2rfc --text x.xml \
68    && rm x.xml && mv x.txt mmark2rfc.txt
69
70Outputting v3 xml is done with the `-xml` switch. There is not yet a processor for this XML, but you
71should be able to validate the resulting XML against the schema from the xml2rfc v3 draft. I'm
72trying to stay current with the latest draft for the V3 spec:
73<https://tools.ietf.org/html/draft-iab-xml2rfc-03>
74
75## Running from a Docker Container
76
77To use mmark and xml2rfc without installing and configuring the separate software packages and
78dependencies, you can also use mmark via a Docker container.  You can use
79https://github.com/paulej/rfctools to build a Docker image or you can use the one already
80created and available in Docker Hub (https://hub.docker.com/r/paulej/rfctools/).
81
82To use Docker, you invoke commands like this:
83
84    % docker run --rm paulej/rfctools mmark -version
85    1.3.4
86
87To output a v2 XML file as demonstrated in the previous section, use this command:
88
89    % docker run --rm -v $(pwd):/rfc paulej/rfctools mmark -xml2 -page mmark2rfc.md
90
91Making a draft in text form:
92
93    % docker run --rm -v $(pwd):/rfc paulej/rfctools mmark -xml2 -page mmark2rfc.md >x.xml \
94    && docker run --rm -v $(pwd):/rfc -v $HOME/.cache/xml2rfc:/var/cache/xml2rfc \
95    --user=$(id -u):$(id -g) paulej/rfctools xml2rfc --text x.xml \
96    && rm x.xml && mv x.xml mmark2rfc.txt
97
98The docker container expects source files to be stored in /rfc, so the above command maps
99the current directory to /rfc.  Likewise, xml2rfc will attempt to write cache files to
100/var/cache/xml2rfc, so the above command maps the user's cache directory in the container.
101
102Note also that the xml2rfc program will write an output file that will be owned by "root".
103To prevent that (and the cache files) from being owned by root, we instruct docker to run
104using the user's default user ID and group ID via the --user switch.
105
106There is a script available called "md2rfc" simplifies the above to this:
107
108    % docker run --rm -v $(pwd):/rfc -v $HOME/.cache/xml2rfc:/var/cache/xml2rfc \
109    --user=$(id -u):$(id -g) paulej/rfctools mmark2rfc.md
110
111Still appreciating that is a lot to type, there is an example directory in the
112https://github.com/paulej/rfctools repository that contains a Makefile.  Place your .md file
113in a directory along with that Makefile and just type "make" to produce the .txt file.
114
115## Syntax
116
117See the [syntax](https://github.com/miekg/mmark/wiki/Syntax) document on all syntax elements that
118are supported by Mmark.
119
120[1]: https://daringfireball.net/projects/markdown/ "Markdown"
121[2]: https://golang.org/ "Go Language"
122