MKDoc is Free Software and is a web application which lets you: Easily manage and deploy content on the internet. Create and manage online communities around your website. Publish materials in. Mkdocstrings can support multiple MkDocs themes. It currently supports supports the Material for MkDocs theme and, partially, the built-in ReadTheDocs theme. Each renderer can fallback to a particular theme when the user selected theme is not supported.
I work in the Quality Engineering department in Waterloo, Ontario, Canada. There is a lot of information out there, internally and externally, about how we do our jobs. For example, internally, there is JAM, SharePoint, and Wiki. Externally, I use Google, Stack Overflow, and other technical sites. Having so many sites to navigate, I thought it would be nice to store information in a central location so I created an Information Repository. Not only have does it contain new content but it also references links to all these tools.
The information repository started off as a reference point for new hires and interns, but it is becoming more than that! It is a great way to share information and fosters cross-training.
After working in User Assistance for some time, I worked on SAP Cloud Platform SDK for Android and saw that they used MkDocs. To begin with, I set up our Quality Engineering documents using MkDocs but later moved to Jekyll.
“MkDocs is a fast, simple 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.” For more information, see the MkDocs website.
Jekyll is simple, static, and is a great blog tool. It is also used for building project and technical documentation. For more information, see the Jekyll website.
Both MkDocs and Jekyll take markdown and yaml files and convert them into HTML. They can both be easily integrated into GitHub and you can use GitHub pages to host the documentation.
I’d like to discuss the benefits and drawbacks of each project documentation tool.
MkDocs
| Benefits | Drawbacks |
| Quick setup time – uses Python, markdown | At that time, no ability to edit a page if you wanted to make a quick change. |
| Creating a table of contents is simple | Older technology |
| The search is superior to Jekyll | |
| Running a test server is easier to set up than Jekyll |
Jekyll
| Benefits | Drawbacks |
| Has the ability to edit a page on each page | Set up time is longer than MkDocs (Jekyll, Bundler, Ruby Gems, Markdown are required) |
| Newer technology | Search is limited to title, keywords, tags and summary |
| Running a test server takes more effort if its not your project | |
| Table of contents can only be three levels |
The no “Edit me” was a big issue for me because I wanted it to be as easy as possible to make changes. This button allows a user to edit their current page and make the necessary changes without having to go to GitHub to figure out the location of the page. At the time, “Edit me” went to the project and not the page. This has been corrected.
Download skyhawke driver. Edit me
I decided to go with Jekyll mainly for the “new look and feel” and the ability to have someone edit a page. It took longer to get set up but once completed, I was happy that I went with Jekyll! People on the team are adding content almost every day. Here is the landing page of the Quality Engineering documentation:
QE Documentation
My next step is to utilize Docker since there are Jekyll Docker images readily available.
MkDocs installation steps are described on the MkDocs website and are summarized belowto verify that the steps work on different operating systems.
MkDocs requires Python.Python may not otherwise be utilized in a software or documentation project andin such cases Python will only be used behind the scenes.On the other hand, Python may be utilized as the primary language for a software project, or may be usedas a supporting utility language for scripting. Python is available on common operating systems.
It may be necessary or desirable to use a third-party MkDocs theme to enable an improved look and feel and functionality.This decision may not be obvious until after content has been added to the documentation.The following are links to themes:
- Material Theme - this documentation uses Material theme
To use a third-party theme, follow the link for the theme on the above page and follow installation instructions.Note that in some cases the theme will already have been installed and pip will indicate that update can be used.After installing the theme, change the theme configuration property in the mkdocs.yml file to indicate the new theme.It may be necessary to and restart MkDocs (see Edit Content section).
The following describes how to install MkDocs:
Install on Cygwin
The following instructions describe how to install MkDocs on Cygwin for Python 3 (python3).
Install Python
Check to see if Python is installed on the system. The python3 program is used for Python3.Note that the python program corresponds to Python 2 and care needs to be taken to use python3.
If python3 is not installed, install using the Cygwin installation tool.
Install pip
MkDocs is installed using the pip3 tool.This is a script in addition to the pip module installed as a python3 package.Check whether pip3 is installed:
or equivalently:
The Windows output may be shown when run on Cygwin in this example because Cygwin will search forsoftware installed on Windows if not found on Cygwin.This may be OK if MkDocs from Windows is used instead of Cygwin.However, if it is desired to use Python and pip on Cygwin, confirm the installation on Cygwin.
If pip is not installed for python3, install it.Even though pip should already be included with python3 on Cygwin, it may not actually have been installed(see Stack Overflow article 'Installing new versions of Pytnon on Cygwin does not install Pip?').Following the instructions from the above link to install pip on Cygwin:
Install MkDocs
MkDocs is installed as a Python module. Capture one to lightroom. First check whether MkDocs is installed:
If MkDocs is not installed, install and if necessary update pip:
Install MkDocs Theme
Mkdocs
It is often useful to install a MkDocs theme.For example, this documentation uses the Material theme.To install, use a command similar to the following:
Install on Linux
The following instructions describe how to install MkDocs on Linux.The following examples used Debian Jessie, although other Linux distributions would be similar.There may be variations in install locations and handling of Python program name for Python versions 2 and 3.Therefore, it is important to understand what is installed and which program name should be used.It is assumed that software is being installed on a virtual machine or other environment.MkDocs is more appropriate for a developer computer than a server.MkDocs has been verified to work with Python 2 (python) and Python 3 (python3).The following focuses on newer python3.
Install Python
Check to see if Python is installed on the system (the python3 program corresponds to Python 3and python corresponds to Python 2):
If necessary, install Python:
Install pip
MkDocs requires that the pip3 Python module is installed for python3. Check whether pip3 is installed:
If pip3 is not installed, install it:
Install MkDocs
MkDocs is installed as a Python module. First check whether MkDocs is installed:
If MkDocs is not installed, install:
Install MkDocs Theme
It is often useful to install a MkDocs theme.For example, this documentation uses the Material theme.To install, use a command similar to the following:
Install on Windows
The following instructions describe how to install MkDocs on Windows 7 & 10.The following focuses on Python 3.
Note that the Python installation for Windows has changed over time.Newer installations of Python recommend installing the software in a user's file locations,which corresponds to C:UsersusrAppData rather than older C:Python27, etc., in orderto minimize need for administrator privileges and avoid installing Python packages in a system folder.
Python software for new installations is also accessed using the py program.The py.exe program is installed in C:windows and therefore is always in the PATHenvironment variable.The py program finds Python 2 and 3 versions on the system and by default runs thenewest installed version.This ensures that Python can be run without adding a specific Python installation folder tothe PATH.Of course, installing py requires administrative privileges even if the Pythonsoftware itself is installed in user files.The benefit of installing Python in user files is that additional packages can beinstalled without administrative privileges.
The following illustrates how Python is found on the command line:
Install Python
Check to see if Python is installed on the system.
Checking for Python using py
If py is used to run Python, available Python can be listed as following(the asterisk indicates the version that will be used by default):
Mkdocs Faq
Checking for Python in PATH
If Python was added to the PATH then the following can be used to check whether it is installed:
Python may not have been added to the PATH environment variable.If nothing is shown above, also check for Python installation in C:UsersxxxAppDataLocalProgramPythonPython37(which is used for Python 3.7), although other locations may have been used,such as C:UsersxxxAppDataRoamingPythonPython35.
If necessary, install Python for Windows from the Python download site.
Install pip
Mkdocs Rst
MkDocs requires the pip Python module installation tool to be installed. Check whether pip is installed:
Because of the complexities of installing multiple Python versions,it may be more clear to run pip by specifying as a module:
Mkdocs Layout Setting
If pip is not installed, install it:
Mkdocs
Install MkDocs
MkDocs is installed as a Python module. First check whether MkDocs is installed:
If MkDocs is not installed, install.
Install MkDocs Theme
It is often useful to install a MkDocs theme.For example, this documentation uses the Material theme.To install, use a command similar to the following:
Update MkDocs
MkDocs release notes can be consulted to determine whether to update MkDocs.
Mk Docs
New versions of MkDocs software can be installed by running the following, or a variation, as per operating system:
Next Steps
After installing the software, the next step is to create a new MkDocs project to organize documentation files.