There are now multiple Markdown parsers, each with their own idiosyncrasies. To make matters worse, there's a set of extensions popularly known as "Markdown Extra".

Extra has support for things like tables, footnotes, and - in some dialects - autolinks.

Most of the time, when an author writes the text Visit https://example.com they want the URl to be automatically turned into a hyperlink. Most Markdown parsers support that. Hurrah!

But there's a rather nasty little edge case.

Markdown is explicitly designed so that authors can mix and match HTML and Markdown in the same document. This is perfectly valid:

I <em>love</em> the delicious taste of **fresh** oranges!

Which becomes:

I <em>love</em> the delicious taste of <strong>fresh</strong> oranges!

This is also valid:

<a href="https://example.com/">Visit my *favourite* site https://example.com/</a>!

The parser is smart enough to ignore the link inside the href="" but will process all the Markdown contents of the <a> element.

The text favourite is converted to <em>favourite</em> correctly.

But what about the link? Should that be autolinked?

Here's how a few dozen different Markdown parsers fare.

Nearly all of the ones which support Autolink end up producing broken HTML. They nest an anchor within an anchor. Something explicitly forbidden by the HTML specification.

<a href="https://example.com/">Visit my
   <em>favourite</em> site 
   <a href="https://example.com/">https://example.com/</a>
</a>!

Others break in weird and unexpected ways.

Is this a bug?

Markdown is an excellent example of "do what I mean, not what I say" software. To the human reading the text, it might seem obvious which parts need to be transformed and which don't.

There are various specifications for how autolinking should work - but I couldn't find any documents which explicitly discuss where it shouldn't work.

At this point, you're probably going to leave a comment saying that it is the users who are wrong. They should wrap links in brackets, or stick to pure Markdown, or some other tosh.

Markdown was supposed to simplify the process of writing HTML. Anything which forces the user to write in an unnatural or confusing way is a bug.

Markdown allows you to write using an easy-to-read, easy-to-write plain text format, then convert it to structurally valid XHTML (or HTML).

Markdown Introduction

I don't think any of the authors of Markdown parsers have been naughty here. They mostly just follow the spec. But Markdown was designed without ever being tested with real users. And real users break things in all sorts of unexpected and delightful ways.

That's where the real bug is. When we don't test with users and fail to meet their expectations, we produce faulty software.

The zeroth² element is sacrosanct to our creed; for in the beginning there was nothing.

If you're using WordPress's JetPack, it uses an ancient version of Markdown Extra. You can either monkeypatch this, or install a separate Markdown plugin.

I've patched my fork of it in two specific places.

Firstly, I set $this->footnote_counter = 0; in the initial config of the footnotes.

Secondly, I changed the display so that the ordered list began from zero: <ol start="0">

Wait… should that be zerothly and firstly?

There's no way to change footnote links to symbols like * or ♪. Perhaps I'll add that next^3😉?

Anyway, I enjoy hacking around on my theme.

Problem

You installed the WordPress JetPack plugin and wrote all your blog posts in Markdown. Now you want to remove JetPack or replace it with a better Markdown parser.

You turn off JetPack's "Write posts or pages in plain-text Markdown syntax". You click edit on a post and see the HTML version of your page. Where did the Markdown version go?

Background

When you write using JetPack's Markdown plugin, the Markdown version is stored in post_content_filtered. When you hit "publish" or "update", the page is parsed as Markdown and the HTML output is stored in post_content.

When you hit "edit", the post_content_filtered version is loaded into the editor - and the process starts again.

Solution

When you edit a post, replace the content with the filtered version, then delete the filtered version.

Place this code in your theme's functions.php.

function edit_markdown_content( $content, $id ) {
    $post = get_post( $id );
    if ( $post && ! empty( $post->post_content_filtered ) ) {
        //  Get the Markdown version
        $markdown = $post->post_content_filtered;

        //  Delete the post_content_filtered version
        global $wpdb;
        $debug = $wpdb->query( 
            $wpdb->prepare(
                "UPDATE $wpdb->posts SET `post_content_filtered` = '' WHERE `wp_posts`.`ID` = %d",
                                                                                              $id
            )
        );

        //  Replace the post_content with the Markdown version
        $post->post_content = $markdown;

        //  Send it to the editor with a message saying that it was restored, along with the date of restoration
        return "<!-- Restored from post_content_filtered \n" . date("c") . "\n-->" . $post->post_content;
    }
    return $post->post_content;
}
add_filter( "edit_post_content", "edit_markdown_content", 1, 2 );

