API Reference

The base Markdown syntax defined by this extension is:

\begin{...}
...
\end{...}

Important

• Each \begin{} must be on its own line with a blank line above, and each \end{} must be on its own line with a blank line below.

• Only nesting different types of environments works; nesting the same environment within itself does not.

Captioned Figure

class markdown_environments.CaptionedFigureExtension

Any chunk of content, such as an image, with a caption underneath.

Usage:

import markdown
from markdown_environments import CaptionedFigureExtension

input_text = ...
output_text = markdown.markdown(input_text, extensions=[
    CaptionedFigureExtension(html_class="never", caption_html_class="gonna")
])

Markdown usage:

\begin{captioned_figure}
<figure content>

\begin{caption}
<caption>
\end{caption}

\end{captioned_figure}

becomes…

<figure class="[html_class]">
  [figure content]
  <figcaption class="[caption_html_class]">
    [caption]
  </figcaption>
</figure>

Note

The caption block can be placed anywhere within the captioned_figure block, as long as, of course, there are blank lines before and after the caption block.

__init__(**kwargs)

Initialize captioned figure extension, with configuration options passed as the following keyword arguments:

• html_class (str) – HTML class attribute to add to figures (default: "").

• caption_html_class (str) – HTML class attribute to add to captions (default: "").

Cited Blockquote

class markdown_environments.CitedBlockquoteExtension

A blockquote with a citation/quote attribution underneath.

Usage:

import markdown
from markdown_environments import CitedBlockquoteExtension

input_text = ...
output_text = markdown.markdown(input_text, extensions=[
    CitedBlockquoteExtension(html_class="give", citation_html_class="you")
])

Markdown usage:

\begin{cited_blockquote}
<quote>

\begin{citation}
<citation>
\end{citation}

\end{cited_blockquote}

becomes…

<blockquote class="[html_class]">
  [quote]
</blockquote>
<cite class="[citation_html_class]">
  [citation]
</cite>

Note

The citation block can be placed anywhere within the cited_blockquote block, as long as, of course, there are blank lines before and after the citation block.

__init__(**kwargs)

Initialize cited blockquote extension, with configuration options passed as the following keyword arguments:

• html_class (str) – HTML class attribute to add to blockquotes. Defaults to "".

• citation_html_class (str) – HTML class attribute to add to captions. Defaults to "".

Div

class markdown_environments.DivExtension

A general-purpose <div> that you can tack on HTML class es to.

Usage:

import markdown
from markdown_environments import DivExtension

input_text = ...
output_text = markdown.markdown(input_text, extensions=[
    DivExtension(html_class="up", types={
        type1: {},
        type2: {"html_class": "never"}
    })
])

Markdown usage:

\begin{<type>}
<content>
\end{<type>}

becomes…

<div class="[html_class] [type's html_class]">
  [content]
</div>

__init__(**kwargs)

Initialize div extension, with configuration options passed as the following keyword arguments:

• types (dict) – Types of div environments to define. Defaults to {}.

• html_class (str) – HTML class attribute to add to divs. Defaults to "".

The key for each type defined in types is inserted directly into the regex patterns that search for \begin{<type>} and \end{<type>}, so anything you specify will be interpreted as regex. However, if the key is an empty string, its regex will never be matched against, so it is effectively useless. In addition, each type’s value is itself a dictionary with the following possible options:

• html_class (str) – HTML class attribute to add to divs of that type. Defaults to "".

Dropdown

class markdown_environments.DropdownExtension

A dropdown that can be toggled open or closed, with only a preview portion (<summary>) shown when closed.

Usage:

import markdown
from markdown_environments import DropdownExtension

input_text = ...
output_text = markdown.markdown(input_text, extensions=[
    DropdownExtension(
        html_class="gonna", summary_html_class="let", content_html_class="you",
        types={
            type1: {"html_class": "down"},
            type2: {}
        }
    )
])

Markdown usage:

\begin{<type>}

\begin{summary}
<summary>
\end{summary}

<collapsible content>
\end{<type>}

becomes…

<details class="[html_class] [type's html_class]">
  <summary class="[summary_html_class]">
    [summary]
  </summary>

  <div class="[content_html_class]">
    [collapsible content]
  </div>
