diff --git a/docs/features/techdocs/creating-and-publishing.md b/docs/features/techdocs/creating-and-publishing.md index 93ce3ad4d9..c0989bf02e 100644 --- a/docs/features/techdocs/creating-and-publishing.md +++ b/docs/features/techdocs/creating-and-publishing.md @@ -5,11 +5,12 @@ sidebar_label: Creating and Publishing Documentation description: Guidance on how to create and publish documentation --- -This section will guide you through: +This section will guide you through how to: - [Create a basic documentation setup](#create-a-basic-documentation-setup) + - [Use any software template](#use-any-software-template) - [Use the documentation template](#use-the-documentation-template) - - [Manually add documentation setup to already existing repository](#manually-add-documentation-setup-to-already-existing-repository) + - [Enable documentation for an already existing entity](#enable-documentation-for-an-already-existing-entity) - [Writing and previewing your documentation](#writing-and-previewing-your-documentation) ## Prerequisites @@ -21,29 +22,47 @@ This section will guide you through: If you have an existing repository that you'd like to add documentation to, skip to the -[Manually add documentation setup](#manually-add-documentation-setup-to-already-existing-repository) -section below. Otherwise, continue reading to start a documentation repo from -scratch. +[Enable documentation for an already existing entity setup](#enable-documentation-for-an-already-existing-entity) +section below. Otherwise, continue reading to create a new software entity +including documentation from scratch. + +### Use any software template + +TechDocs is built on top of the +[docs like code approach](https://www.docslikecode.com/about/). This, in short, +means that you should keep documentation close to the code. + +Your Backstage app has a set of software templates added by default. All of +these software templates include everything you need to get your TechDocs site +up and running and to start writing your documentation. + +If you have created software templates that do not include documentation by +default, we highly recommend you to set that up. Follow our how-to guide +[How to add documentation setup to your software templates](./how-to-guides.md#how-to-add-documentation-setup-to-your-software-templates) +to get started. ### Use the documentation template -Your working Backstage instance should by default have a documentation template -added. If not, copy the catalog locations from the +There could be _some_ situations where you don't want to keep your docs close to +your code, but still want to publish documentation - for example, an onboarding +tutorial. For this use case, we have put together a documentation template. Your +Backstage instance should by default have a documentation template added. If +not, copy the catalog locations from the [create-app template](https://github.com/backstage/backstage/blob/master/packages/create-app/templates/default-app/app-config.yaml.hbs) -to add the documentation template. The template creates a component with only -TechDocs configuration and default markdown files as below mentioned in manual -documentation setup, and is otherwise empty. +to add the documentation template. The template creates a component with +**only** TechDocs configuration and default markdown files, and is otherwise +empty. ![Documentation Template](../../assets/techdocs/documentation-template.png) Create an entity from the documentation template and you will get the needed setup for free. -### Manually add documentation setup to already existing repository +### Enable documentation for an already existing entity Prerequisites: -- An existing component +- An existing entity [registered in backstage](../software-catalog/index.md#adding-components-to-the-catalog) (e.g. via a `catalog-info.yaml` file). @@ -72,11 +91,11 @@ metadata: The [`backstage.io/techdocs-ref` annotation](../software-catalog/well-known-annotations.md#backstageiotechdocs-ref) is used by TechDocs to download the documentation source files for generating an -Entity's TechDocs site. +entity's TechDocs site. -Create a `/docs` folder in the root of the project with at least an `index.md` -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.)_ +Create a `/docs` folder in the root of your repository with at least an +`index.md` file in it. _(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.)_ > Note - Although `docs` is a popular directory name for storing documentation, > it can be renamed to something else and can be configured by `mkdocs.yml`. See @@ -95,9 +114,10 @@ updated documentation next time you run Backstage! ## Writing and previewing your documentation -Using the `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. +Using the [techdocs-cli](https://github.com/backstage/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: diff --git a/docs/features/techdocs/how-to-guides.md b/docs/features/techdocs/how-to-guides.md index 9c41c6dde2..edca4e84ad 100644 --- a/docs/features/techdocs/how-to-guides.md +++ b/docs/features/techdocs/how-to-guides.md @@ -348,3 +348,75 @@ const app = createApp({ ], }); ``` + +## How to add the documentation setup to your software templates + +[Software Templates](https://backstage.io/docs/features/software-templates/software-templates-index) +in Backstage is a tool that can help your users to create new components out of +already configured templates. It comes with a set of default templates to use, +but you can also +[add your own templates](https://backstage.io/docs/features/software-templates/adding-templates). + +If you have your own templates set up, we highly recommend that you include the +required setup for TechDocs in those templates. When creating a new component, +your users will then get a TechDocs site up and running automatically, ready for +them to start writing technical documentation. + +The purpose of this how-to guide is to walk you through how to add the required +configuration and some default markdown files to your new template. You can use +the +[react-ssr-template](https://github.com/backstage/software-templates/tree/main/scaffolder-templates/react-ssr-template) +as a reference when walking through the steps. + +Prerequisites: + +- An existing software template including a `template.yaml` together with a + skeleton folder including at least a `catalog-info.yaml`. + +1. Update your component's entity description by adding the following lines to + the `catalog-info.yaml` in your skeleton folder. + +```yaml +annotations: + backstage.io/techdocs-ref: dir:. +``` + +The +[`backstage.io/techdocs-ref` annotation](../software-catalog/well-known-annotations.md#backstageiotechdocs-ref) +is used by TechDocs to download the documentation source files for generating an +entity's TechDocs site. + +2. Create an `mkdocs.yml` file in the root of your skeleton folder with the + following content: + +```yaml +site_name: ${{values.component_id}} +site_description: ${{values.description}} + +nav: + - Introduction: index.md + +plugins: + - techdocs-core +``` + +3. Create a `/docs` folder in the skeleton folder with at least an `index.md` + file in it. + +The `docs/index.md` can for example have the following content: + +```md +# ${{ values.component_id }} + +${{ values.description }} + +## Getting started + +Start writing your documentation by adding more markdown (.md) files to this +folder (/docs) or replace the content in this file. +``` + +> Note: The values of `site_name`, `component_id` and `site_description` depends +> on how you have configured your `template.yaml` + +Done! You now have support for TechDocs in your own software template!