Mmark on Miek Gieben

Learning Go

Tue, 13 Aug 2019 07:39:00 +0000

Learning Go is a book that teaches you Go. It includes exercises (and solutions) to help put your new knowledge to the test.

Mmark Updates

Mon, 09 May 2016 18:54:21 +0100

Recent bug reports prompted some Mmark development (guess I am into bug-driven development). New releases can be found on Github. Anyway Mmark saw some bug fixes and new features:

A feature/pull request from blackfriday got merged, meaning that two different lists are not merged into one:

* A
* B

1. One
2. Two

Is now correctly seen as two different lists.

Further more a <br/> is converted to a <vspace/> in the XML output. This is especially useful when you want a vertical space after a definition term. See rfc/rfc7511.md for an example on how to use this.

Mmark Syntax Document

Sat, 05 Mar 2016 11:13:21 +0000

The canonical version of this document is the version in the Github Wiki.

Mmark Syntax

All syntax elements should be described. Please open an issue or PR if there is something you want to improve here, or even better, edit the doc!

This document describes all the syntax elements that can be used in Mmark. Mmark’s syntax is based on the “standard” Markdown syntax.

It adds numerous enhancements to make it suitable for writing (IETF) Internet Drafts and even complete books. It ~~steals~~ borrows syntax elements from pandoc, kramdown, leanpub, asciidoc, PHP markdown extra and Scholarly markdown.

Inline Attribute Lists

Tue, 01 Mar 2016 14:14:24 +0000

Mmark is a powerful markdown parser.

With Inline Attribute Lists (IALs) you can add extra information to block elements, think of extra classes, attributes or an ID. In Mmark these have the syntax: {#id .class attr="key"}. And should be specified before a block level element.

These will mostly be backend specific, i.e. a {color="blue"} might do something in HTML5 output, but does nothing in the XML v2 output. Worse yet; the XML might not validate anymore. Mmark try to help here by white listing the allowed attributes for an element (this happens in each renderer and is currently a work in progress).

Callouts in Figures in Mmark

Sun, 27 Sep 2015 14:02:00 +0000

The use of callouts in Mmark came from Asciidoc, they are “… a mechanism for annotating verbatim text”. In mmark they work like this.

In a codeblocks you can use <1>, or <2>, etc. to create a callout. After the codeblock/figure you can reference it. An example:

    Code  <1>
    More  <1>
    Not a callout \<3>

As you can see in <1> but not in \<1>. There is no <3>.

This will be rendered as:

Lists in lists with style

Thu, 24 Sep 2015 11:56:00 +0000

Mmark is a markdown dialect for writing RFCs (or books!). The main reason it exists is because the IETF is developing a new XML format (version 3) for writing RFCs. This new format is way more powerful, so sadly Pandoc2rfc does not cut it anymore.

Right now mmark fully supports writing RFCs in XML2RFC version 2, but anything written can also be converted to the (work-in-progress) XML2RFC version 3 format. In a series of blog posts I will detail some of the features, such as list styling while remaining upwards compatible.

Learning Go in Markdown

Sat, 09 May 2015 07:39:00 +0000

The original Learning Go is written in LaTeX. With LaTeX you get beautiful (PDF) output, but there are a few problems. Most notably I consider LaTeX an output format: it is hard to convert it into something else. Markdown offers much more flexibility in that regard. The downside of markdown is that is not powerful enough to typeset a book. To fix this I forked BlackFriday extended it and renamed it Mmark (These are all written in Golang).

Markdown for XML2RFC v3 - Update

Thu, 18 Dec 2014 22:46:00 +0000

And another update (2015-01-12)

This is a follow up the previous article about using markdown for XML2RFC. The syntax has been changed and more features have been implement. And my blackfriday fork has been renamed mmark.

See this document for an up to date syntax of mmark. A short summery will be given here.

New features are:

Include raw XML references
Allow HTML comments to be converted to crefs
Abbreviations (https://michelf.ca/projects/php-markdown/extra/#abbr), this is not used in XML2RFC but seems a relatively standard markdown extension
Example lists (http://johnmacfarlane.net/pandoc/README.html#numbered-example-lists)
Quote attribution

Also the possibility to convert pandoc2rfc documents to mmark has been added (as a quick and dirty perl script + pandoc!):

Markdown for XML2RFC v3

Thu, 27 Nov 2014 22:50:00 +0000

Or… how to write Markdown to generate XML that is valid XML2RFC v3. These are some assorted notes and ideas

Goal:

Self contained file with all information to generate a complete I-D;
CommonMarkdown, with some extension.

I’m working on implementing these ideas in blackfriday. The following has already been implemented:

Abstract;
Citation;
Document divisions;
Index;
File inclusion;
Extra attributes (kramdown’s IAL.) (work-in-progress).

Document meta data

In TOML - much easier than YAML for instance, lines are starting with %. We don’t need to specify the citations here because: