backstagebackstage
107

Mkdocs Techdocs Core

screenshot of Mkdocs Techdocs Core

The core MkDocs plugin used by Backstage's TechDocs as a wrapper around multiple MkDocs plugins and Python Markdown extensions

Github

Overview

The mkdocs-techdocs-core is a powerful base plugin designed for integrating MkDocs with Spotify's TechDocs, all crafted in Python. This core plugin encapsulates essential MkDocs defaults, ensuring a seamless documentation experience through pre-configured theming, plugins, and other key functionalities. By offering a user-friendly interface, mkdocs-techdocs-core simplifies the documentation process for developers while adhering to best practices.

With the requirement of Python version 3.8 or higher, this plugin allows developers to set it up quickly and add it to their mkdocs.yml configuration. The modular design not only supports a robust documentation framework but also enhances the user experience through optional features such as advanced theming and search functionalities.

Features

  • Easy Installation: Quickly install the mkdocs-techdocs-core using pip, making it accessible for any project requiring MkDocs integration.

  • Built-in Plugins and Themes: Comes with default theming and plugins like search functionality via lunr.js, helping you to create appealing and functional documentation right out of the box.

  • Flexible Configuration: Modify the mkdocs.yml file for additional features, allowing for customization based on project needs without extensive code changes.

  • Development-friendly: Supports local development with pip's --editable flag for easy testing of changes alongside your project.

  • Linting Support: Utilizes black for code linting to ensure code quality and maintainability, promoting best coding practices before submission.

  • Testing Capabilities: Offers a script to build and test your changes in the Spotify TechDocs Docker image, ensuring that your local modifications behave as expected.

  • Automatic Release Management: Leverages PSR for automatic versioning and release notes generation based on commit messages, streamlining the release process for developers.

  • Modular Architecture: The inclusion of various MkDocs plugins and extensions allows for extensive functionality while keeping the core design lightweight and efficient.