I adapted it from WP Githuber MD

Direct MySQL

If you want to automatically convert all your posts, you can edit your database directly.

UPDATE wp_posts
SET 
    post_content = post_content_filtered,
    post_content_filtered = ''
WHERE post_content_filtered IS NOT NULL AND post_content_filtered<>'';

Warning

If you do not have a Markdown parser installed, posts will come out looking *very* strange.

WP GeSHi Highlight Redux works with WordPress's Classic Editor to convert Markdown to syntax highlighted code.

That allows me to write:

```php
$a = "Hello";
$b = 5 * 2;
echo $a . str($b);
```

And have it displayed as:

$a = "Hello";
$b = 5 * 2;
echo $a . str($b);

I've previously written about the WP GeSHi Highlight plugin. My plugin is a fork of that. It has the following changes:

• RSS & Atom feeds - disable code highlighting
• Remove extra style wrappers
• Markdown support
• Remove line-numbers
• Remove escape option (escape now permanent)
• Remove TinyMCE changes
• Remove custom CSS options
• Improve default CSS
• Improve HTML detection

These changes work for me, with my weird blogging set-up. If they work for you, feel free to use it. If they don't work for you, please fork and write your own code.

You can download WP GeSHi Highlight Redux or get the original plugin.

To that end, I'm writing a patch for PHP Markdown which will display the first ~200 characters of a footnote in the pop-up title text. Hover over the superscript number and you'll get a preview of the footnote⁰.

Dealing with all sorts of weird HTML & Markdown edge-cases is tricky. So, if you'd like to help, please contribute to this discussion. And if you spot any bugs, please let me know.

The test... Begins!

These footnotes support HTML¹.

And they cope with Markdown².

Footnotes with an image³ have the img replaced with its alt text.

They don't choke on entities⁴.

And plain quote marks are fine⁵.

Nested elements should work⁶.

Very long footnotes are truncated⁷.

Fully multilingual⁸.

Also Emoji⁹ compatible.

Although some may be split if they use ZWJ¹⁰.

Every Element

These are the HTML elements which display textual content - and some notes on where unusual things might happen.

• <a>¹¹ works, but doesn't show the destination of the link.

• <abbr>¹² The title text doesn't show.

• <address>¹³

• <area> / <map>¹⁴ alt text shows.

• <article>¹⁵

• <aside>¹⁶

• <audio>¹⁷

• <b>¹⁸

• <bdi>¹⁹ The BDI algorithm isn't implemented.

• <bdo>²⁰ The override isn't implemented.

• <blockquote>²¹

• <br>²² changed to newlines - which works.

• <button>²³

• <cite>²⁴

• <code>²⁵

• <data>²⁶ Doesn't show the value.

• <del>²⁷

• <details><summary>²⁸

• <dfn>²⁹

• <dialog>³⁰

• <div>³¹

• <dl><dt><dd>³²

• <em>³³

• <fieldset><legend>³⁴

• <figure><figcaption>³⁵

• <footer>³⁶

• <form>³⁷

• <h1>³⁸

• <header>³⁹

• <hgroup>⁴⁰

• <i>⁴¹

• <img>³

• <ins>⁴² datetime isn't shown.

• <kbd>⁴³

• <label>⁴⁴

• <mark>⁴⁵

• <menu><li>⁴⁶

• <meter>⁴⁷

• <nav>⁴⁸

• <ol><li>⁴⁹

• <optgroup>⁵⁰

• <option>⁵¹

• <output>⁵²

• <p>⁵³

• <picture><source>⁵⁴

• <pre>⁵⁵

• <progress>⁵⁶

• <q>⁵⁷

• <ruby><rp><rt>⁵⁸

• <s>⁵⁹ It isn't possible to show a strikethrough in a tooltip.

• <samp>⁶⁰

• <section>⁶¹

• <select>⁶²

• <small>⁶³

• <span>⁶⁴

• <strong>⁶⁵

• <sub>⁶⁶ Subscript formatting isn't available in title text