</details>

Important

The summary block must be placed at the start of the dropdown block, of course with blank lines before and after the summary block.

__init__(**kwargs)

Initialize dropdown extension, with configuration options passed as the following keyword arguments:

• types (dict) – Types of dropdown environments to define. Defaults to {}.

• html_class (str) – HTML class attribute to add to dropdowns. Defaults to "".

• summary_html_class (str) – HTML class attribute to add to dropdown summaries. Defaults to "".

• content_html_class (str) – HTML class attribute to add to dropdown contents. Defaults to "".

The key for each type defined in types is inserted directly into the regex patterns that search for \begin{<type>} and \end{<type>}, so anything you specify will be interpreted as regex. However, if the key is an empty string, its regex will never be matched against, so it is effectively useless. In addition, each type’s value is itself a dictionary with the following possible options:

• html_class (str) – HTML class attribute to add to dropdowns of that type. Defaults to "".

Thms

class markdown_environments.ThmsExtension

A wrapper around divs and dropdowns that provides more options to mimic the theorem capabilities of LaTeX.

In particular, this extension introduces theorem headings and theorem counters, which are used in theorem environments but can also be used standalone as described below.

Theorem headings:

The terminology I use for the parts of a theorem heading throughout the documentation is as follows:

Lemma 2.1.3 (Euler's theorem).
  ^     ^           ^        ^
 thm   thm         thm      thm
type counter       name    punct

Markdown usage:

{[<thm type><thm counter>]}[<optional thm name>]{<optional hidden thm name>}

becomes…

<span id="[thm name/hidden thm name]" class="[thm_heading_config's html_class]">
  <span class="[thm_heading_config's emph_html_class]">[thm type][thm counter]</span>
  [thm name]<span class="[thm_heading_config's emph_html_class]">.</span>
</span>

Note:

<optional hidden thm name> is only used for the HTML id, and it is ignored if <optional thm name> is provided.

Theorem counters:

Theorem counters are specified as a (positive) offset from the previous theorem counter, similar to how \newtheorem in LaTeX lets you define the counter (but hopefully in a slightly less janky way). Offsets are specified per segment, and incrementing a segment resets all following segments to 0. In addition, each counter will display only as many segments as provided in its Markdown.

Usage:

Section {{1}}
Subsection {{0,1,0,0,0,0,0}} (displays as many segments as given)
Lemma {{0,0,0,1}}
Theorem {{0,0,1}} (the fourth counter segment is reset here). Let x be a lorem ipsum.
Reevaluating Life Choices {{0,0,0,3}}
What even is this {{1,2,0,3,9}} (first counter segment resets next ones, and so on)

becomes…

<p>Section 1</p>
<p>Subsection 1.1.0.0.0.0.0 (displays as many segments as given)</p>
<p>Lemma 1.1.0.1</p>
<p>Theorem 1.1.1 (the fourth counter segment is reset here). Let x be a lorem ipsum.</p>
<p>Reevaluating Life Choices 1.1.1.3</p>
<p>What even is this 2.2.0.3.9 (first counter segment resets next ones, and so on)</p>

Important

There cannot be spaces within the Markdown {{}} syntax for theorem counters.

Usage:

import markdown
from markdown_environments import ThmsExtension

input_text = ...
output_text = markdown.markdown(input_text, extensions=[
    ThmsExtension(
        div_config={
            "types": {
                "thm": {
                    "thm_type": "Theorem",
                    "html_class": "md-thm",
                    "thm_counter_incr": "0,0,1"
                }
            },
            "html_class": "md-div"
        },
        dropdown_config={
            "types": {
                "exer": {
                    "thm_type": "Exercise",
                    "html_class": "md-exer",
                    "thm_counter_incr": "0,0,1"
                }
            },
            "html_class": "md-dropdown",
            "content_html_class": "md-dropdown__content"
        },
        thm_counter_config={
            "add_html_elem": True,
            "html_id_prefix": "spanish-inquisition"
        },
        thm_heading_config={
            "html_class": "md-thm-heading"
        }
    )
])

Markdown usage (div-based):

\begin{<type>}[<optional thm name>]{<optional hidden thm name>}
<content>
\end{<type>}

becomes, with theorem heading and counter syntax…

\begin{<type>}
{[<type's thm type> {{<type's thm_counter_incr>}}]}[<thm name>]{<hidden thm name>}
<content>
\end{<type>}

