Use Pandoc Markdown in Pelican

 February 02, 2021      Stardate: 74556.0     Tagged as: Pandoc Pelican

This article documents installing the pelican plugin Pandoc-Reader, which changes the engine that converts Markdown syntax to html from the standard Python-Markdown to Pandoc..

Why? Pandoc is awesome on many levels, but specifically for this blog, it allows me to write pandoc’s flavor of markdown. I added Python-Markdown Extensions that gave some cool features, but it still didn’t satisfy me.

Some of my personal favorite features are:

• Figure Captions!
• Footnotes
• Emojis
• Internal Links

One feature it doesn’t have are reStructured-like admonitions. This is something that Markdown Extensions had 😞 - but I saw a Pandoc filter that looked like it will implement those.

Installation

The installation is easy and the instructions are clear. Make sure you have at least Pandoc 2.11, then pip install the plugin.

python -m pip install pelican-pandoc-reader

One note is that your metadata (Title:, Date:, etc.) has to be in YAML format. That is means fenced by triple dashes. Example:

---
Title: Me
Date: 2021-01-01
---

If you already have a bunch of articles written, here is a simple python script that should convert it for you.

You also need to add these variables to the pelicanconf.py file.

# Arguments passed into pandoc
PANDOC_ARGS = [
    "--mathjax",
]

# Non-Pandoc Extensions that are not enabled by default in pandoc
#   https://pandoc.org/MANUAL.html#non-pandoc-extensions
PANDOC_EXTENSIONS = [
    "+abbreviations",
    "+backtick_code_blocks",
    "+emoji"
    ]

Pandoc Markdown

Here are some examples of the cool features built-in Pandoc Markdown.

Figure Captions

Note

I’ve applied styling to the figure and figure captions within my CSS Stylesheets.

Footnotes

MARKDOWN:

Here is a footnote reference,[^1] and another.[^longnote]

[^1]: Here is the footnote.

[^longnote]: Here's one with multiple blocks.

HTML RESULT:

Here is a footnote reference,¹ and another.²

Emojis

Pandoc converys textual emojis into Unicode emoticons. https://www.webfx.com/tools/emoji-cheat-sheet/

MARKDOWN:

 :smiley:
 :cow:

HTML RESULT:

• 😃
• 🐮

Links

MARKDOWN:

You can go directly to <https://.google.com> to find it.

HTML RESULT:

You can go directly to https://google.com to find it.

MARKDOWN:

Go see the very last header named [MathJax](#mathjax)

HTML RESULT:

Go see the very first header named SmartyPants

SmartyPants

Write this in MARKDOWN:

"curly quotes"
... are ellipses
-- are en-dashes
--- are em-dashes

To get this HTML RESULT:

• “curly quotes”
• … are ellipses
• – are en-dashes
• — are em-dashes

Line Blocks

MARKDOWN:

| The limerick packs laughs anatomical
| In space that is quite economical.
|    But the good ones I've seen
|    So seldom are clean
| And the clean ones so seldom are comical

| 200 Main St.
| Berkeley, CA 94718

HTML RESULT:

Lists

MARKDOWN:

COMPACT LISTS
-------------
* one
* two
* three

HTML RESULT:

• one
• two
• three

LOOSE LISTS
-----------
* one

* two

* three

HTML RESULT:

• one

• two

• three

Fancy List

MARKDOWN:

(1) One
(2) Two
    a. 2.1
    b. 2.2
(3) Three

HTML RESULT:

1. One
2. Two
   1. 2.1
   2. 2.2
3. Three

MARKDOWN:

#. one
#. two
#. three

HTML RESULT:

1. one
2. two
3. three

StartNum

MARKDOWN:

 9)  Ninth
10)  Tenth
11)  Eleventh
       i. subone
      ii. subtwo
     iii. subthree

HTML RESULT:

9. Ninth
10. Tenth
11. Eleventh
    1. subone
    2. subtwo
    3. subthree

Defintion Lists

MARKDOWN:

Term 1
  ~ Definition 1

Term 2
  ~ Definition 2a
  ~ Definition 2b

HTML RESULT:

Term 1

Definition 1

Term 2

Definition 2a

Definition 2b

**NOTE: I styled the definitions with CSS

Example Lists

MARKDOWN:

(@)  My first example will be numbered (1).
(@)  My second example will be numbered (2).

Explanation of examples.

(@)  My third example will be numbered (3).

HTML RESULT:

1. My first example will be numbered (1).
2. My second example will be numbered (2).

Explanation of examples.

3. My third example will be numbered (3).

Superscript and Subscripts

MARKDOWN:

H~2~O is a liquid.  2^10^ is 1024.

HTML RESULT:

H₂O is a liquid. 2¹⁰ is 1024.

Strikeout

MARKDOWN:

This ~~is deleted text.

HTML RESULT:

This is deleted text.

Small Caps

MARKDOWN:

[Hello Everyone]{.smallcaps}, how are you doing?

HTML RESULT:

Hello Everyone, how are you doing?

MathJax

MARKDOWN:

This is an inline math $y = mx +b$ which is cool.

HTML RESULT:

This is an inline math \(y = mx +b\) which is cool.

MARKDOWN:

This is a full math equation.
$$ y = mx +b $$ 

HTML RESULT:

This is a full math equation. \[ y = mx +b \]