I had been longing for a dedicated space on the web where I could document concepts related to software development. I wanted to effortlessly add technical notes that in the future could help me refresh what I had already learned. For a while I did this on my physical notebook and large whiteboard because it was convenient – until it wasn't. I love writing and highlighting physically, but it was less accessible and harder to find things as oppose if it were in digital format. I then stumbled across Docusaurus and that facilitated my objective.
I'd say this site had been living in my head rent-free for a couple years. I knew I wanted to do it, but failed so many times. In fact, many attempts were abandoned half way. I tried using vanilla JavaScript, HTML, and CSS, but it required too much effort to make it fit my needs. I didn't want to have to maintain it either.
I tried using WordPress too, but it felt too heavy with the database. I wanted something more of a static site generator (SSG). I could simply build and upload the output to the cloud, and because it would just be html, css, and some js it would be blazing fast and cacheable. I even tried Hugo which I liked (and still use for some of my other projects), but then it was too much work installing all the plugins and libraries that I needed to make blogging about software hassle-free. I wanted things like code highlighters, diagrams, and live code, amongst other to be included or a command away from being able to add it.
At this point you might be thinking, you're just a lazy programmer. And you're probably somewhat right, but to be frank, I typically don't like to utilize my time on boring projects. And to me building a custom blogging platform is boring.
At the end of the day, I just wanted a platform or framework where I could just focus on technical writing. Something that came bundled with all the tools necessary to easily add code examples. And of course, with markdown support. My dream. Another requirement was to have full control of my data and code, and something easy enough to customize the appearance. Then I found Docusaurus and it checked all the boxes! The code gods had finally listened to me, or maybe it was serendipity?
Docusaurus is Awesome
Docusaurus is open-source and was created by the folks at Meta (Facebook, Whatsapp, Instagram) specifically for documentation. Many popular libraries like Redux, Redux Toolkit, React Navigation, amongst others use it. The cool thing is that it also has well built out system for blogging out the box! Yup, just what I needed.
It supports markdown, MDX, and even custom React components. Not only that, but out-the-box it looks fantastic and comes with dark/light mode switcher! The entire piece of software is just so easy to set up and use. Kudos to the contributors.
I'm using Docusaurus 2. The following is an example on how it can have live React code:
<button onClick={() => alert('welcome to code logbook')}>Click me!</button>
And we get a live button! How cool is that?!
Conclusion
In a way I am finally writing this thanks to Docusaurus. It has definitely removed the barrier that was stopping from doing so. I can now just focus on writing the content, and that makes me happy. I'm really excited to finally be able to sit down at a coffee shop from time to time and document things about software development that I find interesting.
Get ready for a lot of TILs (today I learned)! I am convinced that by writing I can solidify my long-term knowledge, while at the same time possibly help others who are interested in these sorts of topics. Hopefully you find my blog (technical notes) useful! 😃