Skip to content

How to Install and Run MkDocs Development Server

MkDocs is a static site generator that allows you to create beautiful and customizable documentation for your project. In this guide, we will walk through the steps of installing and running the MkDocs development server on your local machine.

Prerequisites

Before you begin, make sure that you have the following installed on your system:

  • Python 3.x
  • pip (Python package manager)

Step 1: Install MkDocs and the Material Theme

To install MkDocs and the Material theme, open your terminal or command prompt and type the following commands:

cd hakai-api/docs
pip install -r requirements.txt

Step 2: Start the MkDocs Development Server

To start the MkDocs development server and view your documentation, navigate to the project directory and run the following command:

cd ../  # hakai-api root dir
mkdocs serve

This will start the development server and display a message that the server is running on http://127.0.0.1:8000/.

Open your web browser and enter the URL http://127.0.0.1:8000/ to view your documentation. You should see a default MkDocs template with some sample pages.

Step 3: Edit the MkDocs Configuration File

To customize your MkDocs project, you can edit the mkdocs.yml file located in the project directory. This file contains the configuration settings for your project, such as the site name, theme, and pages.

After making changes to the configuration file, you can restart the development server to see your changes by pressing Ctrl+C in the terminal to stop the server, and then running the mkdocs serve command again.

Step 4: Edit the Documentation Pages

To edit the documentation pages, you can edit the Markdown files located in the docs/ directory. Changes to these files will be automatically reflected in the development server.

Step 5: Deploy the Documentation to GitHub sites

To deploy the documentation to GitHub pages, just push the changes to the main branch. GitHub will automatically build and deploy the documentation to the gh-pages branch.

Reference Documentation

For further reference, please consider the following resources:

Material for MkDocs has multiple themes that you can choose from, as well as a number of extensions for rendering code, drawing diagrams, admonitions, and more. For more information, see the Material for MkDocs Documentation.