Welcome to the NZRT Wiki Podcast. Today we’re looking at ?? GitHub Pages.

So what exactly is GitHub Pages? Put simply, it’s a feature built right into GitHub that lets you host a static website directly from one of your repositories. You don’t need a separate server, you don’t need to manage hosting accounts, and you don’t need to worry about uptime. GitHub handles all of that for you. It’s particularly well suited for project documentation, development blogs, and public portfolios.

Let’s start with the concept of a source. When you set up GitHub Pages, you tell GitHub where to find your website content. You have a few options here. You can point it at a folder called docs inside your main branch, you can use your main branch directly, or you can use a dedicated branch called gh-pages. Whichever you choose, that’s where GitHub looks when it builds your site.

Now, speaking of building, GitHub Pages has a built-in static site generator called Jekyll. Jekyll is what takes your Markdown files and turns them into proper HTML pages. So if you’re writing documentation in Markdown, you don’t have to manually convert anything. You just write your content, push it to your repository, and Jekyll does the rest. You can also skip Jekyll entirely if you prefer to write your own HTML directly.

One of the nicest things about GitHub Pages is that deployment is fully automatic. Every time you push an update to your source branch, GitHub picks it up and rebuilds your site. You do need to factor in a short wait though. Build times typically run somewhere between one and five minutes, so don’t expect changes to appear instantly. Give it a few minutes and then refresh.

Let’s talk about your web address. By default, your site will be available at a github dot io URL based on your username and repository name. But you can also connect a custom domain if you want something more professional. To do that, you point your domain’s DNS records to GitHub Pages’ IP addresses, then configure the custom domain inside your repository settings. Once that’s done, your site is reachable at whatever domain you’ve set up. And on the security side, GitHub Pages automatically provides SSL certificates for github dot io domains, so you get HTTPS without any extra setup.

For NZRT specifically, GitHub Pages opens up some interesting possibilities. There are three potential sites worth thinking about. First, an API documentation site, which would sit at api dot nzrt dot io and could be auto-generated directly from the codebase. Second, an internal docs and guides site at docs dot nzrt dot io. And third, a development blog at blog dot nzrt dot io. All three of these could be maintained as GitHub repositories and deployed automatically whenever content is updated.

So how do you actually get started? There are five steps. First, you go into your repository’s settings on GitHub and enable the GitHub Pages feature. Second, you select your source, so that’s either your main branch with a docs folder, or the gh-pages branch. Third, you either pick one of GitHub’s built-in themes or supply your own custom HTML. Fourth, once it’s live, you access it at the github dot io URL that GitHub assigns you, or at your custom domain if you’ve set one up. And fifth, from that point on, any time you push a change to your source branch, the site redeploys automatically. You don’t need to do anything else.

That’s the core of GitHub Pages. It’s a lightweight, low-maintenance way to get a professional-looking static site live quickly, backed by the same version control workflow you’re already using for your code. For a consultancy like NZRT, it makes a lot of sense as a way to publish API docs or internal guides without adding another tool to the stack.

That’s it for this episode of the NZRT Wiki Podcast. Thanks for listening.