This is my walkthrough of how to easily publish a site with GitHub pages and Jekyll. I am using the Chirpy-starter, which is just based off of the Chirpy Jekyll theme. There are a lot of Jekyll themes out there, but this one I picked for the clean styling, and also the blog centric focus. The starter version is not as customizable, but easier to get up and going. I might in the future use something more extensible, but this offered everything I need at the moment.
As I mentioned in my previous post, I was using a static Google Site for my CV type of homepage, and then Blogger for blog posts…obviously. Both were very rigid, and also I did not like how I had to use a proprietary system to publish, especially Blogger. I wanted to write my blog posts in Markdown for two reasons. Main reason was so my posts could be easily written and linkable within my note/knowledge system of choice, Obsidian. Also, ownership of the publishing and files was important to me. I have written previously about this journey of finding a knowledge management system alongside a task management system. I will refactor these out of date posts and republish here shortly (and update this article with links once I do).
Create the repo
For now, let me focus on the title of this post. First step was to use the template above, and name the repo
<GitHub_username>.io in my account. Mine looks like this –>
Then cloned my repo locally to customize and create posts. Here are a couple customizations I did that might be helpful for you.
NOTE: the instructions say to install all of the dependencies/prerequisites, such as Ruby, but this is not needed. Installing these are just for previewing the site locally.
Pretty simple, but you just go to the repo’s Pages settings to enable this. See the docs for more info, but essentially I just needed a TXT record to verify domain ownership, and then A records pointing to GitHub pages endpoints
Remove categories from tabs
config.yml from this:
1 2 3 4 5 6 7 8 jekyll-archives: enabled: [categories,tags] layouts: tag: tag category: category permalinks: tag: /tags/:name/ category: /categories/:name/
1 2 3 4 5 6 jekyll-archives: enabled: [tags] layouts: tag: tag permalinks: tag: /tags/:name/
Other config updates
- Updated all of the appropriate title, description, and social fields.
- Updated the avatar to my Twitter profile picture
theme_mode: [light|dark]to just
[dark]to nuke light mode (I hate glaring white)
I enabled Disqus to test and it worked fine, but removed as I didn’t care for the styling, not to mention their questionable privacy policies. I instead configured utterances, an open source and lightweight commenting app that uses GitHub Issues to store the comments. There is no tracking, no ads, and no data lock-in. Beings this is a technical blog, I would imagine most readers will have a GitHub account. If this was a different genre of blog, maybe Disqus would be more appropriate.
Go to this page for instructions
Go to the demo site, as it contains everything else needed.
Now onto the reason to do all of this: posting content. This page has great info on all the options for the markdown files. The basics are:
- Title of markdown file needs this format of date+title –>
- Metadata needs
- Tags need to be lowercase, and can be Obsidian nested style with a
/, or just single string. I prefix all of my tags with
blog, so in Obsidian my blog post tags don’t clutter up my personal note tags.
1 2 3 4 5 --- title: New post tags: [blog/obsidian_nested,regular_tag] --- Content of blog post....
Placed my files in the
Pushed all of these changes and the blog was live. You can watch the pipeline build the site in the Actions tab. Feel free to comment below if you have questions or run into issues.
Here is my follow up post with my Obsidian workflow for creating the actual post files.