Package: mkdocs-techdocs-core
mkdocs-techdocs-coreThis is the baseMkdocsplugin used when using Mkdocs with Spotify'sTechDocs. It is written in Python and packages all of our Mkdocs defaults, such as theming, plugins, etc in a single plugin.UsageRequires Python version >= 3.8$pipinstallmkdocs-techdocs-coreOnce you have installed themkdocs-techdocs-coreplugin, you'll need to add it to yourmkdocs.yml.site_name:Backstage Docsnav:-Home:index.md-Developing a Plugin:developing-a-plugin.mdplugins:-techdocs-coreDevelopmentRunning LocallyYou can install this package locally usingpipand the--editableflag used for making developing Python packages.pipinstall--editable.You'll then have thetechdocs-corepackage available to use in Mkdocs andpipwill point the dependency to this folder.LintingWe useblackas our linter. Please run it against your code before submitting a pull request.pipinstallblack
black.Note:This will write to all Python files insrc/with the formatted code. If you would like to only check to see if it passes, simply append the--checkflag.Testing Dependencies End-to-EndIf you have made changes to the plugin itself, or updated a dependency it's
strongly recommended to test the plugin.To build a version of thespotify/techdocsdocker image with your changes,
run the below script in this repository:./build-e2e-image.shThe script is only tested on OSXThe script assumes that you have theimage repositorycloned in a
sibling directory to this repository (or you can specify its location).It will build an image calledmkdocs:local-devincluding the changes you
have made locally. To test the image in backstage, edit the config (e.g.app-config.yaml) with the following:techdocs:generator:runIn:"docker"dockerImage:"mkdocs:local-dev"pullImage:falseReleaseUpdate theChangelog.Bump up the version number insetup.pywhich triggers the release workflow onGitHub Actionsto publish a new version in PyPI.MkDocs plugins and extensionsThe TechDocs Core MkDocs plugin comes with a set of extensions and plugins that mkdocs supports. Below you can find a list of all extensions and plugins that are included in the
TechDocs Core plugin:Plugins:search: A search plugin is provided by default with MkDocs which useslunr.jsas a search engine.mkdocs-monorepo-plugin: This plugin enables you to build multiple sets of documentation in a single MkDocs project. It is designed to address writing documentation in Spotify's largest and most business-critical codebases (typically monoliths or monorepos).Extensions:admonition: Admonitions, also known as call-outs, are an excellent choice for including side content without significantly interrupting the document flow. Material for MkDocs provides several different types of admonitions and allows for the inclusion and nesting of arbitrary content.toc: The Table of Contents extension generates a Table of Contents from a Markdown document and adds it into the resulting HTML document.
This extension is included in the standard Markdown library.pymdown: PyMdown Extensions is a collection of extensions for Python Markdown.
All extensions are found under the module namespace of pymdownx.caret: Caret is an extension that is syntactically built around the ^ character. It adds support for inserting superscripts and adds an easy way to place text in an <ins> tag.critic: Critic adds handling and support of Critic Markup.details: Details creates collapsible elements with <details> and <summary> tags.emoji: Emoji makes adding emoji via Markdown easy 😄.superfences: SuperFences is like Python Markdown's fences, but better. Nest fences under lists, admonitions, and other syntaxes. You can even create special custom fences for content like UML.inlinehilite: InlineHilite highlights inline code: from module import function as func.magiclink: MagicLink linkafies URL and email links without having to wrap them in Markdown syntax. Also, shortens repository issue, pull request, and commit links automatically for popular code hosting providers. You can even use special shorthand syntax to link to issues, diffs, and even mention peoplemark: Mark allows you to mark words easily.smartsymbols: SmartSymbols inserts commonly used Unicode characters via simple ASCII representations: =/= → ≠.highlight: Highlight allows you to configure the syntax highlighting of SuperFences and InlineHilite. Also passes standard Markdown indented code blocks through the syntax highlighter.extra: Extra is just like Python Markdown's Extra package except it uses PyMdown Extensions to substitute similar extensions.tabbed: Tabbed allows for tabbed Markdown content.tasklist: Tasklist allows inserting lists with check boxes.tilde: Tilde is syntactically built around the ~ character. It adds support for inserting subscripts and adds an easy way to place text in a <del> tag.markdown_inline_graphviz: A Python Markdown extension replaces inline Graphviz definitions with inline SVGs or PNGs.
Activate the inline_graphviz extension using theusage instructions.plantuml_markdown: This plugin implements a block extension which can be used to specify a PlantUML diagram which will be converted into an image and inserted in the document.Note that the formatsvg_objectis not supported for rendering diagrams. Read more in theTechDocs troubleshootingsection.mdx_truly_sane_lists: An extension for Python-Markdown that makes lists truly sane. Features custom indents for nested lists and fix for messy linebreaks and paragraphs between lists.Other plugins and extensionsNote that the above set of plugins and extensions represents an opinionated
list providing a core set of functionality necessary for most technical
documentation needs (hence:techdocs-core). PRs introducing new plugins or
extensions are welcome, but they are not guaranteed to be accepted.In order to solve your organization's specific needs, you're encouraged to
install any necessary extensions/plugins in your own environment on top oftechdocs-core(be it the TechDocs backend container, or a custom TechDocs
build container).CaveatsThemeWe only usematerial-mkdocsas base styles because Backstage also uses theMaterial UIon the client-side. We don't expect people to use themes other thanMaterial UIto maintain consistency across all Backstage pages (in other words, documentation pages have the same look and feel as any other Backstage page) and so we use theBackstageThemeconfigured in Front-end application as the source of truth for all application design tokens like colors, typography and etc. So here you canseethat some styles will always be overridden regardless of themkdocs-materialplugin theme settings and this can cause unexpected behavior for those who override the theme setting in amkdocs.yamlfile.ChangelogUnreleased1.3.3Bumpedmkdocs-materialto9.4.14which add support for: Mermaid.js version 10.6.1, emoji extension and updated MkDocs to 1.5.3Added tests forPythonversion3.111.3.2Bumpedpymdown-extensionsto10.3.1which add material.extensions supportRemoved support forPythonversion3.71.3.1Bumpedpygmentsto2.17.2which includes JSX support.1.3Bumpedmkdocs-material(and its dependencies) from9.1.3to9.2.7causing a few changes:MkDocs dependency is now1.5theme.paletteis now hardcoded to{}instead of""which caused some issues with some Material plugins1.2.3Bumpedpygmentsto2.16.1, which also fixes avulnerability.Update dependencyplantuml-markdownto3.9.2.1.2.2Added config override ofpymdownx.snippetsforsecurity.restrict_base_pathwill always betrue. If you currently use snippets with files outside of the directory, those files will no longer be included.1.2.1Use latest version ofpymdown-extensionswhich containssecurity fixes.1.2.0Updatedmkdocs-material(and its dependencies) from8.1.11to9.1.3causing a few changes:Somemkdocs-materialfeatures were made opt-in v9. In order to preserve compatibility, they are now hardcoded as enabled bymkdocs-techdocs-core. The features arenavigation.footercontent.action.edittheme.paletteis now hardcoded to""to preserve previous behavior. Without hardcoding the palette, it gets the valuedefault, causing unwanted visual changes.Some components e.g. admonitions have a slightly different look.Minor color changes that can be avoided by also updating to the latest version of@backstage/plugin-techdocswhich compensates these changes.1.1.7Updatedmkdocs-monorepo-pluginto1.0.4, which includes a compatibility
fix formkdocsversions1.4.0and newer.1.1.6Removed pins on thepyparsingandJinja2dependencies, which are no
longer needed.Pinnedmkdocs-monorepo-pluginandmarkdown_inline_graphviz_extensionto
specific (latest) releases to improve stability. Going forward, these (along
with all other feature-related deps) will be bumped regularly and any changes
will be reflected in this changelog.1.1.5Added support for Python 3.10#73Resolved a run-time error introduced in1.1.4that prevented sites from
being built under certain circumstances.1.1.4Support markdown version >3.2,<4Use markdown_inline_graphviz_extension 1.1.1 which supports svg rendering for markdown >=3.31.1.3Upgradedplantuml-markdownto3.5.1, which removesuuidas a dependency.1.1.2Simplify theme code to update only the attribute necessary by backstage.1.1.1Fix run-timeAttributeError: 'Theme' object has no attribute 'copy'1.1.0Add new capability to override mkdocs theme attributesNote:Look the caveats section in readme about the Backstage theme consideration1.0.2Bumpedpymdown-extensionsto 9.3 and enabledpygments_lang_classto allow easier targeting of codeblocks by language in TechDocs Addons.1.0.1Jinja2pinned to v3.0.3.1.0.0This package has been promoted to v1.0!Note:Going forward, this package will followsemverconventions.0.2.3Upgrade mkdocs-material and its dependencies0.2.2Updateplantuml-markdownversion to 3.5.0 for image maps support0.2.1Fix run-timemodule 'pyparsing' has no attribute 'downcaseTokens'error as
a result of shifting python dependencies.Update to latestmkdocs-monorepo-plugin, which allows use of.yamlfile
extensions and non-slug-likesite_names in monorepos.0.2.0Add mdx_truly_sane_lists for dealing with the very annoying bullet differences in mkdocs vs commonmark / gf markdown. Seehttps://github.com/backstage/backstage/issues/6057#issuecomment-8628220020.1.2Fix the dependency version of Markdown to ensure GraphViz SVG rendering works.0.1.1Ensure required mkdocs-monorepo-plugin is compatible with Mkdocs1.2.x.0.1.0Improved dependency compatibility with other mkdocs plugins.Upgraded mkdocs minimum to1.2.20.0.16Reused data fromrequirements.txtfile ininstall_requiresofsetup.py.#240.0.15Upgrade monorepo to track latest patch, includes various bug fixes.#220.0.14Upgrade plantuml-markdown to 3.4.2 with support for external file sources.#180.0.13Fixed issue where the whole temp directory could be included in the built site output.#70.0.12Updated home repository to be the newhttps://github.com/backstage/mkdocs-techdocs-core0.0.11Any MkDocs plugin configurations from mkdocs.yml will now work and override the default configuration. Seehttps://github.com/backstage/backstage/issues/30170.0.10Pin Markdown version to fix issue with Graphviz0.0.9Change development status to 3 - Alpha0.0.8Superfences and Codehilite doesn't work very well together (squidfunk/mkdocs-material#1604) so therefore the codehilite extension is replaced by pymdownx.highlightUses pymdownx extensions v.7.1 instead of 8.0.0 to allow legacy_tab_classes config. This makes the techdocs core plugin compatible with the usage of tabs for grouping markdown with the following syntax:```java tab="java 2"
        public void function() {
            ....
        }
    ```as well as the new=== "Java"

    ```java
    public void function() {
        ....
    }
    ```The pymdownx extension will be bumped too 8.0.0 in the near future.pymdownx.tabbed is added to support tabs to group markdown content, such as codeblocks."PyMdown Extensions includes three extensions that are meant to replace their counterpart in the default Python Markdown extensions." Therefore some extensions has been taken away in this version that comes by default from pymdownx.extra which is added now (https://facelessuser.github.io/pymdown-extensions/usage_notes/#incompatible-extensions)0.0.7Fix an issue with configuration of emoji support0.0.6Further adjustments to versions to find ones that are compatible0.0.5Downgrade some versions of markdown extensions to versions that are more stable0.0.4Added support for more mkdocs extensionsmkdocs-materialmkdocs-monorepo-pluginplantuml-markdownmarkdown_inline_graphviz_extensionpygmentspymdown-extensionsLicenseCopyright 2020-2023 © The Backstage Authors. All rights reserved. The Linux Foundation has registered trademarks and uses trademarks. For a list of trademarks of The Linux Foundation, please see our Trademark Usage page:https://www.linuxfoundation.org/trademark-usageLicensed under the Apache License, Version 2.0:http://www.apache.org/licenses/LICENSE-2.0