Markdown and MkDocs

Hello! Since we're all starting to delve into the territory of online documentation, I think it's necessary to start learning about the tools that we are going to be using throughout this process, so, this article will focus in Markdown and MkDocs. Let us begin.

Markdown

Simply put, Markdown is a series of conventions that simplifies the use of HTML to create simple yet good-looking sites. Markdown is specially useful when it comes to READMEs and documentation in general. As a matter of fact, using Markdown to build documentation is pretty much the industry standard, so learning this ability will be very useful for any current or future technical documentation activities, and you'll be happy to know that Markdown supports HTML syntax, so all the HTMl stuff we learned some time ago will be very useful. Luckily for us, Markdown is simple enough to learn and use and there are a whole lot of resources online to learn and master it very quickly. I'll compile some of these resources here to get you on your way to become a Markdown expert.

  1. Text / Source Code Editor

    2. This is more of a preliminary step. A Text / Source code editor is necessary to create and edit Markdown files (.md), even something like Notepad can get the job done, but just like using a frying pan to hammer down some nails, there are way better tools for the job. I would suggest installing either Microsfot Visual Studio Code (the one I use) or Atom. Both offer excellent features that may come in extremely handy when writing Markdown, such as Markdown syntax preview. Install and familiarize yourself with your tool of choice before going any deeper. Both editors are completely free.

  2. Markdown Tutorial

    3. This is an interactive site designed to learn the basics of Markdown. It will guide you through a series of excercises and activities that will help you learn a lot about this tool. It does not take long and you will familiarize yourself with the most basic aspects of Markdown. It isn't the most in-depth look, but it is a good starting point.

  3. Markdown Cheatsheet

    4. This convenient guide offers instructions to carry out different formatting configurations with their corresponding examples. When in doubt about how to format anything, this guide may come extremely handy.

  4. StackEdit

    5. This is pretty much a live Markdown demo. it allows to see the syntax and results live on the site. It is also a very good resource when learning how to use Markdown to write documentation.

There are many more resources to be found on the net, but they are as diverse in content and quality as your writing and formatting needs. Learning to look for resources is also a part of mastering Markdown. Simply put, it's time to train your Google-Fu!

MkDocs

MkDocs is a static website generator; that is, a tool that can be used to create simple and good looking static websites very easily. This is the tool that we will use to create the online documentation for the solutions of the company. MkDocs is free and very easy to install, learn and use. I will take the chance to compile all the resources and components necessary to install and use MkDocs.

  1. MkDocs

    2. This is the main website of the tool. It contains the files, instructions and resources needed to install MkDocs on your PC, as well as additional resources such themes and plugins. This site holds everything you will need to build, configure and deploy your own static website, all without spending a single dime; however, it is also possible to find resources externally suited for different needs and themes.

  2. Python/PIP

    3. As you will find in the MkDocs installation process, it is necessary to install and/or update Python and PIP. The MkDocs installation instructions already provide steps and instructions to install these components, but I consider it's important to provide these two links to have them at hand. Bear in mind that MkDocs DOES NOT support the latest version of Python and the last supported version is Python 3.7. Right after installing a supported version of Python, it is necessary to check the version of PIP and update it. You will find the instructions to carry out these procedures in the provided links.

  3. Themes

    4. MkDocs allows the use of themes to configure the visual aspect of the website. These themes are free, very easy to install and highly customizable. This feature allows us to select and use the theme we find most suitable for the purpose of the document and modify its appearance (color scheme, icons, the position of some components, etc.). The theme that we selected for the documentation demo is called Material, it has its own website with different resources to configure and deploy a site using it. Most of these themes have similar resources, both provided by their respective creators and other parties that have used them for their own documentation sites. These resources are at a hands reach if you know where to look, so the Google-Fu we talked about before will come in very handy.

Examples

Here, I will simply provide some examples of documentation sites that use MkDocs so you can see the tool in action, and some useful external resources.

  1. ZeroNet

    2. ZeroNet's line of business is very far from ours; however, they used the same tool as us to build their documentation and they are very open with the knowledge and technology they used to build their documentation site. You can find their documentation repository here along with the Readme they created for their site and other useful goodies.

  2. Markdown Crash Course

    3. Just a useful video about Markdown in case you're looking for more information about it or you're more of an audiovisual learner.

  3. Dougal Matthews - MkDocs: Documenting projects with Markdown

    4. Short conference in EuroPython 2015 about using this tool to create online documentation. It showcases how fast and easy it is, with the added bonus of legitimizing our use of the tool a bit because people respond well to that sort of thing.

Well, this is it for now, hope you find this resource useful. Good luck and happy documenting!