GitHub pages is a blessing to get a simple website up and running without much fuss. For example, library documentation, which quite often is a mess in the corporate world, can be made much easier with GitHub pages. GitHub and GitHub pages lower the threshold to maintain documentation and include in the development team’s task list.
There are many options when it comes to the technology to build such a website. Static website generators such as Docusaurus, Jekyll, Gatsby and Hugo are great tools to design a modern and easy to maintain website. For example, docs.dimescheduler.com is built with Docusaurus. Converted into a physical book, this website would span well over 250 pages. Without such a static site generator, it would’ve been a full-time job just to write and maintain the docs.
Obviously, it doesn’t stop with documentation pages. For example, I have made a slide deck using a simple create-react-app and Webslides. While it is available on intro.dimescheduler.com, it is actually hosted on GitHub pages, which brings me to today’s topic. While GitHub pages’ docs are pretty good, I was struggling in one certain area. When I deployed the React app’s build directory to GitHub pages and added a subdomain, the static site couldn’t find the style sheets and scripts. Turns out that the solution was pretty simple.
The “homepage” field in the package.json is not merely informative. Set this field to the URL you want to use in production and the build process will set the path to the correct value. In my repository, this will be intro.dimescheduler.com. The value should correspond with the value you entered in the custom domain field in the repository’s settings custom domain section
Other than that, the deployment process is surprisingly simple. Below you can find a part of the package.json file, where you’ll see there is only one extra dependency: gh-pages. I added a script called “gh-pages” which will basically drop the output in the build directory to GitHub pages. The other script, “deploy”, builds the application and calls the gh-pages script.
{
"homepage": "http://intro.dimescheduler.com",
"scripts": {
"start": "react-scripts start",
"build": "react-scripts build",
"test": "react-scripts test",
"eject": "react-scripts eject",
"gh-pages": "gh-pages -d build",
"deploy": "yarn build && yarn gh-pages"
},
"devDependencies": {
"gh-pages": "^3.1.0"
}
}An Azure Pipeline, which runs automatically after each push to the repo, merely invokes the deploy script. Nothing should stop you from using GitHub Actions instead of Azure Pipelines. I would actually recommend it because that would make the circle complete: host the code, build and run the site on GitHub.
That’s all there is to it, really. The only caveat I still have figure out is that after each deployment, the custom domain is cleared, forcing me to set the value manually. No doubt there is a solution for that, but I haven’t found it yet.