• <sup>⁶⁷ Neither is superscript

• <table><thead><tr><th><tbody><td><tfoot><caption><colgroup><col>⁶⁸

• <textarea>⁶⁹

• <time>⁷⁰ datetime isn't displayed

• <u>⁷¹

• <ul>⁷² If there is no space between the elements, the tooltip may look odd. Here, the HTML is

• <var>⁷³

• <video>⁷⁴

• <wbr>⁷⁵

Get involved

If you'd like to peruse my code or offer a suggestion, take a look at this GitHub issue.

So, you want to write your dissertation or thesis in Markdown. But how do you manage all your citations?

1. Install Zotero
2. Install the Better BibTex plugin
3. Restart Zotero. The BBT plugin will launch a configuration screen - use it to set your preferences
4. Install VS Code (or VS Codium)
5. Install the VS Code Zotero plugin

Now, when you want to enter a citation in Markdown, the combined plugins will generate something like this:

## Abstract

Space is really big @adamsHitchhiker1979

That @adamsHitchhiker1979 is the citation.

Formatting citations

You want to export your Markdown to something like ePub or PDF with nicely formatted citations like (Adams, 1979)

Use Pandoc!

1. Install Pandoc
2. In Zotero, use File → Export Library. Export in Better BibTex format as test.bib.

Add the following configuration section to the top of your Markdown file:

---
bibliography: test.bib
...

Run the following command:

pandoc --citeproc test.md -o test.epub

Hey presto! You now have a nicely formatted ePub with all the citations in your preferred format, and the bibliography at the end.

Format the citations better

The citations don't look the way I want them to!

1. Download your preferred Citation Style from Zotero, save it as whatever.csl
2. Add the following into your Markdown file's configuration section csl: whatever.csl
3. Important Make sure that your citations are wrapped in [ and ] otherwise Pandoc will mess things up. See the Pandoc Citations Extension for more details.

Your Markdown should look something like this:

---
bibliography: test.bib
csl: whatever.csl
link-citations: true
...

# Intro

Computers are complicated [@verletComputerExperimentsClassical1967].

Then run pandoc --citeproc test.md -o test.epub - you can change the file type to html, pdf, or anything else your system supports.

Make it look even nicer

This is the boilerplate that I use.

---
bibliography: test.bib
csl: whatever.csl
link-citations: true
reference-section-title: References
title: My brilliant title
...

# Intro

Computers are complicated [@verletComputerExperimentsClassical1967].

## Something

More info [@smithEvolutionInnovationCapability2017]

<div id="refs">
## References
</div>

## The End
Goodbye!

That gives you a title, ensures that all in-text citations link down to the references, and puts the references somewhere other than the end. Here's the HTML it produces using pandoc --citeproc test.md -o bib.html :

<h1 id="intro">Intro</h1>
<p>Computers are complicated <span class="citation" data-cites="verletComputerExperimentsClassical1967">(<a
         href="https://shkspr.mobi/blog/2022/11/zotero-citations-in-markdown-publishing-to-epub-or-pdf/#ref-verletComputerExperimentsClassical1967" role="doc-biblioref">Verlet, 1967</a>)</span>.</p>
<h2 id="something">Something</h2>
<p>More info <span class="citation" data-cites="smithEvolutionInnovationCapability2017">(<a
         href="https://shkspr.mobi/blog/2022/11/zotero-citations-in-markdown-publishing-to-epub-or-pdf/#ref-smithEvolutionInnovationCapability2017" role="doc-biblioref">Smith <em>et al.</em>, 2017</a>)</span>
</p>
<div id="refs" class="references csl-bib-body" role="doc-bibliography">
   <h2 id="references">References</h2>
   <div id="ref-smithEvolutionInnovationCapability2017" class="csl-entry" role="doc-biblioentry">
      Smith, C. <em>et al.</em> (2017) <span>‘The <span>Evolution</span> of an
         <span>Innovation Capability</span>’</span>, <em>Research-Technology
         Management</em>, 60(2), pp. 26–35. Available at: <a
         href="https://doi.org/10.1080/08956308.2017.1276388">https://doi.org/10.1080/08956308.2017.1276388</a>.
   </div>
   <div id="ref-verletComputerExperimentsClassical1967" class="csl-entry" role="doc-biblioentry">
      Verlet, L. (1967) <span>‘Computer "<span>Experiments</span>" on
         <span>Classical Fluids</span>. <span>I</span>. <span>Thermodynamical
            Properties</span> of <span>Lennard-Jones Molecules</span>’</span>,
      <em>Physical Review</em>, 159(1), pp. 98–103. Available at: <a
         href="https://doi.org/10.1103/PhysRev.159.98">https://doi.org/10.1103/PhysRev.159.98</a>.
   </div>
</div>
<h2 id="the-end">The End</h2>
<p>Goodbye!</p>

If that was useful to you - or if you think you know a better way - please drop a comment in the box.

The Problem

Using WordPress's JetPack, markdown footnotes are rendered as:

Some text <sup id="fnref-1234-1"><a href="https://shkspr.mobi/blog/2021/10/better-footnotes-in-wordpress-jetpack/#fn-1234-1" class="jetpack-footnote">1</a></sup>
...
<li id="fn-1234-1">The footnotes. <a href="https://shkspr.mobi/blog/2021/10/better-footnotes-in-wordpress-jetpack/#fnref-1234-1">↩</a></li>

There are two main problems with this:

1. The <sup>1</sup> doesn't announce the destination of the link.
2. The ↩ may be read out as "leftwards arrow with hook"

Ideally, it would be useful to have something like:

<a href="https://shkspr.mobi/blog/2021/10/better-footnotes-in-wordpress-jetpack/#fn-1234-1" aria-label="Read footnote 1" ...

and

<a href="https://shkspr.mobi/blog/2021/10/better-footnotes-in-wordpress-jetpack/#fnref-1234-1" aria-label="Return to main content">↩</a>

Or similar.

The Solution

The issue occurs in jetpack/_inc/lib/markdown/extra.php

@define( 'MARKDOWN_FN_LINK_TITLE',     "" );
@define( 'MARKDOWN_FN_BACKLINK_TITLE', "" );

The link and backlink titles are used later in the same file to set the title.

if ($this->fn_backlink_title != "") {
    $title = $this->fn_backlink_title;
    $title = $this->encodeAttribute($title);
    $attr .= " title=\"$title\"";
}

But, because they're never set, the code doesn't run.

It's pretty easy to hotfix this. Replace the above definitions with:

@define( 'MARKDOWN_FN_LINK_TITLE',     __( 'Read footnote.', 'jetpack' ) );
@define( 'MARKDOWN_FN_BACKLINK_TITLE', __( 'Return to main content.', 'jetpack' ) );

I've raised this as an issue on GitHub.

Problems with the solution.

• It will be overwritten when JetPack updates. You can also add the new @defines to your theme if you want them to survive updates.
• I'm not sure if title is the right element. Although it seems has the same precedence as aria-label in the Accessible Name and Description Computation algorithm
• It is in English only. Because those strings don't exit in the translation file, it will only work for monolingual installs.
• The title text shows as a pop-up on certain browsers.
• No metadata. It might be nice to have the title say "Read footnote 23."
• Some footnote plugins put the footnote text in the title. That may be useful.

If you'd like to see this in the default JetPack experience - please leave a comment on GitHub.

The code is pretty simple. Write [^1] where you want your first footnote link to appear. Then, later in the document, write [^1]: The text of the note.

It doesn't matter what number you put inside the [^…], WordPress automatically generates a sequential number when displaying the links. For example, this one is [^3]¹

In order to keep your thoughts straight while writing and editing, you can give your footnotes names - like [^fn about names]². If you want, you can also use emoji³. When you click that link, the emoji should appear in your URl bar.

Similarly, you can write the footnote text next to where you want the link to appear. Something like:

Something like[^5] 
[^5]: See!

should work fine⁴.

Sadly⁵, there's no such thing as a <footnote> element⁶ in HTML

WordPress automagically puts the footnotes at the end of your page in this structure:

<div class="footnotes">
   <hr>
   <ol>
      <li id="fn-1234-1"> ... <a href="#fnref-1234-1">↩</a></li>
...

This means you can style the div and hr⁷. The number after fn- is the WordPress post ID.

There are a few other things to be aware of⁸, but they're pretty easy to use. No plugins required, no expensive themes. Just cool in-built functionality.

Enjoy!⁹