Docs-as-Code Tutorial

A basic tutorial to create and host a documentation project using MkDocs and GitHub


This tutorial explains how to create a static site for documentation using a docs-like-code approach. It will guide you to the process of:

  • Setting up a local documentation project.
  • Hosting your documentation project in a remote repository hosting site.
  • Setting up an automated deploying process to a static web site.


There are many different tools available –from static site generators to hosting sites– but for this tutorial we will use:

  • MkDocs to create the static site.
    (ℹ) MkDocs requires Python and pip package manager. If you are using Mac you should have them installed already. Verify if you have them by running python --version and pip --version in a Terminal window.
  • GitHub to host the documentation repository.
  • GitHub Pages to automate the deploying process and host the web site.

The tutorial guides you through the process of installing and configuring the required tools.

Get Help and Give Feedback

If you follow this tutorial and need help or find something that is not working or can be improved, don't hesitate to reach out at: