Replies: 1 comment
-
This is a test comment with bold and italics A headingWith some text underneath
|
Beta Was this translation helpful? Give feedback.
0 replies
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
-
description: Details on how this website was built, leveraging GitHub Pages, Discussions and Actions.
This website has been made and remade a few times, each taking a slightly different approach. So far I've tried:
But once again, I've rewritten this website from scratch...
Why did this website need a rewrite?
It probably didn't, but I like the current state its in far better than previous versions (and it was fun to do).
Although all of the other solutions worked, none of them seemed just right. The previous iteration using Sanity.io as a CMS1 was close. However, writing content was cumbersome and the CMS was overkill for writing short blog posts. I found myself not writting anything because it was tedious to do so.
What makes a good system for writing a blog?
Challenges, problems and solutions along the way
Inspired by swyx.io's blog I explored using GitHub as a CMS. Swyx's blog uses GitHub Issues to write posts leveraging GitHub's feature-rich markdown. This simple solution is definitely easy to update and feature rich.
After first seeing utteranc.es2, I wanted to use it to add comments through GitHub Issues and this seemed to kill 2 birds with one stone. However, I wasn't fully onboard with using Issues for posts and comments because it fills a useful issue tracker with dummy issues and feels too much like a workaround. With the relatively new addition of GitHub Discussions, it felt better suited for a place to write posts and store comments.
After a quick search I found giscus , it is inspired by utteranc.es but uses discussions instead to host conversations. Just like swyx's issue CMS, discussions have markdown content which can be used in a similar way.
Conveniently, you can setup announcement discussion categories in the discussions tab of a GitHub repository allowing for a place where
This sounds like a perfect place to host our blog content. In addition to the other two criteria, we now have a system that also supports comments and reactions. The discussion categories also allow for differentiating between drafts and pubished posts where it is simple to make drafts only visible locally in development.
I wanted to use GitHub Pages to host this website, so this meant that it had to be fully static. SvelteKit's static adapter makes this very easy to do, without any configuration3!
To enable fast updates, I used GitHub Actions to automatically trigger builds when a discussion is created, edited or when its category is changed. The action only runs if the discussion is in the published category as shown in the snippet below.
To pull content from discussions I wrote a script that parses the markdown and metadata and turns it into content for my blog using the Discussions API. This did come with some challenges. Since it is only available through GitHub's GraphQL API, it requires authentication for all requests. This is fine in development as I can use a personal access token to authenticate my requests but I thought it might be a problem for deploying. But it didn't take long to find that GitHub automatically provides a
GITHUB_TOKEN
when using Actions. This allows all the requests to be easily authenticated during building and deploying.Parsing the discussion body using mdsvex means I can have very rich content, with code highlighting, frontmatter and other nice formatting out of the box. The frontmatter is especially powerful, allowing for the ability to override metadata and add other whatever other arbitrary information to posts. Additionally with plugins, I added even more 'nice to have' features like footnotes, estimated reading time, or oEmbed.
The 'finished' product
This website as it is acheives the goals set out at the begining and is a huge improvement on the previous iteration. It really makes use of GitHub's great features to deliver a minimal but fully featured blog (The best thing is, it is all free!) There are still a few features I would like to add shown below, along with the list of features already implemented.
You can find all the code on GitHub, feel free to poke around or use anything that might be useful for you.
Leave your thoughts and reactions (or just try giscus) below!
Features and To Do
Footnotes
A content management system, where you can author content and upload media ↩
A clever comments systems built with GitHub Issues ↩
A bit of configuration necessary if you are hosting at
user.github.io/repo
instead ofuser.github.io
↩Beta Was this translation helpful? Give feedback.
All reactions