areed.me

Creating a home for my projects

Motivation

I like to make things in my spare time, and over the years I've worked on quite a few home projects of varying complexity. Regardless of the project, my attempts at documenting what I've done have always been patchy. I've ended up with some write-ups scattered accross the internet, as competition entries or GitHub readmes, but most projects have not really been written up at all.

With the founding of this website, I'm hoping to change that. I intend to use it as a place to collect informative writeups on my work, initially from past projects and then as an ongoing process for anything I work on in the future. This will most likely be mainly for my personal benefit, both as a useful reference for my future self and because documenting work can be a valuable experience in itself, but hopefully some of the information that ends up on here will be useful for any like-minded souls who come across it in future too.

Design

Given that the material I post is likely to consist almost entirely of basic text and images, only a simple site should be required to host it. I've therefore elected to construct this website as a static site for simplicity. For this task I've chosen to use the popular static site generation tool 11ty. There is plenty of documentation available for this, as well as a wide range of example projects that can be used as a starting point. However, rather than build upon one of these I decided to try assembling the site from scratch in order to better understand how it was put together.

11ty supports several templating languages that can be used to create pages, however most of the examples in the 11ty documentation, as well as their simple example project, seemed to use Markdown/Liquid and Nunjucks so I chose to do the same. Nunjucks is used for the page layout templates, and for the pages with material generated by 11ty (home, tags, all tags). The posts themselves are written in Markdown, with a small configuration header to aid integration with 11ty.

The end product has turned out fairly similar to the official blog starter project, which isn't hugely surprising as I made heavy of use this as a reference while developing mine. There are some differences though, most notably in the pagination of posts on the homepage and tag summary pages. Below is a summary of the main features of the site:

• Navigation bar with links to main site areas, generated by 11ty
• Homepage with generated list of posts sorted by date
  • Paginated with next/prev links
• Posts written in Markdown
  • Template provides consistent formatting and ties into 11ty
• Post tags, with generated page for each tag collating all posts sharing that tag
  • Tag collation pages also paginated with next/prev links
  • This actually requires "double pagination" as tag pages are themselves generated by pagination in 11ty
• Simple css styling

Using Markdown for the important material, i.e. the posts themselves, should make it easy to transfer to other platforms if I decide to redesign the site at a later date as it is very widely supported. Additionally, Markdown is designed to make writing formatted text for web pages as intuitive as possible, so it is very easy to use. This is particularly important, as keeping the effort required to write posts as low as possible will give me the best chance of succeeding with this site!

Hosting

The setup used for hosting this site has also deliberately been kept as simple as possible. The 11ty project that generates the site is on GitHub, which grants access to free site hosting via GitHub Pages. This can use the root directory, or a subdirectory called docs, of any branch of the repository as the source location for a GitHub Pages website.

The root directory of this project isn't a suitable GitHub Pages source, as the 11ty template files confuse it, so I've instead configured the repository to use the docs folder for this. 11ty has also been configured to use this directory as its output folder, instead of _site. Although the directory name doesn't make much sense for this usage, the alternative would be to host the site from a separate branch. This would make the process of updating the site content significantly more involved, so I'll live with the slightly strange directory naming instead.

My GitHub Pages configuration can be seen above. By default, when enabled the repository's GitHub Pages site is hosted on a github.io domain. However, as can be seen in the screenshot I've configured my repository to use the custom domain areed.me instead. After purchasing the domain name through Google Domains, it was straightforward to set this up as the custom GitHub Pages domain by following the instructions in the GitHub documentation found here.

Briefly, the process is follows. Firstly, add the custom domain through the GitHub web interface. This creates a CNAME file in the GitHub Pages source folder (docs for this project) containing the custom domain name. Next, configure the domain's DNS settings in the Google Domains web interface. Under "Custom resource records", add an "A" record to point the root domain (areed.me for this project) to GitHub Pages using the four IP addresses found in the documentation. This should be all that's necessary to get the site up and running, though apparently it can sometimes take some time before changes propagate through the system.

Optionally, you can also add a "CNAME" record to direct the "www." subdomain (i.e. www.areed.me here) to your GitHub Pages homepage too. I've also enabled HTTPS in the GitHub Pages settings as this is recommended. The final configuration for this domain, under the Google Domains DNS settings, can be seen in the screenshot below.

Conclusion

Despite being someone without much experience in web development, I was still able to get this site up and running from scratch after about a weekend's worth of work. There were plenty of resources online for working with 11ty, which made it accessible even for a relative beginner such as myself. I'm quite happy with the end result, and hopefully it should be easy to maintain in the future due to its simplicity.

Creating new entries and adding them to the website is also as straightforward as I'd hoped. A local copy of the site can be loaded by running npx @11ty/eleventy --serve, and posts then written in Markdown with minimal technical overhead. The local site automatically updates as the post is written, allowing me to check the formatting as I go, and also generates the 11ty build output needed for the live site in the docs folder. To add the new page to the live website, all I need to do is commit the new files in the docs folder when I'm done writing. Perfect!

Now I just need to get on with putting together some actual material to post...