Skip to main content

Troubleshooting TechDocs

Documentation not found when generating​

This may happen if you have TechDocs set up using the "out-of-the-box" configuration, wherein documentation is built dynamically by the TechDocs backend, and your TechDocs files are being pulled from a git-based source control management system (e.g. GitHub, BitBucket, etc).

If you experience this, check that TechDocs-related files (e.g. markdown, assets, or the mkdocs.yml file) are not matched by an export-ignore attribute in a .gitattributes file in the relevant repository.

TechDocs' backend is not able to see such files, and therefore may generate partial (or no) TechDocs as a result.

You'll need to reconsider how you distribute tar archives based on your source code (and how you prevent internal documentation from being included in those archives). Alternatively, you could consider switching to the "recommended" TechDocs architecture (documentation generated and published in CI/CD).

MkDocs Build Errors​

Using the TechDocs CLI, you can troubleshoot MkDocs build issues locally. Note this requires you have Docker available to launch images. First, git clone the target repository locally, then in the root of the repository, run:

npx @techdocs/cli serve

For example, if you have forgotten to put an MkDocs configuration file in your repo, the resulting error will be:

npx: installed 278 in 9.089s
[techdocs-preview-bundle] Running local version of Backstage at http://localhost:3000
INFO    -  Building documentation...

Config file '/content/mkdocs.yml' does not exist.

When it works, a local copy of both Backstage and your site will be launched locally:

npx: installed 278 in 9.682s
[techdocs-preview-bundle] Running local version of Backstage at http://localhost:3000
INFO    -  Building documentation...
WARNING -  Config value: 'dev_addr'. Warning: The use of the IP address '0.0.0.0'
  suggests a production environment or the use of a proxy to connect to the MkDocs
  server. However, the MkDocs' server is intended for local development purposes only.
  Please use a third party production-ready server instead.
INFO    -  Cleaning site directory
DEBUG   -  Successfully imported extension module "plantuml_markdown".
DEBUG   -  Successfully loaded extension "plantuml_markdown.PlantUMLMarkdownExtension".
INFO    -  Documentation built in 0.23 seconds
[I 210115 19:00:45 server:335] Serving on http://0.0.0.0:8000
INFO    -  Serving on http://0.0.0.0:8000
[I 210115 19:00:45 handlers:62] Start watching changes
INFO    -  Start watching changes
[I 210115 19:00:45 handlers:64] Start detecting changes
INFO    -  Start detecting changes

PlantUML with svg_object doesn't render​

The plantuml-markdown MkDocs plugin available in mkdocs-techdocs-core supports different formats for rendering diagrams. TechDocs does however not support all of them.

The svg_object format renders a diagram as an HTML <object> tag but this is not allowed as it enables bad actors to inject malicious content into documentation pages. See CVE-2021-32661 for more details.

Instead use svg_inline which renders as an <svg> tag and provides the same benefits as svg_object.