{"id":4121,"library":"mkdocs-techdocs-core","title":"MkDocs TechDocs Core","description":"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.","status":"active","version":"1.6.1","language":"en","source_language":"en","source_url":"https://github.com/backstage/mkdocs-techdocs-core","tags":["mkdocs","backstage","techdocs","documentation","plugin","material-design"],"install":[{"cmd":"pip install mkdocs-techdocs-core","lang":"bash","label":"Install with pip"}],"dependencies":[],"imports":[{"note":"The plugin is configured in mkdocs.yml, not imported as a Python module in application code.","symbol":"techdocs-core","correct":"plugins:\n  - techdocs-core"}],"quickstart":{"code":"# 1. Create a project directory (e.g., 'my-techdocs-site')\n# 2. Inside 'my-techdocs-site', create an 'mkdocs.yml' file:\n#    ---\n#    site_name: My TechDocs Project\n#    nav:\n#      - Home: index.md\n#    plugins:\n#      - techdocs-core\n#    ---\n# 3. Inside 'my-techdocs-site', create a 'docs' directory.\n# 4. Inside 'docs', create an 'index.md' file:\n#    ---\n#    # Welcome to My TechDocs Project!\n#\n#    This is your documentation generated with MkDocs TechDocs Core.\n#    ---\n# 5. Run MkDocs serve from the 'my-techdocs-site' directory:\n#    mkdocs serve","lang":"bash","description":"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`)."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"All versions (specifically with `mkdocs-material` v9+)"},{"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`.","message":"`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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Use the `svg_inline` format instead of `svg_object` for PlantUML diagrams: `!['Diagram Name'](diagram.plantuml?svg_inline)`.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure your environment is running Python 3.9 or a newer compatible version.","message":"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.","severity":"breaking","affected_versions":"<1.0.0 (required >=3.8), >=1.0.0 (required >=3.9)"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}