In the last blog post, we showed how to publish the API of a simple Spring REST Application and provide an API documentation in a OpenAPI/Swagger way. In this blog post, we will extend the example and show how to integrate Backstage Techdocs.
If you’re looking to streamline your documentation process within your organization, integrating TechDocs into Spotify’s Backstage can be a game-changer. TechDocs provides a unified, seamless documentation experience directly within your Backstage instance. This blog post will provide information about the entire setup process, from prerequisites to deployment and show an example.
Prerequisites
- Backstage Application: A running instance of Backstage.
- Node.js and Yarn: Installed on your machine.
First, you have to check, if Techdocs is already installed. If you have created your Backstage app with npx @backstage/create-app, TechDocs may already be present.
Otherwise, you need to perform the following steps (detailed instructions can be found in the Backstage documentation at https://backstage.io/docs/features/techdocs/getting-started):
- Adding the Techdocs frontend plugin
- Adding the Techdocs backend plugin
Bear in mind, that if you deploy Techdocs on your local computer, you need Docker installed – otherwise it will not work by default. If you run Techdocs in a containerized environment, you can run the Techdocs Docker logic outside the Backstage container. You also have to figure out, where to store your documentation. The best way would be to use some kind of object storage (AWS S3, Google Cloud Storage and so on) outside the Backstage deployment and have some CI/CD pipeline to publish documentation.
Once again, the exact configuration is described in the Backstage documentation. We will use a local installation here, and use the following snippet in the app-config.yaml
techdocs:
builder: 'local' # Alternatives - 'external'
generator:
runIn: 'docker' # Alternatives - 'local'
publisher:
type: 'local' # Alternatives - 'googleGcs' or 'awsS3'. Read documentation for using alternatives.
Writing the backstage entities for Techdocs
Once, Techdocs is configured you can begin with designing your entities for Techdocs. In the last blog post, we were already setting up a directory structure. That will be our starting point:
Now let’s take a look in the mkdocs.yaml:
site_name: backstage-sample-app
nav:
- Overview: index.md
- Quick Start: sample.md
- Business Logic:
- Employees: employees.md
- System Architecture : architecture.md
- Code Structure: structure.md
plugins:
- techdocs-core
The site_name property defines the name of the documentation with Techdocs. We then define the navigation consisting of five different menu items. The plugins property configures how Backstage will render the documentation. In our simple scenario, techdocs-core is sufficient, but there might be use cases where you want to diagrams or other visual elements, where you need additional plugins.
Now let’s show a simple markdown file:
# Structure
"Wenn ich Hunger in der Jacke habe, dann kenne ich mich nicht vor Wut! Von Natur bin ich aber friedlich!"
"Es ist mir hier zu laut, ich kann nicht richtig kauen!“
"Hat dir eigentlich schon mal einer mit einem Vorschlaghammer einen Scheitel gezogen?"
"Wenn du denkst, du hast ’nen Dummen vor dir, bist du an der richtigen Adresse!"
"Gegen meine Kelle hilft nicht mal ein Waffenschein"
"Ganz ruhig, sonst drücken wir das Köpfchen in deinen Hals."
"Ohne Heu kann das beste Pferd nicht furzen."
"Mamor, Stein und Eisen bricht, aber mein kleines Fäustchen nicht!"
Once we are finished, with our documentation. We can upload it either manually to Backstage or in case we configured a object storage, we can upload the files to the object storage location. If we want to do it manually, just navigate to Create… on the left nagivation area, click on “REGISTER EXISTING COMPONENT” and upload the configuration files as described before. In our case, the all.yaml files had an annotation referencing to the Techdocs configuration.
annotations:
backstage.io/techdocs-ref: dir:.
Now we can navigate to Docs and choose our application:
> Click here for Part 14: Backstage Software Templates
