I’ve been working on this app spec for weeks at work. In an effort to improve on what I’d accomplished, I reached out to my friend, and one of the smartest people I know, Peter Becan. I wanted him to teach me how to do it right. Peter’s been doing this sort of thing for a lot longer than I have, and has a particular knack for it. Learning to correctly prepare an application specification is harder than learning to program, IMHO.

As my spec writing progressed, I’d email Peter PDF output from Scrivener as I accumulate enough new content worthy of a dispatch. marked, which I’m using to preview MultiMarkdown markup in my Scrivener document, generates the formatted PDFs. I realize that as time progresses, keeping Peter in the loop requires a different method. In order to keep him informed, and not have to email him a new PDF every so often, I needed to make use of the web to post the formatted output.


Scrivener supports outputting HTML generated by the MultiMarkdown processor as a Compile For target. There are instructions on how to use MultiMarkdown with Scrivener here, however the instruction appear out of date. I’m using Scrivener 2.2 and some of the preferences mentioned in the instruction have either moved, or no longer exist. Luckily, by setting options using MultiMarkdown metadata and a simple change in the compile settings, I obtained the necessary output.

For posterity’s sake, what I did not find was MultiMarkdown Settings… under the File menu

Two things are necessary to produce the desired output for inclusion in a WordPress page. First, as mentioned in the instructions, I had to enable the exporting of Titles for both Documents and Groups within Scrivener. You do this by checking the check box under Title in the Formatting options of the Compilation Settings sheet.

Format Settings

Second, I opted to use a Meta-Data file at the very top of my Scrivener doc to coerce the MultiMarkdown processor to produce the necessary output. The metadata fields that I use are:

Title:  Contractor Spec   
Format: snippet  

The key is the Format field. What that does is instruct the MultiMarkdown processor to only create the HTML for the given markup and not an entire XHTML page. Clearly if I am including the output in a WordPress page, only the HTML associated with the MultiMarkdown markup is necessary; the cruft associated with a well-formed XHTML page (i.e. HEAD, BODY, etc.) would be in the way. With all the correct metadata and settings in place, I use Compile… with a Compile For of MultiMarkdown -> HTML and save that in its own subfolder within my source tree.


Git. Love it or hate it, it’s the linchpin in the operation. My Git repo resides on the same server as my WordPress installation. Having that scenario started me thinking about how I would get the HTML snippet residing within the repo into a place that I could serve just that content and not the entire source tree. I started Googling update website with git, and sure enough I found what I was looking for. After sifting through several top results, I found that this was the best answer.

I have an addendum to those instructions. For the remote path, I used a file:// path pointing to the path of the real repo on the server. Found that here.

The key to copying the HTML to a place I can include it from is using a post-receive hook in Git. Very simply put:

The post-receive hook runs after the entire process is completed and can be used to update other services or notify users. (taken from Pro Git)

However, if you follow the steps set out in the instructions, you’ll wind up with your entire repo in the web directory. While that may work in most cases, it was not ideal for what I was trying to do. Next pass at Google had me looking for ways to only checkout a subset of the entire repo. The key to that is something entitled a sparse checkout. I used the steps outlined here to only checkout the folder (and it’s content) that contained the HTML snippet. One exception however about the sparse checkout instructions, you will need to include a ‘*’ at the end of the path. Otherwise you will receive from Git:

error: Sparse checkout leaves no entry on working directory

For my “local” repo on the server, I picked a spot outside of the root of the WordPress installation to checkout the files to.


Last step in the process. How do I insert a snippet of HTML that resides on disk into a WordPress page? Create your own page template and use a custom field. In the end, this was rather easy, once I learned how to do it. This page at the WordPress codex explains how to create the custom template and where to upload it to your server. Scroll down a bit till you get to the Using Custom Fields section. For this, I’m using a custom field called doc_path. Here is my custom template named docs.php:

 Template Name: docs
