TechDocs FAQ
This page answers frequently asked questions about TechDocs.
Technology
- What static site generator is TechDocs using?
- What is the mkdocs-techdocs-core plugin?
- Does TechDocs support file formats other than Markdown (e.g. RST, AsciiDoc)?
What static site generator is TechDocs using?
TechDocs is using MkDocs to build project documentation under the hood. Documentation built with the techdocs-container is using the MkDocs Material Theme.
What is the mkdocs-techdocs-core plugin?
The mkdocs-techdocs-core package is a MkDocs Plugin that works like a wrapper around multiple MkDocs plugins (e.g. MkDocs Monorepo Plugin) as well as a selection of Python Markdown extensions that TechDocs supports.
Does TechDocs support file formats other than Markdown (e.g. RST, AsciiDoc) ?
Not right now. We are currently using MkDocs to generate the documentation from source, so the files have to be in Markdown format. However, in the future we want to support other static site generators which will make it possible to use other file formats.
What should be the value of backstage.io/techdocs-ref
when using external build and storage?
The value of
backstage.io/techdocs-ref
metadata annotation is used in the build process of TechDocs. But when
techdocs.builder
is set to 'external'
in
app-config.yaml
, the value of the annotation remains unused. However the
annotation should still be present in entity descriptor file (e.g.
catalog-info.yaml
) for Backstage to know that TechDocs is enabled for the
entity.
Is it possible for users to suggest changes or provide feedback on a TechDocs page?
This is supported for TechDocs sites whose source code is hosted in either
GitHub or GitLab. In order to add "edit this page" and "leave feedback" buttons
on a TechDocs page, be sure that you have repo_url
and edit_uri
values in
your mkdocs.yml
files per
MkDocs instructions.
If the host name of your source code hosting URL does not include github
or
gitlab
, an integrations
entry in your app-config.yaml
pointed at your
source code provider is also needed (only the host
key is necessary).