becomes…

<div class="[html_class] [type's html_class]">
  <span id="[thm name/hidden thm name]" class="[thm_heading_config's html_class]">
    <span class="[thm_heading_config's emph_html_class]">[thm type][thm counter]</span>
    [thm name]<span class="[thm_heading_config's emph_html_class]">.</span>
  </span>
  [content]
</div>

Markdown usage (dropdown-based):

\begin{<type>}[<optional thm name>]{<optional hidden thm name>}

\begin{summary}
<summary>
\end{summary}

<collapsible content>
\end{<type>}

becomes, with theorem heading and counter syntax…

\begin{<type>}

\begin{summary}
{[<type's thm type> {{<type's thm_counter_incr>}}]}[<thm name>]{<hidden thm name>}
<summary>
\end{summary}

<collapsible content>
\end{<type>}

becomes…

<details class="[html_class] [type's html_class]">
  <summary class="[summary_html_class]">
    <span id="[thm name/hidden thm name]" class="[thm_heading_config's html_class]">
      <span class="[thm_heading_config's emph_html_class]">[thm type][thm counter]</span>
      [thm name]<span class="[thm_heading_config's emph_html_class]">.</span>
    </span>
    [summary]
  </summary>

  <div class="[content_html_class]">
    [collapsible content]
  </div>
</details>

Notice that with dropdowns, the theorem heading is prepended to the summary of the dropdown. In addition, the \begin{summary} block is optional with theorems; if omitted, the summary will only include the theorem heading.

__init__(**kwargs)

Initialize dropdown extension, with configuration options passed as the following keyword arguments:

• div_config (dict) – configs for divs. Possible config keys are:

  • types (dict) – Types of div-based theorem environments to define. Defaults to {}.

  • html_class (str) – HTML class attribute to add to div-based theorem environments. Defaults to "".

• dropdown_config (dict) – configs for dropdowns. Possible config keys are:

  • types (dict) – Types of dropdown-based theorem environments to define. Defaults to {}.

  • html_class (str) – HTML class attribute to add to dropdown-based theorem environments. Defaults to "".

  • summary_html_class (str) – HTML class attribute to add to dropdown summaries. Defaults to "".

  • content_html_class (str) – HTML class attribute to add to dropdown contents. Defaults to "".

• thm_counter_config (dict) – configs for theorem counter. Possible config keys are:

  • add_html_elem (bool) – Whether theorem counters are contained in their own HTML element. Defaults to False.

  • html_id_prefix (str) – Text to prepend to HTML id attribute of theorem counters if add_html_elem is True; usually useful for linking. Defaults to "".

  • html_class (str) – HTML class attribute to add to theorem counters if add_html_elem is True. Defaults to "".

• thm_heading_config (dict) – configs for theorem headings. Possible config keys are:

  • html_id_prefix (str) – Text to prepend to HTML id attribute of theorem headings (for all theorem heading elements with id attributes). Defaults to "".

  • html_class (str) – HTML class attribute to add to theorem headings. Defaults to "".

  • emph_html_class (str) – HTML class attribute to add to theorem types in theorem headings. Defaults to "".

The key for each type defined in both div_config’s and dropdown_config’s types is inserted directly into the regex patterns that search for \begin{<type>} and \end{<type>}, so anything you specify will be interpreted as regex. However, if the key is an empty string, its regex will never be matched against, so it is effectively useless. In addition, each type’s value in types is itself a dictionary with the following possible options:

• thm_type (str) – Theorem type actually displayed in theorem headings. Defaults to "".

• html_class (str) – HTML class attribute to add to theorems of that type. Defaults to "".

• thm_counter_incr (str) – Theorem counter inserted into theorem headings (again, no spaces!). Defaults to ""; leave default to produce an unnumbered theorem type.

• thm_name_overrides_thm_heading (bool) – Whether the entire theorem heading besides the theorem punct should just be theorem name if a theorem name is provided, like the default behavior of \begin{proof} environments in LaTeX. Defaults to False.