MkDocs - Step By Step
What Is MkDocs
MkDocs is an easy-to-use static HTML site generator that enables the creation of Project Documentation for end users quickly. It is easy to customize the project documentation as well as the look and feel of the site. The documentation source files use Markdown to format the documentation pages. Configuration of the site uses a YAML configuration file. These combined processes enable the previewing of the site as you work. In addition, it comes with a built-in site search function, allowing the end user to find information faster. Sites built using MkDocs can be hosted anywhere, including GitHub pages and Amazon S3.
MkDocs Requirements
1. Python (to install the package)
2. Something to edit Markdown files (i.e. Visual Studio Code)
Steps
1. To download the package MkDocs and run the following on the command line
// Installs MkDocs Package pip install mkdocs
2. Make a new project for MkDocs such as “ProjectDocumentation”. This will generate the mkdocs.yml file, which defines the navigation and site organization. This can be done in the command line prompt.
// To make a new project // code: mkdocs new [Projecct Name] mkdocs new ProjectDocumentation // Changes Directory cd ProjectDocumenation
The following files are created:
index.md is the homepage for the documentation
mkdocs.yml is the configuration file and also defines the navigation for the project
The docs folder contains all the markdown pages of the project
3. Running the files will generate a local website. This will allow one to edit the .md / .yml files and the changes in real-time by viewing the local website.
// initiates the local website to enable real-time editing/viewing mkdocs serve
4. When happy with how things look, build the site using the following code:
// Builds the site mkdocs build
5. The site can be deployed anywhere. If GitHub is being used, commit the files and run the following:
// Deploys the site using GitHub mkdocs gh-deploy
There are many different themes that can be used out of the box or customized. There are links to that information and how to create your own theme at MkDocs.org. I also made a GitHub Repo Template and blog post that can be used as a base for your own project. This was inspired by The Document and Usability course, which is a part of The Informatics Technology for Cancer Research (ITCR) Education Resource training series.
