As promised in one of my previous posts, I am sharing the background about how the documentation pages were created on the new SpecFlow website. The story starts in 2000 (quite some time ago, bah…) when someone called me (did I have a cellphone already? I don’t remember…) and asked me to fly to Stockholm on the following day to fix a website for a TV show that was about to start in two weeks. In PHP. I was in the 2nd semester of my MSc and did a lot of perl coding. In fact I  programmed everything in perl that time… so was quite hooked on it. I had never done anything in PHP until that time, but saw that it was pretty similar to perl, so I printed the PHP documentation and sat on the plane. We fixed (better to say built up from nothing) the website, so the show could start, but I have never done a PHP job anymore. Was enough. 13 years later, I somehow felt a kind of nostalgia (one of the most dangerous feelings one can have), when we picked WordPress as the CMS for the Spec* toolset. And I felt that I have to do some code into it…

I disliked using the github wiki as documentation, because it is too hidden, there is no good way for providing a hierarchical navigation across the pages, it’s slow, it uses https (that seems to be a disadvantage for search engines) and finally, you cannot get any feedback about the usage (what pages are more frequently visited, etc.). On the other hand, the collaborative editing and the simplified formatting options are very good, still. So with the new website, I wanted to make something that keeps the good stuff but avoids all the bad stuff (easy, isn’t it?).

The strategy is simple: let’s keep the editing in github wiki, but mirror the content and embed it to the website.

And this is how you can achieve this.

Preparation and mirroring

Are you eager to type the $ sign already? Hold on. We need to do some preparation work before.

1. You need to have a self-hosted WP site at a hosting provider that supports SSH access.
2. You need to conjure an executable git onto your account. This is pretty complicated, because it depends on the exact server OS and you need to configure a few environment variables for the shell (bash in my case). Unfortunately I don’t fully remember how I did that, but I’ll try to figure it out if you really need it.

3. At this point, when you call “git --version” from your shell, it should write out the version number (1.7.11.3 in my case). Git is anyway very useful for managing WP sites. But this is another post…

4. You have to clone the wiki repository to a folder inside the WordPress installation:
   git clone git@github.com:you/yourproject.wiki.git doc
5. After this, calling the “git pull” command should not ask for anything but report that the repository is up-to-date. Let’s schedule the synchronization!
6. You need to make a small shell script that automates the repository pull. Due to the rules of scheduling, this script will not inherit your user settings automatically, so we need to do this ourselves. My script looks like this. Not very sophisticated, but it works. (Don’t forget to mark it executable!)
7. Finally you have to schedule a (cron) job to run this script every hour or so. This depends on the hosting provider, for some you need to do it from the web administration interface.
8. If you did everything well, you will see a growing logfile and an up-to-date repository inside the “doc” folder (that no one sees yet).

Ok. That was enough of unix magic, let’s do some PHP coolness now!

Embedding the wiki content to WordPress

Actually we need to do three things here:

1. Convert the wiki format (Markdown) to HTML
2. Handle the table of contents (TOC)
3. Embed the result into the website

There are thousands of ways to do this (welcome to WP). Finally I have used a combination of a wordpress plugin and a special page (a wordpress page with a special template). When somebody requests a page like http://www.specflow.org/documentation/Configuration/, the plugin translates this (with a rewrite rule) to “http://www.specflow.org/documentation/?docpage=Configuration” (to be precise, it is “http://www.specflow.org/index.php?pagename=Documentation&docpage=Configuration”, but that’s just a WP detail). The special documentation page (through the template PHP file) takes the “docpage” argument and tries to match it to a wiki page file inside the cloned git repository. In our case above, this is the “Configuration.md” file.

Then we read the file and transform the Markdown format to HTML. For this I use the “PHP Markdown & Extra” plugin by Michel Fortin. This plugin does a great job, but some github (like code snippets) and site specific (links) post processing is necessary that I do with regex.

In addition to the requested wiki page, I do same transformation for the table of contents file as well. This is also a wiki page, called Documentation-TOC.md. So in the end I have two HTML snippet: the actual documentation content and the TOC. Of course all of these are free of HTML styling, that is provided in a separate CSS file.

The wordpress template takes these parts and places them into the appropriate HTML sections that are formatted as TOC and page content with the site stylesheet. It also puts a link to the original github wiki page, if someone wants to fix mistakes.

And that’s it! The code is not a rocket science. The plugin that contains the core logic is about 200 lines. But it works (or at least it seems to) and I’m finally filled up with PHP coding for the next 13 years…

PS: Do you need the bits? You are already filled up, right? OK, I’ve got it. Drop me an email and I’ll send a copy.

PS(2): Yes, you see “vi” on the screenshot. This is part of the feeling. You don’t want to do PHP coding in Visual Studio, do you? What!? You even develop it on your windows dev box with WebMatrix?  Oh no…