The Technology Behind These Articles

I make it no secret that I use GNU Emacs for everything: programming, project management, writing emails, calculations (using M-x calc and its awesome features), and of course, writing the articles for this blog. However, I do not write any of these articles in HTML. So today I decided to briefly explain my process and the programs that I rely on to publish this content.

I was a professional web programmer for some years, but since I left that industry I have stopped writing HTML. Nowadays I prefer to write documents in a more readable format. When I say ‘readable’ I mean the content is just as easy to read in plain-text as it is in HTML. For example, this is how I typed yesterday’s article. That is easier for me to read and write than a bunch of HTML tags.

That specific format is Markdown. Its goal is to be an easy to read and write text format that you can convert into HTML. The official site provides a program to perform that conversion. But I do not use it. Instead I prefer to use Pandoc. It calls itself ‘a universal document converter’, and it lives up to the claim. Pandoc converts every format I use to every other format I use, and then some. It’s an awesome and useful piece of software.

Thanks to Pandoc I can write my articles in the Markdown format and then convert that to HTML I can copy-paste directly into WordPress. Now even though Markdown is a simple format I still want support for it in Emacs, even if it is only syntax highlighting. Thankfully markdown-mode provides a lot more than that. It makes it even easier to write these articles in Markdown by providing shortcuts for creating links, blocks of code, things like that.

I keep all of the content for this blog in a Git repository. There you will see two directories: drafts and content. All pages are in the drafts folder, in the Markdown format. The HTML versions that I post here are in the content directory, but you will notice none of them appear in the repository. That is because I have no reason to track changes to the HTML versions. Since I can regenerate them at any time with Pandoc I only commit changes to the drafts.

Inside of that content directory is a Tupfile. That is a file for the Tup build system. It helps automate the process of converting the drafts to HTML. Tup also tracks changes to drafts so it will recreate older articles as needed, e.g. if I fix a typo. So when I finish writing an article I go to my terminal and do the following:

$ cd ~/Projects/EricJMRitz-WP/content
$ tup upd

That populates the content directory with HTML versions of every Markdown document in my drafts directory. After that all I have to do is go into the WordPress dashboard, create a new post, copy-paste my HTML, and I’m done!

I realize that this entire workflow is not for everyone. However, there are a lot of other good uses for these programs. For example, I have found the combination of Markdown and Pandoc to be wonderful for creating software documentation like this. The markdown-mode package for Emacs is useful not only for this site but also when I am writing email for Thunderbird, where I use the Markdown Here add-on. Git is the best version-control program I have used; I’ve used it to manage the source for my projects for years now. Tup has become my favorite build tool, so much so that I wrote an Emacs package for Tupfiles.

So even though I expect no one to adopt my specific workflow for writing these blog articles, I do believe a lot of you can find a good use for these programs, whether it’s Pandoc for documentation or Tup for building your software. Check them all out and see if any help improve your workflow.


Add Your Thoughts

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )


Connecting to %s