Beliebte Suchanfragen

Cloud Native



Agile Methoden



Charge your APIs Volume 1 - Build a documentation system with mkdocs

10.5.2023 | 5 minutes of reading time

Following last week's launch of a new series of articles on LinkedIn, there is now a refresh under a new name on the codecentric blog. Why "Charge your APIs"? Quite simply, we all need to think APIs further and not just see them as a vehicle for integration. But for that, there is a lot to do besides the classic API design. That's why I would like to pick a particular topic each week and look at it in more detail. And I'll also tell you one or two tricks from our everyday project work. And here we go! Last week's focus was on Any Decision Records (ADRs). The Decision Records served as a starting point. Now, this week, we want to build the foundation for the creation of relevant API guidelines. At this point, I would like to define again what API guidelines actually are.

Refreshing API-Guidelines

API guidelines are a set of rules and recommendations that should be considered when developing and using APIs. These guidelines can refer to various aspects of API design, such as the naming of endpoints, the use of HTTP methods, the handling of error messages or the documentation of interfaces.

The goal of API guidelines is to increase the consistency and usability of APIs to ensure a better experience for developers and users. Well-designed APIs that follow the guidelines can also contribute to easier maintenance, scalability and integration of applications.

A bit more information on API guidelines can be found in my post on Medium.

Now, if we want to create API guidelines, we can do so using any editor and store them in a central location in the organisation. The writing process and storage are only part of the whole. We have already set the textual foundation with ADRs. From them, we now want to create the documentation for our API initiative. In the context of documentation systems, static site generators are becoming more and more common.

Static Site Generator

A static site generator is a tool used to create static websites. Unlike dynamic websites, which use databases and server-side scripts, static websites generate all pages in advance and store them on the server. The generator uses a template and content in the form of text, images, etc. and generates the static HTML files for the website. Static site generators enable faster and more secure website development, as no server-side processing is necessary and content can be cached more efficiently. They are also great for creating documentation, as in the context of API guidelines, as they make it easier to create and manage content in a central data source.

Building a documentation system with mkdocs

Today I'd like to take a look at mkdocs. A very lightweight system based on Python and Markdown. After installing mkdocs, you can start right away.

1 mkdocs new acme-api-initiative
2INFO     -  Creating project directory: acme-api-initiative
3INFO     -  Writing config file: acme-api-initiative/mkdocs.yml
4INFO     -  Writing initial docs: acme-api-initiative/docs/

With the creation of the directory for the ACME API initiative, we have laid the foundation. With the possibility of using plugins and templates to customise the functionality and presentation of mkdocs, we can build a documentation system that meets our needs. Here is a first basic configuration:

1site_name: ACME API Initiative Documentation
4  - search
5  - multirepo:
6      cleanup: true
7      keep_docs_dir: true
8      repos:
9        - section: Decision Records
10          import_url: '*'
13  name: material
14  palette:
15    - media: "(prefers-color-scheme: light)"
16      scheme: default
17      toggle:
18        icon: material/brightness-7
19        name: Switch to dark mode
20    - media: "(prefers-color-schema: dark)"
21      scheme: slate
22      toggle:
23        icon: material/brightness-4
24        name: Switch to light mode

In this configuration, I use an integrated plugin for the search function and the mkdocs-multirepo-plugin in addition to mkdocs-material. The last plugin makes it possible to integrate external documentation repositories into the documentation system. Specifically, this is now the Decision Records from last week. With mkdocs-material, a few little helpers, such as Python Markdown Extensions, are added in addition to the actual theme. One special feature should be noted: mkdocs-material is available as an open source variant and as an Insiders fork, which is available for a monthly sponsorship. This is a good thing, as it keeps the project alive in the long term and, via Funding Goals, all users get access to all functions over time. But back to our initiative documentation. For the first time, we will now create it using mkdocs serve.

1 mkdocs serve
2INFO     -  Building documentation...
3INFO     -  Multirepo plugin importing docs...
4 decision-records (1.162 secs)
5INFO     -  Cleaning site directory
6INFO     -  Multirepo plugin is cleaning up temp_dir/
7INFO     -  Documentation built in 1.33 seconds
8INFO     -  [01:05:39] Watching paths for changes: 'docs', 'mkdocs.yml'
9INFO     -  [01:05:39] Serving on
10INFO     -  [01:05:39] Browser connected: http://localhost:8000/

If we now go to http://localhost:8000 in the browser, we get the following view.

So the documentation works already locally, but will reach so few to no one 😉 . Therefore, we need a central place where the documentation can be accessed. Since the decision records can be found on Github anyway, this is also a good place for the documentation. So we now create an action based on mkdocs-deploy-gh-pages. Before we look at the action further, we have to create a requirements.txt for the mkdocs plugins, because we need exactly the dependencies for the respective runs of the action.

1 pip freeze > requirements.txt
1name: Publish docs via GitHub Pages
3  push:
4    branches:
5      - main
8  build:
9    name: Deploy docs
10    runs-on: ubuntu-latest
11    steps:
12      - name: Checkout main
13        uses: actions/checkout@v2
15      - name: Deploy docs
16        uses: mhausenblas/mkdocs-deploy-gh-pages@master
17        # Or use mhausenblas/mkdocs-deploy-gh-pages@nomaterial to build without the mkdocs-material theme
18        env:
19          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
20          AccessToken: $(System.AccessToken)
21          CONFIG_FILE: mkdocs.yml
22          EXTRA_PACKAGES: build-base
23          # GITHUB_DOMAIN:
24          REQUIREMENTS: requirements.txt

With each push, the Github Action is executed and creates a new version of the documentation.


As we have seen, the development of a documentation system, which can also grow into a documentation platform, is possible with little programming effort, almost low-code-like. mkdocs with all its plug-ins and perhaps one or two of our own developments will accompany us on our way in the coming weeks. Next week we'll be looking in the direction of the API guidelines. So long!


GitHub - danielkocot/decision_records_example

GitHub - danielkocot/acme-api-initiative: An example for a documentation platform with mkdocs

Photo by Maksym Kaharlytskyi on Unsplash

share post




More articles in this subject area

Discover exciting further topics and let the codecentric world inspire you.


Gemeinsam bessere Projekte umsetzen.

Wir helfen deinem Unternehmen.

Du stehst vor einer großen IT-Herausforderung? Wir sorgen für eine maßgeschneiderte Unterstützung. Informiere dich jetzt.

Hilf uns, noch besser zu werden.

Wir sind immer auf der Suche nach neuen Talenten. Auch für dich ist die passende Stelle dabei.