After seeing a post on the github blog about David Baldwin using github as his blog I got to thinking about how much easier it would be to create my markdown posts offline and then commit them to some repository and have them show up as blog entries.

The comments for the github entry point out a number of people using various solutions to achieve an effect similar to what I want however I am somewhat loathe to give up on a web interface in general and Wordpress in particular. But this did get me thinking, what about a post-commit hook so after every commit a script examines the changed files and creates or edits posts as necessary. Google didn’t turn up much of anything in the way of making this happen and so I started thinking about how I would write my own solution.

As of right now I’m just in the planning stages but I did realize it would have to be a pre-commit hook on account of wanting to track the post id somewhere and the most logical place seems to be as some meta information at the top of the post. Currently I have the pre-commit hook reading the information I need to send about the post out of the file, the next step will be to figure out creating an XML object to send to the xmlrpc.php file of my Wordpress installation. In addition to dealing with hooks and xmlrpc¹ I’m writing the script using Perl in order to get some hands on experience with it.

I’ll admit I’m not 100% sure I can make the script do what I want it to do but I’m certainly going to give it a shot because looking at the solutions eluded to in the comments of the post on github there doesn’t look to be a solution to satisfy me yet.

My initial planning has the username, password and xmlrpc url being stored as config options via git config username|password|xmlrpc while post related information is stored in the actual post file. I think the most likely hang up will be modifying the file which is about to be committed (by adding the post id) because I believe I’d actually have to create the post via xmlrpc, write the response into the file, stop the commit, add the post file back to the index and re-commit. There may also be a problem with the way xmlrpc expects the categories.² Time will tell.

I’ve been working a great deal with JavaScript Objects which are used purely to store data but which need to be performantly converted into HTML code blocks. In order to achieve this I created a function which searches for specific delimiters and replaces the delimiters with the Object’s property of the same name.

The code to do this is fairly straightforward:

/* This code is released under a MIT license */
String.implement({
	template: function(props) {
		var regex = /%(\w+)%/g;
		var newStr = this.replace(regex,function replacer(mid) {
			var key = mid.substring(1,mid.length-1);
			var value = props[key];
			if (typeof value === 'string') {
				return props[key];
			} else {
				return '';
			}
		});
		return newStr;
	}
});

Using this function I can take a snippet of HTML and a JavaScript Object containing replacement information and easily turn the snippet into a useful String for user with the innerHTML property. For example, starting with the following HTML

<div id="template">
	<div class="test">
		<p>%testName%</p>
		<p>%testDescription%</p>
	</div>
</div>

I can execute this simple piece of JavaScript and get a useful HTML. The JavaScript and HTML output follow.

var newHtml = $('template').get('html').template({
	'testName': 'This is just a test',
	'testDescription': 'Please do not be alarmed this is a simple test'
});
$('template').set('html',newHtml);

The HTML will now look like the following

<div id="template">
	<div class="test">
		<p>This is just a test</p>
		<p>Please do not be alarmed this is a simple test</p>
	</div>
</div>

I’ve found this technique to be incredibly useful. Hopefully someone else will as well.

Recently I started using PHP Markdown Extra in order to format my posts. I decided to make the switch mostly because I find writing Markdown slightly more natural than writing HTML; more than that though I find reading and editing posts I’ve previously written using Markdown to be as easy as reading a regular word document or a book. Of course, the readability of Markdown text was sort of the point of the syntax so my observations seem a touch obvious. The crux of my point stems from my reasons for switching so it felt necessary to elucidate my position.

Through the course of learning the Markdown Extra Syntax I found it supported footnotes, for me this was exciting because I have a tendency when writing to have a lot of tangential thoughts. I usually¹ use parentheticals to capture these ancillary musings but I have noticed this tends to detract from the primary issue during reading. Clarity is something I strive for when writing² and so I figured it would be better to store my tangents away from the rest where they wouldn’t detract from the point I was trying to get across.³

I jumped into using footnotes with both feet and had soon written two posts⁴ making liberal use of footnotes. Upon inspection of the posts on the front page I noticed the references didn’t behave correctly. After some brief investigation I discovered the ids were the same for every set of footnotes which was frustrating for a couple reasons.

1. The footnotes aren’t much use if they don’t actually work
2. Duplicate ids means the document won’t validate, which makes me sad.

I immediately descended on the problem in an attempt to rectify the situation. To make a long⁵ story short I ended up creating a SHA1 hash of the footnote’s text and using it as an identifier for the references and ids. This works quite well for my purposes since it seems fairly unlikely I’ll be using the same footnote text over and over again⁶, however there are some pretty obvsious weaknesses to this strategy, which I’ll outline below. But first I wanted to provide a downloadable patch of the changes I made in order to make this footnote stuff work: you can get the Wordpress Friendly Markdown Footnotes patch and apply it in order to get this working for yourself. I created the patch using git, so if it proves difficult to apply let me know in the comments or via one of the contact methods on my about page and I’ll fix it up lickity split.

Now about those weaknesses; the major problem comes about if you want to use the same footnote text a couple of times. I could see this coming about more on a site publishing research papers than here but that isn’t the point. A better method would have been to use the Wordpress post id via <?php the_ID(); ?> because then the footnote references for the post are all constrained by a shared value. This was in fact my first idea but it seems core Wordpress loop functions are not available inside filters. This made me wonder if perhaps there wasn’t another way to get the post id, either from a filter argument or from some other magical place. Needless to say I couldn’t figure another way out or I would have used the post id method instead. Another issue, though I guess it’s not really a weakness, is the SHA1 makes the references a bit long and unsightly, not to mention meaningless. However, I was just happy to get the thing to work.

That is all for now, I’ll post updates if I make any improvments or changes.