4.1. Markdown support

In addition to HTML, an ebook page may be written in Markdown. However for this to work, the file extension of the page written in Markdown must be md, markdown, mdown, mkdn, mdwn, mkd or rmd.

The encoding of a Markdown file is, by default, the system encoding (e.g. window-1252 on a Western PC).

If you want to explicitly specify the encoding of a Markdown file, please save your file with a UTF-8 or UTF-16 BOM (Byte Order Mark) or add an encoding directive inside a comment anywhere at the beginning of your file. Example:

<!-- -*- coding: iso-8859-1 -*- -->

Heading
=======

## Sub-heading

Paragraphs are separated
by a blank line.

The above example should work fine because ebookc understands the GNU Emacs file variable called coding.

Out of the box, the Markdown parser is configured to support the commonmark 0.28 “Markdown dialect” plus all the following extensions:

• Abbreviations
• Admonitions
• Attributes
• Definition lists
• Footnotes
• Ins
• Strikethrough and subscript
• Media tags
• Superscript
• Tables
• Typographic characters
• YAML front matter

However, thanks to the flexmark-java software component used by ebookc to implement Markdown support, all this can be configured by passing some load.markdown.XXX options to ebookc.

For example, pass

• -p load.markdown.profile GITHUB
• -p load.markdown.extensions min
• -p load.markdown.autolink true
• -p load.markdown.gfm-tasklist true

to ebookc in order to parse the Github-flavored Markdown dialect and to enable a minimal set of extensions plus the autolink Markdown extension[1] and the task lists syntax extension.

Supported “Markdown dialects” are COMMONMARK, COMMONMARK_0_26, COMMONMARK_0_27, COMMONMARK_0_28, FIXED_INDENT, KRAMDOWN, MARKDOWN, GITHUB_DOC, GITHUB, MULTI_MARKDOWN, PEGDOWN, PEGDOWN_STRICT. See Markdown Processor Emulation.

Parameter load.markdown.extensions may be given the following values:

none

No extensions.

min

Instructs ebookc to reset its extensions to the following minimal set of extensions:

• Strikethrough and subscript
• Superscript
• Tables
• YAML front matter

The above minimal set of extensions corresponds to what’s described in the Markdown Cheatsheet.

most

Default value. See default extensions.

All supported Markdown syntax extensions are documented in Section 4.1.1. Supported Markdown extensions.