This section will guide you through:
- Create a basic documentation setup
- Writing and previewing your documentation
- A working Backstage instance with TechDocs installed (see TechDocs getting started)
Create a basic documentation setup
Use the documentation template
Your working Backstage instance should by default have a documentation template added. If not, follow these instructions to add the documentation template.
Create an entity from the documentation template and you will get the needed setup for free.
Manually add documentation setup to already existing repository
catalog-info.ymlfile registered to Backstage.
mkdocs.yml file in the root of the repository with the following
site_name: 'example-docs' nav: - Home: index.md plugins: - techdocs-core
catalog-info.yaml file in the root of the repository with the
metadata: annotations: backstage.io/techdocs-ref: dir:./
/docs folder in the root of the project with at least a
file. (If you add more markdown files, make sure to update the nav in the
mkdocs.yml file to get a proper navigation for your documentation.)
docs/index.md can for example have the following content:
# example docs This is a basic example of documentation.
Commit your changes, open a pull request and merge. You will now get your updated documentation next time you run Backstage!
Writing and previewing your documentation
techdocs-cli you can preview your docs inside a local Backstage
instance and get live reload on changes. This is useful when you want to preview
your documentation while writing.
To do this you can run:
cd /path/to/docs-repository/ npx @techdocs/cli serve