As a developer, I like learning and sharing new technology. However, I find it wastes a lot of time to copy my notes and post them on blogs websites like Medium. So, I decided to create my own blog site.
My blog site should publish my notes automatically, without posing them by hand. That means, when I take some notes, these notes should be presented on my blog sites without extra action. Awesome, right? Let’s do it.
Structure
Before coding, let’s think about what I gonna build.
First of all, I need a place to store my notes. Github is the best choice. We can push any file to Github easily, and Github shares them. So, I just need to do `git push`, then my notes are available online. That’s it, the job is done.
aha, I’m kidding. There are some limits of Github to show the blogs.
First, It can’t clearly show the extra information, such as the author, the updated date, the topic of notes, etc. We need a back office to track these.
Secondly, the UI of Github isn’t suitable for blogs. I want a nice UI like that of Medium. So, I should create a front page, too.
In conclusion, I need to build:
- a public Github repository to store my notes
- a backend to track my notes
- a frontend to present my notes
Needs
I’ve known what I want to build. It’s time to discuss what we need to do.
First, I need to decide the format of my notes. Although Github can serve all kinds of files, it isn’t easy to share some of them, such as word, excel, etc.
I use markdown. There are 2 reasons.
- Github serves the pure markdown file. There isn’t any extra information in it.
- Markdown files can be parsed into HTML files easily. It reduces a lot of work at the front-end.
Then, I need a back-end. It should:
- listen to my Github repository
When there is a git push, it should know.
- keep `push events` in records
It should know who creates the note, when it’s created, what is the note URL, etc, and keep the records in the database.
- share records
These records should be sent to the front-end.
Tools
Since I’ve figured out the needs. I should choose my tools.
I use Django to build the back-end. Django is written by Python. It makes development so fast. I love Python, and I love this framework.
Next.js is my front-end framework. It provides SSR (Server-Side-Rendering). There are several advantages of SSR over SPA (Single Page Application).
- The application is chunked.
The blog system is one part of my website. The browser doesn’t need to load other JS files which aren’t used in this system.
- The SEO is better.
Compared with the HTML file of SPA which is impossible to read, the HTML files of SSR are rendered at the server-side instead of the client-side, which are more friendly to the search engine.
- The router is simpler.
Next.js is based on React. However, we don’t need “react-router”. Each JS/TS file under “pages” folder represents a page. It’s very easy to develop.
Of course, there are downsides.
- The HTML files are rendered at the server-side for each request.
We can use the “Static Generator”, which is also provided by Next.js, to overcome it. The HTML files will be rendered at the build time. But, the building will cost too much time if we have many files to generate.
Details
There are a lot of details to build a website, and most of them are boring. However, some points are very interesting.
Listen to the Github repository
The repository of Github provides webhooks. When there is a push event, webhooks will send this event to all the listeners. That’s the key point of the whole blog system.
To build it, I did 3 things:
- create a listener in the back-end: The listener includes decrypting webhooks secret key, reading events, save events’ info to the database. I may write another article to present all the details.
- register the listener in webhooks
- setting the secret key of the webhooks
Send notification to site admin
Once a push event is treated by the back-end, the back-end will send a notification to the site admin. It reminds the admin to rebuild the front-end.
The notification can be an email. I use Slack incoming webhooks to send a message in Slack.
Parse Markdown files into HTML files
When an admin rebuilds the front-end, the front-end does a couple of things:
- call the back-end to get records of all the notes:
The record contains all the details of the note, such as author, updated date, topic, etc. Most importantly, the URL of the Markdown file in the Github repository
- call the Github repository to fetch all the Markdown files
- parse Markdown files into HTML files
It’s important to understand that this action ONLY happens when building the site. New notes in the Github repository won’t be presented on the blog site until the site is rebuilt.
- create URLs of all the HTML files
In production, I need to node server to serve this front-end. The server will send the Html files according to the clients’ requests.
Conclusion
I built a blog site using Github webhooks.
I pushed all my Markdown notes to my public Github repository. Then Github will send the push event to my backend through webhooks.
My backend saves the event into the database. Once it’s done, the back-end will send a notification in Slack. It tells the site admin to rebuild the front-end.
When the front-end is rebuilt, it will get notes’ details from the back-end and notes’ markdown files from the Github repository. It parses all the data and generates the HTML files.
Voila, It’s how my blog site works. Thanks for reading and see you next time.
