Why I chose to create my dev blog in a fully open source manner and all the advantages with this approach
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
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 :)
- 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
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).
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!
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.
This open source approach supplies some decent advantages, here are a few:
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!
I added Snyk’s vulnerability test badge at the page header, so every viewer can see the security status of the blog:
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.