if (is_page() ) {
$docs_path = get_post_meta($posts[0]->ID, 'docs_path', true);

        <div id="primary" class="span8">
            <div id="content" role="main">
                <?php include($docs_path); ?>
            </div><!-- #content -->
        </div><!-- #primary -->


This allows me to specify the full path to the HTML snippet on disk that I want included in the WordPress page.

Custom Fields

Make sure, as I forgot this the first time I saved my new Page, to set the template for the Page to your custom template like this:


Final Output

Because the application I’m writing the spec for is proprietary, I can’t share the real fruits of my labor with you. However, what I did do is create another page containing a snippet of sample.html from the MultiMarkdown source at github. My sample page is here. P.S. Yes, I am aware that the sample page has a broken image link.

As I mentioned in my earlier post, the comment spam came in right away after installed WordPress. Now, that’s not to say it was WordPress’ fault. I guess I just didn’t notice them before with Movable Type. Anyway, I simply installed the Disqus plugin. Do understand that I’m not endorsing Disqus; I installed it, and it works.


Today I migrated the site off of MovableType and onto WordPress. I had been wanting to do this for quite some time. The hurdle I had to overcome was porting the data from MovableType in such a way that permalinks wouldn’t 404. The first import utility I tried didn’t maintain the entry IDs stored in MovableType. At that point, it wasn’t important enough and I left it alone. I came back to it today, months later, when I went looking for a MovableType theme based on Twitter Bootstrap. When I didn’t find what I was looking for in MT, I found it in WP. Now I had to find a way to get the data across.

Movable Type Backup Importer

I found this plugin in the WP plugins directory. First thing is it used the actual XML backup file created by MT when you select backup and not just export. I had to fix a few ilegal characters that were in spam trackbacks before the plugin would import the data because the XML was invalid. I used a combination of Sublime Text 2 and Firefox (yes, I’m a Chrome user but Firefox does a more explicit job of pointing out errors in an XML doc) to clean up the XML. As for spam, I didn’t bother cleaning it up. I’m confident that the comments on the blog are mostly clean, and I don’t think trackbacks are were all that important.

Once I imported the data, the same issue persisted from the first time I attempted a data import; the IDs were reset on import. So, first thing is I touched base with the author of the plugin, rogerdudler. I then went off on my own to see if there was a way to allow this to work. As it turns out, there is. On line 2582 of wp-includes/post.php, the code comment was clear:

// If there is a suggested ID, use it if not already present

Armed with this new found knowledge, I went back to Roger’s plugin, and added

$post->import_id = $id;

after line 407. That was it. I used another plugin, WordPress Reset, to flush the database. The second import worked like a charm. The WordPress Post IDs matched the MT entry IDs. Almost done. WordPress is dynamic, and MovableType is static. Now, .htaccess and mod_rewrite to the rescue, and a setting change in WordPress, which I’ll get to in a second. Here is the .htaccess file

RewriteEngine on
RewriteRule ^archives/0*(\d+).html$ /archives/$1 [R=301,NC,L]
RewriteRule index.rdf /index.php?feed=rdf
RewriteRule index.rss /index.php?feed=rss
RewriteRule index.xml /index.php?feed=rss2
RewriteRule atom.xml /index.php?feed=atom

# BEGIN WordPress
<IfModule mod_rewrite.c>
RewriteEngine On
RewriteBase /
RewriteRule ^index\.php$ - [L]
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule . /index.php [L]

# END WordPress 

The first part is what I added, the latter being programmatically generated by WordPress. The setting change came in Settings>Permalinks. I changed the setting to Numeric in order for the links to be similar to MT, and I prefer a flat, static looking permalink. It seems more SEO friendly. After that setting change, everything appears to be working correctly. For example, if you Google “Avistar Sucks” the link is the old MT style until Google updates my permalinks. Clicking on it redirects you to the WP entry. By the way, did you notice the use of R=301 in the rewrite rule? By default, mod_rewrite would issue a 302, which is a temporary redirect. Search engines do not care for 302s. They want to see a 301, which is a permanent redirect. I learned about the 302/301 issue here. Let’s just hope I don’t mess up years of search rankings.

Markdown on Save Improved

While in the process of writing a spec for an app I’m developing at work to interface between SedonaOffice and eOriginal, I grew an affinity for using Markdown syntax. I use Scrivener to collect my thoughts, and then I can export to MultiMarkdown (a superset of Markdown). The ease of use is a huge effort saver. With that, I went looking for a Markdown plugin for MT, and I wasn’t happy with what I found. What I did find for WP was Markdown on Save Improved. It works well. As I understand, this plugin stores the Markdown and the HTML in separate columns so the Markdown->HTML occurs when the post is saved, and not for each request. Much faster that way.

The Bootstrap

My search for a Twitter Bootstrap theme let me to this one. It installed in a flash, and is using the reactive stylesheets. One quick install and my blog is all good for desktop, mobile, and tablet.


Just as an aside, since I went live about 30 minutes ago, I already have spam comments to moderate. Oh boy.

We ordered J a My Twinn baby on Septmeber 6, 2003. I would ceratinly think that they would have enough time to deliver it by the holidays. So, no doll by Thanksgiving. I call. I am informed that the company no longer makes their dolls in Denver, but in China. Um, ok. J’s doll was shipped regular mail on November 19, 2003 from China, and should take 6-10 business days to arrive. Ok, now, I’m no authority on the postal service, but it can take 6 days for an envelope to get to the other side of town. I’m not believing the very apologetic lady on the other end of the phone, but I am assuming that it will arrive by mid December. Second week in December arrives, no doll. I call and sit on hold, no one ever answers. I tell David that at this point, I am sure that we will never see the doll and I need to call the credit card company. I am also sure that the company is done. This morning I go to the site and read their heartfelt letter.

So, yes, it appears they are done. It also appears that they are liars. In a news release they state that all orders received by December 7th will be received by the holidays. Yeah, right, our September 6 order has yet to arrive. They blame their downfall on September 11th. This is the 3rd holiday season since then. They moved their facilities overseas. But, the problem is September 11th?

I want my kids fucking doll.