Hosting a DocPad Site on GitHub Pages

I am a fan, a HUGE fan, of Microsoft's Azure platform, especially their Azure Websites. This blog, has been hosted on Azure for several iterations. First as a blog on WordPress, and later, as a blog being generated using DocPad. Feel free to follow my Wordpress and DocPad adventures. Further, when I speak at events, I often say the subtitle of my talk should be "Azure, a love story". It is awesome and it is a great tool for developers.

The only thing that causes me a slight measure of discomfort is that it costs actual money to host my blog on Azure. I am fine paying money, especially for things I think are awesome, like Azure. However, my site, after migrating to DocPad is pretty stupid, it is just static HTML. Having a server for that can be a bit of overkill.

Enter GitHub.

GitHub pages

They have a platform for serving up static HTML. I think the thing that first time I had a seed planted was a blog post that Phil Haack did about moving his personal blog to GitHub Pages. In it, he steals a tweet from Zach Holman, one of his GitHub colleagues.

@haacked the ops team gets paged when is down. You still have a lot to learn, buddy

I thought that was a pretty good line. I also realize it is the same thing Microsoft does on their cloud platform, but it DID inspire me to dig a bit more into GitHub pages. At the time I looked, it was pretty focused on Jekyll, which I shied away from it based on its Ruby background (more info about my decision here ). A year later though, I have gotten a bit more comfortable with DocPad, and have a workflow to get my pages published to GitHub Pages.

What are GitHub Pages? They are public webpages that are hosted on GitHub's infrastructure. They do NOT support HTTPS, so you won't want to host eCommerce sites on it. However, for blogs and other public content they work great. You can use Jekyll, which is a Ruby based static site generator. It is similar to DocPad. One benefit of using Jekyll with GitHub pages though is that you can check in your posts into your GitHub repository and it will automatically generate the site for you.

There are two types of GitHub pages, User/Organization and Project sites. This blog, is a User site. For User/Organization pages, GitHub will take content committed to the repository, where username is a user's GitHub account. For me, this essentially means I check in my content to a the GitHub repository HTML content checked into this repository is then automatically deployed to a static site at the URL You can find out more about this at GitHubs site

It is worth noting that GitHub Pages User/Organization pages get checked into the master branch of the repository. GitHub project sites, which are for, wait for it....., projects, are a bit different. One of those differences is that they have content checked into the GHPages branch of the project.

So far, so good. However, the site has been living at a specific domain for a while, which I would really like to continue to use. Of course, GitHub pages also supports custom domain names for a site. Instructions are available online. Essentially though, it is pretty slick and quick to do. You check in a single file called CNAME (all caps) into your repository. This file should be in the root of your repository and have the URL of the site, in my case,, without any http:// in front. After committing your changes you can click settings in your repository

Click settings

and you can then verify the URL is set


We have GitHub all set to serve up our requests, but now we need to actually do some work with DNS to do that. I use DNSimmple to manage my DNS. Part of the neat things about DNSimple is they keep it simple :). There is a template setup for you to enable GitHub pages already present. It will add an Alias record for you and you are on your way


So we have a site ready to go and it is live on the Internet, but we need content! Previously, through the magic of Azure, I would check in my blog content as a markdown file, Azure would read the check ins from my GitHub repository, download appropriate NPM pacakges, compile my markdown to static HTML and publish a site. All pretty cool. That is gone now. So instead of having the cloud compile my markdown, I am now doing it all local. This is the main negative for me about moving to GitHub pages, but sometimes freedom has a cost :).

Since I will be dealing with two GitHub repositories, I reworked my workflow a bit. My site, and all of it's content and DocPad assets lives in GitHub at and my static blog content, needs to be in to get published to GitHub Pages. What I have done is reworked a couple of things with DocPad to support this. Previously, I had my repository checked out locally to a directory called What I have done is keep this as the root directory and created two subdirectories within there. The first directory, BlogSource, is the DocPad repository which will be responsible for generating my static content from markdown files. I cloned my GitHub repository here. The second directory, ghpages, is where I cloned the repository.


The next step is to be able to generate the content locally so I can push my static content from my local drive to the repository. This was done by updating my DocPad environment a bit. In the DocPad configuration file,, I created two environments, one for local development, the default way I had been using DocPad previously before, and a second for static. The static environment is what I use when I want to publish a new blog post. The main thing to note is the configuration setting for outPath, which points up a directory level from where my DocPad environment is (the BlogSource) directory and publishes files to the directory(ghpages).

I can run this command by typing docpad -e static generate. After running DocPad and generating the static content I am a commit and a push away from an updated website!

#docpad -e static generate
      outPath: '../ghpages'
      collections:   posts: ->
        @getCollection("html").findAllLive({layout: 'post'},[{date:-1}])
      outPath: '.out'
        posts: ->
          @getCollection('documents').findAllLive({layout: {'$in' : ['post', 'drafts']}}, [layout: 1,  date: -1])

So in closing, my site is no longer hosted on Azure, but GitHub pages and it wasn't too painful. I am now saving $10-15 a month. This will translate to more coffee.

A high level overview about the pros and cons.

Pros about GitHub Pages

  • Free! Azure was costing from $10-$15/month
  • Bypass some CPU usage limits on Azure

Cons about GitHub Pages

  • Cannot automatically build sites from Git commits
  • No IPV6 support (issue with Azure Websites currently)
  • No SSL support

By John Ptacek


MS Dev Podcast Show - December 19, 2014

I had the very cool experience of being invited to be part of the MS Dev Show, a Podcast focused on Microsoft Developer Technologies hosted by Carl Schweitzer and Jason Young. I enjoy the show when I get to a chance listen and, truth be told, Jason was one of the inspirations for me switching my blogging engine to Docpad. That means I was pretty excited to be invited on!

The Podcast mostly focused on AngularJS, but we talked a bit about some of the upcoming Visual Studio changes and ASP.NET vNext, which is going to be really cool for Microsoft Developers. You can get a hint of what is coming on one of my recent blog posts Running ASP.NET vNext on OS X.

You can listen to the show at Wished I would have sounded a bit more eloquent for everyone, but kind of sleep deprived.

Thanks Carl and Jason!

MS Dev Show Log Logo

By John Ptacek


Creating ASP.NET vNext application on OS X

Santa Claus is Coming to Town!! All the geeks get pretty excited for Santa’s arrival to see what will be awaiting us under the tree each year. However, sometimes the things geeks are most excited about aren’t ready for Christmas. We can read about them, maybe see some snippets or even get a preview.

For example, there is a new Star Wars movie coming, but that will not be out until December of 2015, right before Santa’s next visit. There are also a good percentage of geeks getting excited for the release of Apple Watch, which will be out sometime in early 2015, so it won’t be waiting under the Christmas tree this year either.

However, one of the things I am most interested in, workwise, while it is arriving in 2015, is available to kick the tires on now. The early preview present under the tree is running .NET on non-Microsoft platforms like the OS X or Linux. So while Santa will not be putting the final version under my tree this year, we can at least start getting ready.

November and December are always exceedingly busy times, but it is worth taking a moment to realize that something huge happened. Microsoft has opened sourced their .NET framework. I am a big fan of Microsoft’s C# language. I think, for most developers, it is a great and productive way to get work done. Having this option available on Linux and Mac machines is going to be great. Throw in ASP.NET MVC and Web API coming along too, and 2015 will be awesome one for developers.

Scott Hanselman has a blog post where he gets into the details about the open sourcing of .NET and there is a lot to get into. However, but for now, let us just build an ASP.Net vNext app and jump into it like a kid opening presents on Christmas morning!

We are going to create an ASP.NET vNext app to countdown several things… the days until Christmas, the days until the release of the next ASP (assuming Build 2015) and finally, the days until new Star Wars movie.

How do we jump in? These steps are mostly identified on the ASP.NET GitHub page (I know, crazy, right. Microsoft documenting stuff on GitHub!?!?) at We can still step through.

