Using Markdeep for a WordPress blog
Update 2016-12-23: Morgan McGuire has kindly fixed an issue in Markdeep pertaining to HTML mode. In an earlier version of this blog post I suggested a workaround, which has been removed now. Besides the utility has been extended to make it easier to update to new Markdeep versions.
In response to Morgan McGuire's request this post will explain how I set up this blog using his handy Markdeep, MathJax and Wordpress. The blog is hosted on my rented server and when you request a page it usually won't make connections to any other hosts to keep you from being tracked. Most of this post is specific to Markdeep, so you may also find it useful if you have no plans to use Wordpress.
I set up the blog with very specific goals in mind. If you value the same aspects, this post may be for you:
- Convenient offline content creation
- My time for blogging is limited. If the creation of new posts and pages takes too long, I would end up not doing it. Therefore, I wanted a system that allows me to write posts offline with rapid iteration and convenient editing.
- Given my attitude towards PHP, I would have preferred a blog with completely static HTML pages. However, one feature that I care about requires some amount of server-side processing and that's comments. Receiving feedback and getting discussions going is one of the key motivations for this blog, so I cannot do without comments.
- Available server
- I already had rented a server with support for PHP and SQL.
- New domain
- To make sure that I do not bind myself to the owner of some domain, I registered a new one.
- Comments are built-in, the system is not too cluttered but just flexible enough and good themes are available. To avoid opening up security holes, I try to stay away from plugins.
Markdeep in a Wordpress framework
Setting up Wordpress is easy enough and most of the default settings work for me. It took a little bit more tinkering to use preprocessed Markdeep output as content of blog posts and pages without hurting the rapid iteration.
My first attempt was to use Node.js as suggested on the Markdeep webpage but that did not work because Markdeep does in fact require a DOM to function properly, i.e. there has to be an HTML-document in a browser window to work with.
- It surrounds the Markdeep code in the body by actual HTML code. In my case this HTML code defines the layout of my Wordpress blog to get a preview that is as close as possible to the final result. The inner-most element is a
<pre class="markdeep">tag surrounding the Markdeep code,
- It sets
window.markdeepOptions.mode="html", i.e. Markdeep does not generate the whole page but only processes the part in the
- It invokes Markdeep to turn the Markdeep code into HTML,
- It extracts the generated HTML and displays it in a text box,
- It adds an invocation of MathJax to the end of the head.
The use of this extended script is the same as that of Markdeep itself. You add an invocation of it to the end of a text file with file-format extension *.md.html containing Markdeep code. On opening this file in a browser you see the Markdeep output within the surrounding webpage followed by a text box with the code for the body. This code can then be copied easily to post it online.
There was one issue when using the unmodified code for the head. By default Markdeep uses a section numbering for all headings. However, in a Wordpress environment there are many headings (e.g. in the sidebar) which you really do not want to be numbered. Eventually I decided that the section numbering is fairly pointless for blog posts anyway. Its main purpose would be cross references but you can do those via hyperlinks. Thus, I removed the section numbering altogether. The remainder of the code for the head was then added to the header.php in my Wordpress theme.
Eliminating connections to third-party hosts
To figure out which other hosts my page references, I used the network traffic inspector in Firefox.
Of course Google was in there. By default my theme of choice used fonts retrieved from a Google server. This leads to the one plugin that I am using. It disables use of these fonts. The code looked clean enough.
Next I had to upload MathJax to my server and reference that in the head rather than using their content distribution network. Uploading the 32k files via FTP was slightly painful but worked eventually.
Finally, I tried to find some page impression counter that would not phone home but I could not find anything decent and resorted to using the analytics provided by my server. If someone has a recommendation, that would be appreciated.
The procedure for publishing a new post is not quite as automated as I would want it to be but that's largely owed to the restrictions of my server. The first step is to upload all files (images, videos, downloads, etc.) referenced by the article via FTP. It is easiest to keep the paths consistent if you enable permalinks based on the page ID in the Wordpress settings (e.g. http://momentsingraphics.de/?p=24 ). Then in the second step you create the post (or page) through the Wordpress admin panel and paste the body HTML produced by Markdeep.
Markdeep is being improved continuously. I will not update the Markdeep utility provided here with each new version of Markdeep. However, you can easily update it yourself. Just download the latest markdeep.min.js, replace the version that comes as part of the Markdeep utility and run the Python script
BuildMarkdeepUtility.py. If the new version of Markdeep makes changes to the header code, you should also open
ShowHeadAdditions.html to grab the new code.
Here's a summary of how to set up your blog the way I did:
- Perform a standard installation of Wordpress on your server,
- Choose your theme. You will need to change its code a little, so if you change the theme later, you have to start over,
- Add the following code to the <head> of your theme. It should be located in header.php. If you have installed MathJax on your server, you have to change the path accordingly. If you have updated Markdeep, just open
ShowHeadAdditions.htmlin the utility package to get the new code to add.
- Change the structure of permalinks to plain links such as
http://momentsingraphics.de/?p=24in the Wordpress settings (optional, but makes it easier to reference files uploaded via FTP),
- Optionally install a plugin to disable Google fonts.
Then to create a post and publish it, you proceed as follows:
- Download my Markdeep utility. If it suits your needs out of the box, you only need MarkdeepUtility.js. Otherwise you should edit the other files (especially PreviewBlogPage.htm) and run
python BuildMarkdeepUtility.pywith Python 3.x to rebuild MarkdeepUtility.js,
- Create a new file (named e.g. Article.md.html) next to MarkdeepUtility.js and paste the following code into it with the text editor of your choice (I use Notepad++),
<meta charset="utf-8" lang="en"> <!-- Markdeep code goes here --> <script src="MarkdeepUtility.js"></script>
- Open the file in a browser next to your text editor. If you are using Firefox, you can use the plugin Auto Reload to ensure that your article updates in the browser whenever you save your local file. It should look roughly like this:
- Write your article using standard Markdeep notation, then copy the body HTML from the text box at the bottom,
- Upload files referenced by your post (if any) to the appropriate path on your server via FTP,
- Create a new page or post in the Wordpress administration panel and fill in Wordpress meta data such as title, tags, categories, discussion settings, etc.,
- Go to text-edit mode and paste the body HTML,
- Optionally preview the article,
- Click Publish.
WordPress has built-in support for MarkDown. Seems like a lot of extra work to accomplish something that’s built-in? Including LaTeX math (with JetPack). Or am I missing something?
This feature does not really fit my needs for several reasons:
- I want to be able to write posts offline with an immediate preview of what they look like in the blog layout. Achieving this with the native Markdown support of WordPress would have taken at least as long as what I did here.
- Markdown is not the same as Markdeep. Markdeep is an extension with various features that really come in handy for me.
- I've had a look at JetPack and did not like how it sends data about my visitors to a centralized server.
This is not to say that the built-in Markdown support is bad or should not be used. It just did not match my design goals.
Comments are closed.