Why I chose to create my dev blog in a fully open source manner and all the advantages with this approach
tl;dr
In this blog post, I explain why I chose to create my dev blog in a fully open source manner and all the advantages with this approach. I planned creating my own developer blog for a while but wasn’t satisfied with the common setups normally chosen. As an engineer, I preferred to treat my blog as yet another software project and therefore had the following requirements:
- manage everything (really, everything) in a single place — GitHub
- the blog management interface should be done solely using git:
- git pull = get the latest version of the blog
- merge to master = publish a new version of the website
- be able to run the blog locally and see how it looks before publishing
- maximum Markdown as possible, ideally no CSS and html work. I admit, I’m not a CSS fan :)
- the entire stack should be open source
- both the website’s UI and the tech setup should be as simple as possible
The Setup
Source Code Management
Per the requirements I set, GitHub was a clear choice as my source code management. You can see the blog’s repo here.
Nothing special to add here :)
Static Pages Framework
There are lots of open source site generators, Gatsby and Hexo to name a few.
I eventually chose CodeDoc as the site generator for a few reasons:
- I saw it in a Reddit and thought it would be nice to give a new framework a shot :)
- it is really simple to use
- the look and feel is very unique and simple, I looked for the simplest design as possible
- it comes with some useful builtin features out of the box:
- Markdown-based menu (table of contents) on the left
- a small page-map on the bottom-right
Local Debugging
CodeDoc’s CLI has a codedoc serve command that automatically monitors all the local files, converts the relevant Markdown files to html and updates the local server, so http://localhost:3000 always has the updated version.
This allows me to see how the final website looks like during "development" (adding more content).
Publishing Website On Merge
This is exactly the purpose of GitHub Pages! I just configured my repository to publish my master branch as GitHub Pages and that was basically it. so simple and efficient!
Versioning
I used GitHub Actions to call Semantic Release upon merge to master. If you are interested — here is the action configuration.
This automatically creates a GitHub release and a nice and clear release notes, according to my commit messages. Feel free to see all of the blog’s releases.
Open Source Approach Advantages
This open source approach supplies some decent advantages, here are a few:
Ease Of Management
This approach makes the website development cycle a regular software development cycle, making it super easy to maintain:
- local development in a code editor (for writing Markdown files and edit package.json mostly)
- local debugging using codedoc serve -> I put it as my npm start command
- build the website using codedoc build -> I put it as my npm run build command
- merge code to master in order to deploy
- The Semantic Release versioning gives the owner (and everyone who look at the repository :)) a clear view of what each website version contained
- if bad things happen and the website doesn’t look as expected — reverting a commit will do the job
- opening a PR is equivalent to adding new blog content — even this blog post was merged in a PR!
Security
I added Snyk’s vulnerability test badge at the page header, so every viewer can see the security status of the blog:
Summary
I hope I made it clear why I chose to build my blog the way I did, feel free to reach out for any questions!
Originally published at https://shaimendel.dev.
Top comments (0)