MkDocs TechDocs Core

1.6.1 · active · verified Sat Apr 11

The `mkdocs-techdocs-core` library is the core MkDocs plugin used by Backstage's TechDocs. It acts as a wrapper, bundling multiple essential MkDocs plugins and Python Markdown extensions to provide a consistent and opinionated set of features for technical documentation. As of version 1.6.1, it primarily focuses on simplifying the setup for Backstage users. Releases are typically driven by updates to underlying dependencies like `mkdocs-material` and new features for TechDocs, often leveraging Python Semantic Release.

Warnings

breaking Direct MkDocs Material theme overrides in `mkdocs.yml` might not work as expected due to `mkdocs-techdocs-core` hardcoding certain features (e.g., `navigation.footer` enabled, `theme.palette` reset) for Backstage consistency.
Fix: Avoid extensive theme customization in `mkdocs.yml` when using `mkdocs-techdocs-core` in a Backstage environment. Rely on Backstage's `BackstageTheme` for styling. If customization is critical, test thoroughly and be aware of potential overrides.
gotcha `mkdocs-techdocs-core` bundles many other MkDocs plugins (e.g., `search`, `mkdocs-monorepo-plugin`, `pymdown-extensions`). Explicitly listing these individual plugins in your `mkdocs.yml` *in addition to* `techdocs-core` can lead to 'plugin not installed' errors or conflicting behavior, as `techdocs-core` already manages their inclusion.
Fix: Do not configure individual plugins that are known to be bundled within `techdocs-core`. If you need additional plugins not included in the core bundle, install and configure them separately in your `mkdocs.yml` *after* `techdocs-core`.
gotcha The bundled `plantuml-markdown` extension in `mkdocs-techdocs-core` does not support the `svg_object` format for rendering diagrams due to security vulnerabilities (CVE-2021-32661). Using this format will result in diagrams not rendering.
Fix: Use the `svg_inline` format instead of `svg_object` for PlantUML diagrams: `!['Diagram Name'](diagram.plantuml?svg_inline)`.
breaking The library requires Python version 3.9 or higher. Using an older Python version (e.g., 3.8 or 3.7) will lead to installation failures or runtime errors.
Fix: Ensure your environment is running Python 3.9 or a newer compatible version.

Install

pip install mkdocs-techdocs-core Install with pip

Imports

techdocs-core
```
plugins:
  - techdocs-core
```
The plugin is configured in mkdocs.yml, not imported as a Python module in application code.

Quickstart

This quickstart demonstrates how to set up a basic MkDocs project using `mkdocs-techdocs-core`. It involves creating a project structure, configuring `mkdocs.yml` to enable the plugin, and adding a simple Markdown file, then serving the documentation locally. Make sure you have `mkdocs` installed globally or in your environment (`pip install mkdocs`).

# 1. Create a project directory (e.g., 'my-techdocs-site')
# 2. Inside 'my-techdocs-site', create an 'mkdocs.yml' file:
#    ---
#    site_name: My TechDocs Project
#    nav:
#      - Home: index.md
#    plugins:
#      - techdocs-core
#    ---
# 3. Inside 'my-techdocs-site', create a 'docs' directory.
# 4. Inside 'docs', create an 'index.md' file:
#    ---
#    # Welcome to My TechDocs Project!
#
#    This is your documentation generated with MkDocs TechDocs Core.
#    ---
# 5. Run MkDocs serve from the 'my-techdocs-site' directory:
#    mkdocs serve

view raw JSON →