Skip to content

Working with MKDocs locally🔗︎

WOW!🔗︎

I'm clearly on a steep learning curve. I'm not quite sure what I thought MKDocs was, but I now realise that it's a Program. By program, I mean it has its own executables.

My production site is hosted on Azure, using a Static Web App (SWA). A feature that I love is the way SWAs automatically create a "dev" environment, aligned to a Pull Request (PR).

I have a GitHub Actions pipeline that runs a series of commands that builds and publishes the contents of this site. This is great, but one drawback is that the pipeline takes a few minutes to run, so every change takes a few minutes to show up. As I learn more about MKDocs and Python, I am sure I'll be able to reduce that time. Additionally, much of the MKDocs special formatting isn't available.

As I mentioned, MKDocs is a program. Within MKDocs is the executable mkdocs. It takes aruguments such as build and serve. I have just used the serve command and I now have a local copy of my website running and when I make changes, they're reflected instantaneously. Well, 0.5 seconds! I have the VSCode window on one screen and the browser on the other. Press ctrl + s and it updates in the blink of an eye.

When I started my MKDocs journey, I was looking for a "DocsAsCode" solution that would run on Azure. Google led me to an article (1) discussing SWAs which looked the perfect solution. I cloned the repo and followed the instructions. My first site is still in use today. To set up this site, I cloned that repo and got to work. As I customise the site and set it up just the way I want, I'm discovering just what MKDocs is.

  1. 🙋‍♂️ I cannot find the original article and code base. If you're the original author, please drop me a line so I can provide links back to your work.

I've since learned that the clone I took only includes the docs and settings. The source code and binaries are not present. They're not required to build the site because all of that is done in the GitHub Action. However, when working locally, the binaries are required. Like most things, there's more than one way to skin a cat and the way this site builds is not commonly discussed in MKDocs circles. For instance, the many MKDocs plugins are described in a package manager called Poetry.

Since my first implementation, many of the plugins have been updated. These plugins, defined in the poetry.toml, have version "pins" that I updated. This broke the build. Whilst attempting to update the poetry.lock file, I have started to learn about Python virtual environments.

Following along with this article I managed to adapt it to build myself a local development environment using my own repo. Here's how I did it:

Setup🔗︎

Tools required🔗︎

  • Visual Studio Code.
  • Windows Subsystem for Linux (WSL) (1).
  • Windows Terminal.
  1. 🪟 Assuming you're running on Windows 😄.

Environment setup🔗︎

  1. Launch Windows Terminal.
  2. Click the🔻arrow and select one of your WSL Linux installs.
    Select Linux
  3. Click Ubuntu.
    You should have Linux CLI prompt.
  4. Set up authorisation to GitHub. If using SSH, set up your public/private key:
    ssh-keygen -t ed25519 -C "you@domain.tld"
  5. Create and navigate to the directory to clone your repo into
  6. Clone the repo:
    git clone git@github.com:{organisation}/{repo}.git
  7. Navigate to the repo's directory.
  8. Run VSCode:
    code .
    On first run, VSCode will automatically install.

Install MKDocs🔗︎

As mentioned, my repo doesn't have the binaries to build the docs, and I don't want it to. The correct way is to use a Python virtual environment. We'll use pipenv to install the required software within the virtual environment.

From the terminal in VSCode:

  1. The required plugins are defined in the pyproject.toml file. Install and configure the package manager Poetry:
    1
2
3
    pipenv install poetry
pipenv run poetry config virtualenvs.create true --local
pipenv run poetry config virtualenvs.in-project true --local
  2. Ensuring we're in the directory containing pyproject.toml, install the plugins and their dependencies as defined in pyproject.toml. 
    1
2
    pipenv run poetry lock
pipenv run poetry install
  3. Now insall MKdocs: 
    1
    pipenv install mkdocs
  4. Finally run the local server: 
    1
    pipenv run mkdocs serve
    If all goes to plan, the local environment should have launched in your browser.

caveat🔗︎

I'm not saying this is the best way to do it, but working with the repo I have, it works for me. Please feel free to leave comments on how it can be improved or better ways of doing it.

References🔗︎

Comments