ExPost: Render HTML from Etherpads and Use Etherpad Instead of the WordPress Editor

Dogfoodaliciousness: This page is rendered live from [redacted].

What’s this do?

ExPost replaces the built in WordPress editor with an Etherpad. This is really useful if you want to collaborate with someone on posts for your blog, because Etherpad is the king of collaborative editors. Etherpad also has this really sweet Time Slider feature that lets you view a playback of the history of the pad. So, it lets multiple authors edit the same source at the same time in real real-time, and it keeps a complete version history of everything you ever type. You can work on the post from wp-admin if you like (we embed the pad), or from the Etherpad directly, but only a user with permission to publish on your blog can make the content go live.

So, what else? Well, we also run the content from the Etherpad through a markdown library and implement a super sweet LaTeX-style numbering scheme that makes it easy to do named references back to items in a numbered list, and not worry about the order or number of the reference changing. Particularly handy for writing FAQs and Footnotes. Details on that below.

How does it work?

Install and activate the plugin in the usual way. Then when you add a new post in WordPress, you’ll see a new box in the admin interface, just under your title. Enter a URL for an Etherpad and we replace the WordPress editor with your Etherpad. When you save your post, we grab the contents of the Etherpad, apply some magic, and save it in WordPress. Note that previews currently show the last saved content, not the latest updates from Etherpad. Also note that the plugin disables autosave and revisions in WordPress, since Etherpad does that all for you.

Magic that ExPost Performs

Nitty-Gritty Details of the LaTeX-Style Numbering

ExPost replaces each occurrence of $REF[foo] with a unique number, starting with 1 for the first $REF occurrence and counting up sequentially with each new tag. The tags are case sensitive.

As a shortcut, if a tag foo has been defined anywhere in the source with $REF[foo] then all other instances can be abbreviated to just $foo. If $foo occurs where foo is not a tag defined anywhere with $REF then it will not be translated, nor will any subsequent $-prefixed tags on the same line, defined with $REF or not.

Special $FN Syntax for Footnotes

$FN[foo] works the same as $REF[foo] except instead of getting replaced with just a number, N, it gets replaced with one of the following:

<a id="foo1" href="#foo">[N]</a>
<a id="foo" href="#foo1">[N]</a>

The first occurrence is replaced with the first version and the second with the second, assuming only two occurrences, per usual for footnotes. In other words, both occurences of the tag get replaced with a number in brackets and they hyperlink to each other — one being in the body and the other being at the bottom where the actual footnote content is. [1]


[1] What happens in the case of more than two occurrences of a footnote? One answer is, just don’t do that. But for completeness’ sake, the real answer is: the natural generalization where all but the last occurrence links to the last occurrence and the last occurrence links to the first. Specifically, each occurrence gets replaced with one of the following:

<a id="fooX" href="#foo">[N]</a>
<a id="foo" href="#foo1">[N]</a>

where X is defined such that $FN[foo] is the Xth occurrence of $FN[foo]. All but the last occurrence of $FN[foo] get replaced with the first version and the last occurrence (taken to be the place where the actual footnote content is given) is replaced with the second version. Note that $FN tags and $REF tags get numbered independently but you shouldn’t use the same tag foo for both a $FN and a $REF. Various screwiness will happen if you do. Using “FOO” for one and “foo” for the other is fine though, since tags are case sensitive.