Markdown on Miek Gieben

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).

Subfigures in mmark

Sat, 03 Oct 2015 13:24:00 +0000

For XML2RFC version 3 there is a new extended figure element, namely: it can contain multiple <artwork> or <sourcecode> (new in v3) elements. This in turn meant that mmark needed some way to signal “these artworks belong together”. Now Scholarly markdown has a syntax for this. It uses a special section syntax and all images in that section become subfigures of a larger figure. Disadvantage of this syntax is that it can not be used in lists. Hence mmark uses a quote like solution, just like asides (A>), but for figures: we prefix the entire paragraph with F> .

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:

Vim live preview (sort of)

Wed, 08 Oct 2014 22:40:00 +0000

When editing Markdown files or internet drafts in Pandoc’s Markdown, I wanted to see some live preview window. I looked around a bit, but the solutions presented on the Internet, seemed to be insufficient, either to clumsy or don’t work at all.

My usual routine is: edit -> write -> make -> reload “rendered” file.

Turns out you can automate most of this. Vim has a feature: --servername <id> which allows you to send commands to another vim instance using that <id>. So we need two pieces to make this work.