Here we go...¶
Background¶
So I got the basic blog going, and I though I would use this blog entry to reflect on the initial experience.
I started searching for the best "tool" some time ago. I am using "tool" in quotes as it all depends on the requirements, right? So what was my requirements? In a nutshell, I think the following points qualify:
- I love to write in Markdown because it is simple and open. There is no proprietary document format and as long as there are computers, we will all be able to read and understand Markdown.
- The tool (or service) had to support a license that guarantees the content to be open and free - everything I publish needs to be in the public domain. This is just my way of giving back and I don't like the idea that some other company would like to claim some form of ownership over content just because you use their service.
- I am willing to pay for a service, but the cost must obviously fit a working person's budget.
- The tool must be simple enough for me to concentrate on the writing of posts and sharing knowledge - I don't want to spend hours on some widget or fancy control.
- I would like some way to interact with those who may want to comment or otherwise contribute.
- Version control of content is important to me - especially on technical articles that I build up over time before publishing. In this regard I would love the ability to work on one or more branches at the same time. Git already provides all these constructs in a familiar way to me, so the ideal tool would support Git
- I would like full control over the lifecycle of the content. At the same time I don't want to worry about themes etc all that much. It would be great if I could change themes over time without effecting the content.
- The content needs to be portable. If I switch hosts, I would like the ability to transfer the content - all of it.
Online tools¶
I have looked for and use many different online tools over the years to share some content. They all had their own limitations and there was always some aspect of a tool that I didn't like and that eventually prevented me from using it further.
I don't to name names at this stage, as these very tools are serving thousands of users each day who love the various tools. It just wasn't for me.
Especially in terms of my requirements listed above, I just could not find a single service or tool that does it all. I'm sure I have not tried absolutely every tool out there, but at least most of the mainstream ones.
Workflow... my way...¶
I am not a professional writer but I am familiar with software development and technical projects. I would therefore also prefer working with tools that I use every day. My editing of these posts are now done in Visual Studio Code in a very familiar environment.
All my posts are hosted on a public repository on Github. In the future I may automate the build and release of site updates using Github Actions.
I can also work offline and experiment in a "safe place" (a separate branch) before committing any content or changes (like themes), ensuring it works before publishing.
Markdown to HTML¶
There were a number of so called static site generators I tried. Suffice to say, the one in the end that always seemed to just work was MkDocs. It is a really easy to use tool that basically "just works".
The themes available to MkDocs is perhaps not as elaborate as some of the other tools, but it is simple to integrate and easy to maintain. A tool that literally just require a couple of minutes to set a theme and then it's done! The themes are also really easy to customize which is one of the reasons I went for the Cinder theme (version 1.2.0).
Hosting¶
The final peace of the puzzle was hosting my content. I found that after all the searching, a simple AWS Web Hosting solution was perhaps the best way to go. I opted for the Simple Static Website Hosting solution using S3, knowing that when I started to need more advanced options all the tools were already available in AWS.
Wrapping up¶
So, the tool set in the end came down to the following:
- MkDocs as the tool for converting my Markdown files into a static website
- Maintaining my content in a public Git repository
- Using an IDE I'm familiar with to create content
- Using a public cloud service to host the content at a really cheap rate (basically free at this stage)
The setup and configuration of all the elements of the workflow is not 100% complete yet, and I will continue to develop that in the coming days. In the mean time, I am happy that I think I now finally have a long term solution for my very basic needs.
I hope what I shared here could also help other in the future. Feel free to view your opinions in the Disqus comment section, which was also really easy to add to the site!