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, rmd, text or txt.

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:


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:

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.less-extensions 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 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 -p load.markdown.less-extensions true is a shorthand parameter instructing ebookc to reset its extensions to the following minimal set of extensions:

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

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