From 3452e3dd029b5ae4a081f91955674794f1032c2e Mon Sep 17 00:00:00 2001 From: Christof Leuenberger Date: Fri, 8 Dec 2023 15:07:36 +0100 Subject: [PATCH] Describe how to add standalone techdocs The documentation template doesn't seem to exist any longer. Add the minimal steps in order to help users get started with creating a standalone techdocs documentation. Signed-off-by: Christof Leuenberger Signed-off-by: e553956 Signed-off-by: Christof Leuenberger Fix typo in mcdocs Signed-off-by: Christof Leuenberger Signed-off-by: e553956 Add requested changes - Use filename titles for code blocks - Link to documentation on how to add a component to catalog - Consistent use of quotes and file endings Signed-off-by: Christof Leuenberger Signed-off-by: e553956 Add mandatory owner field to example Signed-off-by: Christof Leuenberger Signed-off-by: e553956 Fix prettier issues Signed-off-by: e553956 --- .../techdocs/creating-and-publishing.md | 69 ++++++++++++++----- 1 file changed, 51 insertions(+), 18 deletions(-) diff --git a/docs/features/techdocs/creating-and-publishing.md b/docs/features/techdocs/creating-and-publishing.md index f63ff43b7f..1251f67276 100644 --- a/docs/features/techdocs/creating-and-publishing.md +++ b/docs/features/techdocs/creating-and-publishing.md @@ -9,8 +9,8 @@ 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) - [Enable documentation for an already existing entity](#enable-documentation-for-an-already-existing-entity) + - [Create a standalone documentation](#create-a-standalone-documentation) - [Writing and previewing your documentation](#writing-and-previewing-your-documentation) ## Prerequisites @@ -41,23 +41,6 @@ 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-the-documentation-setup-to-your-software-templates) to get started. -### Use the documentation template - -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, 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. - ### Enable documentation for an already existing entity Prerequisites: @@ -115,6 +98,56 @@ 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! +### Create a standalone documentation + +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 case, you can create a documentation component, which will be +published as a standalone part of TechDocs. + +First, create an entity for your documentation. A minimal example could look like +this: + +```yaml title="catalog-info.yaml" +apiVersion: backstage.io/v1alpha1 +kind: Component +metadata: + name: a-unique-name-for-your-docs + annotations: + # this could also be `url:` if the documentation isn't in the same location + backstage.io/techdocs-ref: dir:. +spec: + type: documentation + lifecycle: experimental + owner: user-or-team-name +``` + +Next, create the config file for [mkdocs](https://www.mkdocs.org/), which will be +used to parse your docs: + +```yaml title="mkdocs.yml" +site_name: a-unique-name-for-your-docs +site_description: An informative description +plugins: + - techdocs-core +nav: + - Getting Started: index.md +``` + +Finally, add your index.md Markdown file, in a folder named `docs/` with your desired +documentation in Markdown. Your file structure should now look like this: + +``` +your-great-documentation/ + docs/ + index.md + catalog-info.yaml + mkdocs.yml +``` + +Last but not least, register your component in the software catalog using +[one of several options](../software-catalog/index.md#adding-components-to-the-catalog). + ## Writing and previewing your documentation Using the [techdocs-cli](https://github.com/backstage/backstage/tree/master/packages/techdocs-cli) you can