First, because vocabulary is important…. Since the codename for the next version of ASP.NET vNext is Katana, Microsoft is going all in with the letter K. So many of the tools utilize the letter K. A quick run through of the most important.

  • KRE is the K Runtime Environment. This is the code that bootstraps your ASP.NET vNext application; compilers, Common Language Runtime (CLR), etc.

  • KVM is the K Version Manager. It will install appropriate version of the KRE. You will be able to have multiple ASP.NET vNext runtimes and applications running on your machine.

  • KPM is the K Package Manager. This will download packages needed for your application to run.

First thing to do is ensure you have Homebrew setup on your OS X machine. If you are doing development work, you most likely have this already, so we will assume you are ready to go.

Next, we need to install the ASP.NET vNext runtime environment (KRE). This is done by downloading appropriate git repositories via a bash script.

brew tap aspnet/k

Similar commands are used for other platforms such as Linux and Windows, which uses PowerShell.

The next step is to install KVM (The K Version Manager), which is the runtime manager. It is responsible for getting the runtime and enables multiple different runtimes on the same machine. I have seen some mention of issues using KVM on OS X with different shells, like zsh. I use the Bash shell and have not run into issues. To install KVM type

brew install kvm

Next we run a script to setup our environment variables, etc


We have pretty quickly setup and downloaded the environment to run ASP.NET vNext apps on an OS X machine, but, we have no code! Thankfully, someone wrote an ASP.NET MVC Project Generator for Yeoman. Yeoman, for those of you not familiar, is a tool to generate scaffolding for your projects. It utilizes Node.js.

So to get all of this working, you are going to need to have Node.JS and the Node Package Manager (NPM) installed. Again, since we are talking developers, you probably already have all of this. The next step then is to install Yeoman, using NPM. From your Bash shell we will install Yeoman first

npm install –g yo

Next, we install the generator for ASP.Net

npm install -g generator-aspnet

Next step, since we have all of the tools we need installed and downloaded, we can generate our application. This is done by running Yeoman from the bash shell type by typing

yo aspnet

Running Yeoman, step1, choose MVC

We have the option of choosing a console application, a Web App, MVC app or Nancy ASP.NET app. We choose MVC application and provide a name

Running Yeoman, step2, choose Project Name

And our application gets generated

Running Yeoman, step3, application is generated

And we can take a look and see our directory structure, with many of the controllers and views most of us know from our MVC projects.

After Running Yeoman, step last, tree view

For those of you well versed in ASP.NET, a couple of pretty interesting things to note. First, no solution file! Second, no Project file! Most of the Visual Studio generate file constructs are gone. Similar to a Node.JS application, there is a json file outlining the dependencies needed for an application, as opposed to the Solution and Project files of Visual Studio. Very cool.

To build and run the application, we use the commands shown in the previous screen shot of the bash shell

kpm restore, which gets the packages for your application

kpm build, builds the application

k kestrel, fires up the web server to serve the pages

By using the kestrel web server we are actually firing up Mono, the open source version of the .NET framework. We access the location locally on port 5004 (http://localhost:5004/)

MVC app on OS X

So that is all kind of Christmas goodies Santa has for us, what is the most impressive programming language for business development being able to run on non-Microsoft platforms. When you start thinking about integrating in with some popular Linux tools like Docker, it doesn’t take a lot to realize things will be a lot different on the .NET stack when Santa is coming back to town in 2015. Plus, new Star Wars!

You can download this code from a GitHub repository I have setup at

Note: When running the web site, it will use the same port for the web server. I usually exit the process (k kestrel) by typing Ctrl-Z. However, I need to list the processes using PS and then kill, by typing kill -9 , the process that is mono. That way I can restart.

UPDATE (December 17, 2014) - Links updated to include link to Microsoft post on Yeoman

UPDATE 2 (December 18, 2014) - Thanks to Sayed Hashimi for helping clean up some typos with case issues.


This blog post originally appeared at Skyline Technologies as part of their 12 Blogs of Christmas series

By John Ptacek


John Ptacek I'm John Ptacek, a software developer for Skyline Technologies. This blog is my contains my content and opinions, which are not those of my employer.

Currently, I am reading Revival by Stephen King

@jptacekGitHubLinkedInStack OverflowGoogle+