Select Page

Taking Better Notes with MK Docs

MK Docs Notes

Something I’ve always tried to strive for in my own projects as well as those of my teams’ is keeping good documentation.  My criteria are simple.  

I need something that is

  • Easy to set up and use
  • Can be accessed even when I’m not connected to the internet
  • Allows for images (a picture’s worth a thousand words)
  • Has nice formatting tools that make my notes and documentation easy to follow not only for myself but others

After searching for a long time, I’ve finally found what works for me.  You might find this to not be the solution for you in your own work but if you are still looking, I offer this up as something you might want to at least consider.

MK Docs is a lightweight, very easy to implement, note and documentation solution.  It uses the Markup language which is straight-forward.  Anyone can Google Markup commands online and find a huge list of commands to make your documentation look professional and easy to read.

Set Up Steps

  • Open terminal on your Mac (click your search icon in the upper right of your computer and start typing terminal for it to appear)
  • terminal defaults to your root directory.  Type ls -l to see all directories in a list
  • Type cd <directory name you want to navigate to>.  Example cd Desktop and hit enter
  • Type md <folder name you wish to create>. Example md mkdocs and hit enter
  • the md command makes a new directory.  In this case it makes the mkdocs directory (or folder)
  • Type cd mkdocs to go into this new directory (You can also create a new directory from within Finder if that’s what you are more familiar with)
  • Go to home-brew.com and copy the command you see on their home page into your terminal window.  Home-brew is a package manager meaning that whatever you need to install, it knows what dependent files your installation needs and will ‘package’ and install those as well and in the order needed
  • After homebrew is installed you can run a ‘brew list’ command at the cursor prompt to see the list of packages you can install
  • Type <brew install mkdocs> 

Creating A New Page

  • Go to your mkdocs directory from Finder
  • Now go into the ‘docs’ directory
  • Make a copy of the index.md file and rename it to what your new page is about.  The last one I made was on HTML so I named the file HTML-tags.md
  • Open the file in the editor of your choice and delete everything.
  • Type your text for the new document in, adding Markup text where needed then save the file. A quick Google search reveals a ton of online pages detailing the commands you can use to format your content
  • When you refresh your browser, you will see your new document and can pull it up

Viewing Your Pages

  • From your terminal window, navigate to the directory you created if you aren’t there already.
  • Type mkdocs serve and hit enter.
  • Open browser link http://127.0.0.1:8000/
  • Your home page should show.

You now have the ability to create professional looking, easy to understand documentation that is local (not cloud dependent) and that you can share if need be. Have fun!