Building a simple & beautiful documentation site

With Seriously Simple Podcasting crossing 35,000 downloads and v1.8 of the plugin being released recently it was high time that I put together complete documentation for it. After spending some time building the site that you can now find on my new docs subdomain I thought it would be valuable to share the tools I used for posterity. So here you will find the theme and plugins that I used to get my docs site up and running.


As with any custom design I embark on, I used Canvas by WooThemes as my parent theme. I’m not much of a designer, so I find Canvas to be a great substitute for my lacking design skills. The design and typography options do wonders to make someone like me look like they know what they’re doing with design work.

For my typography I went with Ubuntu for the headings, Open Sans for the body text and Droid Sans Mono for the inline code.

Seriously Simple Podcasting Docs Homepage So, with Canvas as the parent theme, I built a custom child theme to cater for my needs. You can download that child theme from here if you like (it includes the theme settings export file), but it obviously contains a number of customisations that would be unique to my site. It also requires the plugins I used to make this site a reality.


With the theme taken care of I could now look the plugins I needed.


To start off with I looked around for a decent documentation plugin and, having found nothing workable, I was about to start writing my own one when Emili Castells got in touch with me about his new plugin, Docu. Docu is a simple and flexible documentation plugin that doesn’t add any extra bloat or overhead to your site. It comes with a new custom post type and taxonomy for creating and categorising your docs as well as nicely designed templates (that you can override from your theme) to help you display your docs easily.

I added a small amount of custom styling and logic to the display, but other than that Docu effectively works very well right out the box.

Table of Contents Plus

A necessary feature for any docs site is a table of contents on each document. For me, the best table of contents plugin I’ve ever used is Table of Content Plus. It gives you a number of options for how to display your document contents, but all-in-all it’s a very easy plugin to use that requires only minor configuration to get working.

Screen Shot 2015-02-10 at 10.14.37

oEmbed Gist

As this is a documentation site that includes developer docs, it’s necessary to show code snippets from time to time. One of the best ways to do this is to store your snippets on GitHub’s Gist as it makes them public and easily discoverable. The next step is to embed them in your site content, which unfortunately WordPress doesn’t natively support. Enter oEmbed Gist – just install the plugin and pasting your Gist URL into your content will generate a neat oEmbed of the code.

Pro tip: I use GistBox to create and manage my Gists – it has a great UI and makes team collaboration much easier.


WordPress’ built-in search has always been mediocre at best and there are a lot of plugins out there that are built to enhance the search experience in WordPress. My favourite of these plugin is Relevanssi – with a few simple options you can boost your site’s search effectiveness by leaps and bounds. This is incredibly important when working with documentation as the search is often the first port of call for many users.

An added bonus with Relevanssi is that it allows you to track your user’s searches so you can see what search terms are the most common.

Testimonials by WooThemes

There are loads of plugins available for adding testimonials to your site, but my favourite is definitely Testimonials by WooThemes – it’s especially useful if you’re using a WooThemes theme as it integrates smoothly with the design of your site. The content for the testimonials is all copied from the plugin reviews on the repo.

Screen Shot 2015-02-10 at 11.14.17

Acknowledge Me

The final plugin I used is the handy Acknowledge Me plugin by the guys behind the Pods Framework. Because Seriously Simple Podcasting is an open-source plugin that has had a couple of different contributors help to make it more awesome, I thought it would be good to acknowledge them on the docs site. Acknowledge Me displays all of the contributors to a GitHub project in a neat grid with avatars and contribution counts – all I needed to do was some minor CSS changes to have it fit into the design of my site more effectively.

Screen Shot 2015-02-10 at 10.17.41

And that’s all there is to it. All of those plugins are freely available from the WordPress plugin repo so getting all the functionality you need for a docs site won’t cost you a cent and, while the theme isn’t free, it’s well worth getting a Canvas licence for all of your custom design needs.

2 thoughts on “Building a simple & beautiful documentation site

  1. Hi Hugh, I found your site through Support forums, and I’m contacting you because I have exhausted all other options. I am having trouble with my podcast showing up on my blog posts. This is a new issue, as I’ve posted 99 podcasts before, and now all of a sudden I do the same thing and the audio player does not show up. If you can help me out I would appreciate it, and if not, if you could point me to someone trustworthy, that would be fantastic.

    Thank you,

    Frank Marcopolos


Leave a Comment

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

You are commenting using your 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 )

Google+ photo

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

Connecting to %s