Roll your own static blog engine (Part 1)

Project layout and hosting with git

As the first tech post here, I figured a natural choice would be a walk through on how I make and host the site itself. There's a bit much to try to cram into one post, so this will be the start of a short series on my development and publishing process.

I create and host this blog completely for free using a number of open source tools for site generation and GitHub pages for static hosting. Creating a site this way works really well for any static site---that is, one that doesn't rely on server-side scripting or databases (though, I do plan on writing about how to add in those capabilities in a future post)---and should scale well to even large traffic volumes.

Project layout and git setup

For a web project that's going to be published to a static site host, we'll need a directory for the source files and a directory for the generated html, css, and other content that is uploaded to the server. I don't suppose there are any canonical locations for these, but I've found putting the source directory inside the output directory works pretty well. I'm sure the inverse would be just fine too. Including directories for css and javascript, a boilerplate project layout for one of my sites might look something like this:

./sitename.com/
	- index.html
	- script/
	- src/
		- index.pug
		- script/
		- style/
	- style/

The simplest way I've found for handling version control here is just to create two separate git repositories. The first one in sitename.com/ will be for pushing content to the server. The second in src/ will be for actually versioning the work you do on the site. It is arguable that you should just use one repository since the content of sitename.com/ is directly related to src/, but after hacking around on that for too long, I found it way simpler just to use two repos.

So, to get started:

$ cd /directory/where/you/put/web/projects/
$ mkdir sitename.com
$ cd sitename.com
$ git init

This creates your site directory and initializes a git repo inside. Next, we'll create the src/ directory and ignore it:

$ mkdir src
$ echo "src" > .gitignore
$ git add .
$ git commit

This keeps your pre-compiled source from ending up hosted to the public and allows us to create a second git repo in the src/ directory:

$ cd src
$ git init
$ touch .gitignore
$ git add .
$ git commit

We now have two independent git repositories to hold both the source code/markup and the resulting generated content for the site. If you don't otherwise use git, you may need to set up some configuration variables like your name and email address:

$ git config --global user.name "Your Name"
$ git config --global user.email "email@host.com"

I also set the user.signingkey and commit.gpgsign options so I can use my Yubikey to sign commits with GPG, but that set up may have to be it's own post someday . . .

Hosting

Now that we have a git repository set up, we need a place to push it to. I use GitHub Pages for hosting this site, as it's free for static sites and easy to publish to with a simple git push command. There are plenty of other options, from dedicated services to running your own servers, but I find GitHub offers a nice balance of practicality with free-ness and keeps me from having to worry about uptime.

Create a new repository from your GitHub account and give it the name of your site. Then set the GitHub repo as upstream to the build repository created earlier:

$ git remote add origin git@github.com:<username>/<reponame>.git
$ git push -u origin master

Make sure to do this from the sitename.com repository, not the src repository, as we want to keep that private. Now we can commit a couple of files and push up to our new host. Here, the CNAME file will help with pointing a domain name at the site in the next step.

$ echo Hello. > index.html
$ echo www.sitename.com > CNAME
$ git add .
$ git commit
$ git push

On the GitHub repo's settings page, go to the Pages tab to configure how your site will be served. Choose the branch you want to serve from (probably master) and set the custom domain field to your domain if it's not set already.

Enable the Enforce HTTPS option if you're serving directly from GitHub, or you can leave it blank if proxying through something like Cloudflare. This is a newer option for GitHub Pages. When I first set up the site, this wasn't available, and the only way to get HTTPS on a custom domain was to proxy traffic through a CDN like Cloudflare to allow/force secure connections.

At the registrar for your domain name (or wherever the DNS server for your site is), add two CNAME records to point to the GitHub repo. First, add a CNAME record to redirect sitename.com to www.sitename.com. Then add a second CNAME to point www to <yourusername>.github.io. GitHub can then use the CNAME file we committed earlier to direct requests to the appropriate page. Now (at least once the DNS settings have had time to propagate), you should be able to type your domain name in a browser and see the Hello text from the index.html page in the repository.

From this point, it's all about creating your site however you want. Whenever you want to publish your updates, all you have to do is

$ git add .
$ git commit
$ git push

In future parts of this series, we'll get more into the site creation itself, including HTML templating with PugJS, build automation with Make, and RSS feed generation with Python.

Comments for this post are on the /r/openquestion subreddit.