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 <christof.leuenberger@gmail.com> Signed-off-by: e553956 <christof.leuenberger@sbb.ch> Signed-off-by: Christof Leuenberger <christof.leuenberger@gmail.com> Fix typo in mcdocs Signed-off-by: Christof Leuenberger <christof.leuenberger@gmail.com> Signed-off-by: e553956 <christof.leuenberger@sbb.ch> 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 <christof.leuenberger@gmail.com> Signed-off-by: e553956 <christof.leuenberger@sbb.ch> Add mandatory owner field to example Signed-off-by: Christof Leuenberger <christof.leuenberger@gmail.com> Signed-off-by: e553956 <christof.leuenberger@sbb.ch> Fix prettier issues Signed-off-by: e553956 <christof.leuenberger@sbb.ch>
This commit is contained in:
@@ -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.
|
||||
|
||||

|
||||
|
||||
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:<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
|
||||
|
||||
Reference in New Issue
Block a user