Taking notes drama from DevOps perspective

The Drama

Why so serious? Oh well, where to start?

The drama as I tend to call it starts from my perspective where someone like me wants to find one good platform to store all the notes, code snippets or other more or less important small pieces of information and keep them in some sort of organised manner.

Obviously, on the market, we have plenty of different programs that were designed to do such a thing. Some of them are pretty cool for just taking notes or even taking screenshots of whole websites or other documents (Evernote for instance). They come in lots of different flavours, colours, tastes, they are sometimes multi-platform compatible and offer cloud storage. Someone could argue that you should pick one and stick to it, and yes you are probably right. But. There is always a but. It has to be, otherwise, there would be no such a blog post like this one.

As a DevOps, I work with many different programming languages, different shells, editors, configuration files and so on. So to be able to make, easy to read notes I’ve always liked Markdown as a format. Markdown by being super easy to learn yet very powerful with formatting features and superb with the way you can present certain programming languages bits on the screen has become my primary choice when doing so.

At that time (a few years back) I was using Evernote for quite a while. Actually, since day one it was released so I was a die-hard user of it and really liked it for casual/normal note taking. But when I started to try to make some code snippets or trying to store just simple bash commands all my dreams were finished. It was just a pain. A lot of pain. And since I never wanted to wast my time on playing how to format stuff on the screen, I have started to look around for some alternatives. Went through few of them quickly just to learn that none of them is much different from Evernote.

Saviour? Not Really!

Since I liked the way Evernote kept all my notes in the could and they could be synced through all of my devices I wanted something that could deliver such service and have Markdown support. One of the I have found and bought immediately was Quiver. And I thought all my problems are solved. It was great. I’ve created the custom library and kept it in my cloud directory so I could use it on all my Mac’s just by changing settings of Quiver to use that file from the iCloud directory.

For some time I was happy but I got really fed up with the three-panel way of displaying your notes and it became kind of painful when it went out of sync with your iCloud drive.

So what next?

After working for so many years and reading countless amounts of documentation I kind of developed a taste for so-called ReadTheDocs format of presenting information and after doing some digging I found out that MkDocs project had that format implemented by default and just installing their package you can start your own Markdown-based documentation server.

More info about ReadTheDocs here

But let’s do it in order and explain what MkDocs is. Let’s quote here the description from MkDocs official project page:

MkDocs is a fast, simple and downright gorgeous static site generator that’s geared towards building project documentation. Documentation source files are written in Markdown, and configured with a single YAML configuration file.

Truth to be told for not experienced user installation procedure and configuration might seem a bit complex, so I’ve created a Docker image with MkDocs pre-installed for super easy deployment. What you need is running Docker on your system. Ater that just follow step by step guide a bit lower in this post.

In my case, I work with Docker every day so it’s just super easy to run a server with MkDocs and I can even limit the number of system resources that I want to share with MkDocs which you cannot do when using native Windows/Mac application. After the installation, you just need to create folders under docs directory and put files with .md extension there and MkDocs will do the trick and serve them for you. You can access your documents under http://localhost at all time after your computer starts.

“Magic starts here.” — H. Potter

Assuming you have Docker and docker-compose installed and running on your system we just need docke-compose.yml file which could look like this:

version: '2'
  services:
  mkdocs:
    container_name: mkdocs
    image: polinux/mkdocs:latest
    restart: always
    ports:
      - "80:8000"
    volumes:
      - ${PWD}:/mkdocs
    working_dir: /mkdocs
    cap_add:
      - ALL
    cpuset: 0,1
    mem_limit: 128m

Let me explain what some of those parameters mean.

ports: - Sets the port number on which you want to have access to your documentation. Let’s say you want to access your docs under address like http://localhost:9800 Then you need to set this value to 9800:8000

volumes and ${PWD}:/mkdocs - This means that the directory that you are running your docker-compose up command will contain your documentation files and all required sub-directories.

cap_add:
  - ALL
cpuset: 0,1
mem_limit: 128m

This section above limits the resources that will be granted to MkDocs from your Host OS. which means 0.1 CPU and 128MB or Ram memory. Not much, but plenty for such a simple task like serving your .md files.

How does it look?

That’s a very good question. It does look like full-blown documentation empowered by ReadTheDocs engine. It does come with search and I think it’s one of the best ways to read any notes/snippets. Yes, you definitely argue that it doesn’t come with tags which even Evernote provides, but I believe that this is not to high price for having a great note taking and storing system.

Start docker-compose MkDocs with an empty project.

Access Web interface

Conclusion

So, can we stop the drama? Well, I definitely stopped mine and finally I put it to rest. I use this method for some time and really not feeling that any native app would deliver such experience soon. It’s not the neatest way of dealing with the note-taking and sorting the problem but definitely worth a try and bringings much of satisfaction when all set correctly. In addition, the impact on overall OS performance is so insignificant that I don’t believe any app can beat that.

I hope you enjoyed the read and if you fancy to try and need a hand setting that thing up please feel free to contact me. I’m more than happy to help.

Link to GitHub Repository with docker image used in this example.