4.1.1. Supported Markdown extensions

Abbreviations

Converts plain text abbreviations (e.g. IBM) to <abbr> elements.

This Markdown syntax extension is enabled by default. In order to disable it, pass parameter -p load.markdown.abbreviation false to ebookc.

Example:

The HTML specification is maintained by the W3C.

*[HTML]: Hyper Text Markup Language
*[W3C]: World Wide Web Consortium

is converted to:

<p>The <abbr title="Hyper Text Markup Language">HTML</abbr> specification 
is maintained by the <abbr title="World Wide Web Consortium">W3C</abbr>.</p>

which is rendered as:

The HTML specification is maintained by the W3C.

Admonitions

Syntax for creating admonitions such as notes, tips, warnings, etc.

This Markdown syntax extension is enabled by default. In order to disable it, pass parameter -p load.markdown.admonition false to ebookc.

After the "!!!" tag, the admonition type must be one of "note", "attention","caution", "danger", "fastpath", "important", "notice", "remember", "restriction", "tip","trouble", "warning".

A note example not having a title:

!!! note ""
    Support is limited to bug reports.

is converted to:

<blockquote class="role-note">
  <p>Support is limited to bug reports.</p>
</blockquote>

which is rendered as:

Support is limited to bug reports.

A tip example having a title:

!!! tip "How do you do a hard reboot on an iPad?"
    Press and hold both the **Home** and **Power** buttons 
    until your iPad&reg; reboots.

    You can release both buttons when you see Apple&reg; logo.

is converted to:

<blockquote class="role-tip">
  <h4 class="role-admonition-title">How do you do a hard reboot on an iPad?</h4>
  <p>Press and hold both the <strong>Home</strong> and <strong>Power</strong> 
  buttons until your iPad&reg; reboots.</p>
  <p>You can release both buttons when you see Apple&reg; logo.</p>
</blockquote>

which is rendered as:

How do you do a hard reboot on an iPad?

Press and hold both the Home and Power buttons until your iPad® reboots.

You can release both buttons when you see Apple® logo.

Attributes

Syntax for adding attributes to the generated HTML elements:

attributes -> '{' attribute_spec ( S attribute_spec)* '}'

attribute_spec ->   name=value
                  | name='value'
                  | name="value"
                  | #id
                  |.class

An easy rule to remember

If an {...} specification is separated by space characters from some plain text (e.g. some plain text {...}) then the attributes are added to the parent element of the text.

This Markdown syntax extension is enabled by default. In order to disable it, pass parameter -p load.markdown.attributes false to ebookc.

Example:

The *circumference { .first-term }* is the length of one circuit along the
circle, or the distance around the circle. {#circumference title="See
https://en.wikipedia.org/wiki/Circle"}

is converted to:

<p id="circumference" title="See https://en.wikipedia.org/wiki/Circle">The <em
class="first-term">circumference</em> the length of one circuit along the
circle, or the distance around the circle.</p>

which is rendered as:

The circumference is the length of one circuit along the circle, or the distance around the circle.

Pitfall

By default, heading IDs are not “rendered” in HTML (which is somewhat counterintuitive). You must pass
-p load.markdown.renderer.RENDER_HEADER_ID true
to ebookc get them “rendered”.

Automatic links

Turns plain text URLs and email addresses into <a href="..."> elements.

This Markdown syntax extension is disabled by default. In order to enable it, pass parameter -p load.markdown.autolink true to ebookc.

Example:

Please send your bug reports to ebookc-support@xmlmind.com, a public,
moderated, mailing list. More information in
http://www.xmlmind.com/ebookc/support.html.

is converted to:

<p>Please send your bug reports to <a
href="mailto:ebookc-support@xmlmind.com">ebookc-support@xmlmind.com</a>, a
public, moderated, mailing list. More information in <a
href="http://www.xmlmind.com/ebookc/support.html"
>http://www.xmlmind.com/ebookc/support.html</a>.</p>

which is rendered as:

Please send your bug reports to ebookc-support@xmlmind.com, a public, moderated, mailing list. More information in http://www.xmlmind.com/ebookc/support.html.

Definition lists

Syntax for creating definition lists, that is <dl>, <dt> and <dd> elements.

This Markdown syntax extension is enabled by default. In order to disable it, pass parameter -p load.markdown.definition false to ebookc.

Example:

Glossary:

LED
: Light emitting diode.

ABS
: Antilock braking system.

ESC
ESP
: Electronic stability control, also known as Electronic Stability Program.

: On motorcycles, ESC/ESP is called *Traction Control*.

  > Ducati was one of the first to introduce a true competition-level 
  > traction control system (**DTC**) on a production motorcycle.

EBA
: Emergency brake assist.

is converted to:

<p>Glossary:</p>
<dl>
  <dt>LED</dt>
  <dd><p>Light emitting diode.</p></dd>

  <dt>ABS</dt>
  <dd><p>Antilock braking system.</p></dd>

  <dt>ESC</dt>
  <dt>ESP</dt>
  <dd><p>Electronic stability control, also known as Electronic Stability
  Program.</p></dd>
  <dd><p>On motorcycles, ESC/ESP is called <em>Traction
  Control</em>.</p>
  <blockquote><p>Ducati was one of the first to introduce a true
  competition-level traction control system (<strong>DTC</strong>)
  on a production motorcycle.</p></blockquote></dd>

  <dt>EBA</dt>
  <dd><p>Emergency brake assist.</p></dd>
</dl>

which is rendered as:

Glossary:

LED: Light emitting diode.
ABS: Antilock braking system.
ESC
ESP: Electronic stability control, also known as Electronic Stability Program.; On motorcycles, ESC/ESP is called Traction Control.

Ducati was one of the first to introduce a true competition-level traction control system (DTC) on a production motorcycle.
EBA: Emergency brake assist.

Remember that:

The leading ":" character of a definition must be followed by one or more space characters.

Terms must be separated from the previous definition by a blank line.

A blank line is not allowed between two consecutive terms.

A blank line is allowed before a definition.

Footnotes

Syntax for creating footnotes and footnote references.

This Markdown syntax extension is enabled by default. In order to disable it, pass parameter -p load.markdown.footnotes false to ebookc.

Example:

The differences between the programming languages C++[^1] and Java can be
traced to their heritage.

[^1]: The C++ Programming Language by Bjarne Stroustrup.

C++[^1] was designed for systems and applications programming, extending the
procedural programming language C[^2].

[^2]: The C Programming Language by Brian Kernighan and Dennis Ritchie.

      Originally published in 1978.

is converted to:

<p>The differences between the programming languages
C++<a class="role-footnote-ref" href="#__FN1"></a> and Java can be traced to
their heritage.</p> 

<div class="role-footnote" id="__FN1">
  <p>The C++ Programming Language by Bjarne Stroustrup.</p>
</div> 

<p>C++<aclass="role-footnote-ref" href="#__FN1"></a> was designed for systems 
and applications programming, extending the procedural programming language
C<a class="role-footnote-ref" href="#__FN2"></a>.</p> 

<div class="role-footnote" id="__FN2">
  <p>The C Programming Language by Brian Kernighan and Dennis
  Ritchie.</p>
  <p>Originally published in 1978.</p>
</div>

which is rendered as:

The differences between the programming languages C++[1] and Java can be traced to their heritage.

C++[1] was designed for systems and applications programming, extending the procedural programming language C[2].

Ins

Converts tagged text "++something new++" to <ins>something new</ins>, which is rendered as: something new

This Markdown syntax extension is enabled by default. In order to disable it, pass parameter -p load.markdown.ins false to ebookc.

Strikethrough and subscript

Converts

tagged text "~~something deleted~~" to <del>something deleted</del>, which is rendered as: ~~something deleted~~
tagged text "~a subscript~" to <sub>a subscript<sub/>, which is rendered as: _{a subscript}

This Markdown syntax extension is enabled by default. In order to disable it, pass parameter -p load.markdown.gfm-strikethrough false to ebookc.

Superscript

Converts tagged text "^a superscript^" to <sup>a superscript</sup>, which is rendered as: ^{a superscript}

This Markdown syntax extension is enabled by default. In order to disable it, pass parameter -p load.markdown.superscript false to ebookc.

Media tags

Converts prefixed links to audio, embed, picture and video HTML5 elements.

!A[Text](links) - audio. Links is one or more links separated by character “|”.
!E[Text](links) - embed.
!P[Text](links) - picture.
!V[Text](links) - video.

Audio example:

Audio example: !A[Falcon calling](media/falcon.mp3|media/falcon.wav).

is converted to:

<p>Audio example: <audio controls="" title="Falcon calling">
  <source src="media/falcon.mp3" type="audio/mpeg">
  <source src="media/falcon.wav" type="audio/wav">
  Your browser does not support the audio element.
</audio>.</p>

which is rendered as:

Audio example: .

Video example:

Video example: !V[Funny big bunny](media/bbb.mp4).

is converted to:

<p>Video example: <video controls="" title="Funny big bunny">
  <source src="media/bbb.mp4" type="video/mp4">
  Your browser does not support the video element.
</video>.</p>

which is rendered as:

Video example: .

This Markdown syntax extension is enabled by default. In order to disable it, pass parameter -p load.markdown.media-tags false to ebookc.

Tables

Converts pipe "|" delimited text to <table> elements.

This Markdown syntax extension is enabled by default. In order to disable it, pass parameter -p load.markdown.tables false to ebookc.

Simple table example:

| Header 1 | Header 2 | Header 3 |
| -------- | -------- | -------- |
| Cell 1,1 | Cell 1,2 | Cell 1,3 |
| Cell 2,1 | Cell 2,2 | Cell 2,3 |

is converted to:

<table border="1">
  <thead>
    <tr>
      <th>Header 1</th>
      <th>Header 2</th>
      <th>Header 3</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>Cell 1,1</td>
      <td>Cell 1,2</td>
      <td>Cell 1,3</td>
    </tr>
    <tr>
      <td>Cell 2,1</td>
      <td>Cell 2,2</td>
      <td>Cell 2,3</td>
    </tr>
  </tbody>
</table>

which is rendered as:

Header 1	Header 2	Header 3
Cell 1,1	Cell 1,2	Cell 1,3
Cell 2,1	Cell 2,2	Cell 2,3

Table example having centered and right-aligned columns:

| Header 1 | Header 2        | Table Header 3 |
| -------- | :-------------: | -------------: |
| Cell 1,1 | Table cell 1,2  | Cell 1,3       |
| Cell 2,1 | Cell 2,2        | Cell 2,3       |

is converted to:

<table border="1">
  <thead>
    <tr>
      <th>Header 1</th>
      <th style="text-align: center;">Header 2</th>
      <th style="text-align: right;">Table Header 3</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>Cell 1,1</td>
      <td style="text-align: center;">Table cell 1,2</td>
      <td style="text-align: right;">Cell 1,3</td>
    </tr>
    <tr>
      <td>Cell 2,1</td>
      <td style="text-align: center;">Cell 2,2</td>
      <td style="text-align: right;">Cell 2,3</td>
    </tr>
  </tbody>
</table>

which is rendered as:

Header 1	Header 2	Table Header 3
Cell 1,1	Table cell 1,2	Cell 1,3
Cell 2,1	Cell 2,2	Cell 2,3

Table example having cells spanning several columns and a caption:

| Header 1 | Header 2 | Header 3 |
| -------- | -------- | -------- |
| Cell 1,1 + 1,2     || Cell 1,3 |
| Cell 2,1 + 2,2 + 2,3         |||
| Cell 3,1 | Cell 3,2 | Cell 3,3 |
[Table caption here]

is converted to:

<table border="1">
  <caption>Table caption here</caption>
  <thead>
    <tr>
      <th>Header 1</th>
      <th>Header 2</th>
      <th>Header 3</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td colspan="2">Cell 1,1 + 1,2</td>
      <td>Cell 1,3</td>
    </tr>
    <tr>
      <td colspan="3">Cell 2,1 + 2,2 + 2,3</td>
    </tr>
    <tr>
      <td>Cell 3,1</td>
      <td>Cell 3,2</td>
      <td>Cell 3,3</td>
    </tr>
  </tbody>
</table>

which is rendered as:

Table 4-1. Table caption here
Header 1	Header 2	Header 3
Cell 1,1 + 1,2		Cell 1,3
Cell 2,1 + 2,2 + 2,3
Cell 3,1	Cell 3,2	Cell 3,3

Typographic characters

Converts

"'" to apostrophe ’, which is rendered as in word: "don’t"
"..." and ". . ." to ellipsis …, which are both rendered as: …
"--" to en dash –, which is rendered as: –
"---" to em dash —, which is rendered as: —
single quoted 'some text' to ‘some text’, which is rendered as: ‘some text’
double quoted "some text" to “some text”, which is rendered as: “some text”
double angle quoted <<some text>> to «some text», which is rendered as: «some text»

This Markdown syntax extension is enabled by default. In order to disable it, pass parameter -p load.markdown.typographic false to ebookc.

If you don’t want some of the above plain text sequences to be processed, specify:

-p load.markdown.typographic.ENABLE_QUOTES false: Do not process single quotes, double quotes, double angle quotes.
-p load.markdown.typographic.ENABLE_SMARTS false: Do not process "'", "...", ". . .", "--", "---".

YAML front matter

Syntax for adding metadata to the generated HTML document, that is, for adding <head>/<title> and/or <head>/<meta> elements.

These metadata are specified by key/value pairs written using a subset of the YAML (see also http://yaml.org/) syntax.

This Markdown syntax extension is enabled by default. In order to disable it, pass parameter -p load.markdown.yaml-front-matter false to ebookc.

Example:

---
title: The C Programming Language
author:
  - Brian W. Kernighan
  - Dennis Ritchie
description: |
    One of the best-selling programming books published 
    in the last fifty years, "K&R" has been called everything 
    from the "bible" to "a landmark in computer science" and 
    it has influenced generations of programmers.
date: 1988-03-22
---

is converted to:

<head>
  <title>The C Programming Language</title>
  <meta content="Brian W. Kernighan" name="author" />
  <meta content="Dennis Ritchie" name="author" />
  <meta content="One of the best-selling programming books published 
                 in the last fifty years, &quot;K&amp;R&quot; has been called 
                 everything from the &quot;bible&quot; to 
                 &quot;a landmark in computer science&quot; and it has 
                 influenced generations of programmers." name="description" />
  <meta content="1988-03-22" name="date" />
</head>

Other extensions

The following Markdown syntax extensions are also supported:

anchorlink
aside
emoji
enumerated-reference
gfm-issues
gfm-tasklist
gfm-users
macros
toc
wikilink
youtube-embedded

All the above extensions are disabled by default. In order to enable an extension, pass parameter -p load.markdown.EXTENSION_NAME true to ebookc. For example: -p load.markdown.emoji true

Any extension listed in this section may be parameterized by passing parameter -p load.markdown.EXTENSION_NAME.PARAMETER_NAME PARAMETER_VALUE[3] to ebookc. Examples:

-p load.markdown.emoji.ATTR_IMAGE_SIZE 16
-p load.markdown.emoji.ATTR_ALIGN ""
-p load.markdown.emoji.USE_IMAGE_TYPE IMAGE_ONLY
-p load.markdown.emoji.USE_SHORTCUT_TYPE ANY_GITHUB_PREFERRED

With the above emoji parameters, ":smile:" is rendered as:

More generally, the Markdown parser (pseudo EXTENSION_NAME is "parser") and the HTML renderer (pseudo EXTENSION_NAME is "renderer") may also be parameterized this way. For example, automatically generate an ID for all headings not already having an ID and “render” all heading IDs in HTML[4]:
-p load.markdown.renderer.GENERATE_HEADER_ID true
-p load.markdown.renderer.RENDER_HEADER_ID true.

More information about extensions and their parameters in Extensions (flexmark-java is the software component used by ebookc to parse Markdown and convert it to HTML).

[1] The C++ Programming Language by Bjarne Stroustrup.

[2] The C Programming Language by Brian Kernighan and Dennis Ritchie.

Originally published in 1978.

[3] The only types supported for PARAMETER_VALUE are: string, boolean (true or false), integer and any enumerated type.

[4] By default, heading IDs are not “rendered” in HTML, which is somewhat counterintuitive.