Fix header nesting in software-templates docs

Most pages in the 'Software Templates' docs seemed to have one level too much nesting. This fixes that. Without the correct nesting, the table of contents on the right side was also missing and made reading the longer pages (e.g. writing-templates) more difficult to read. What's odd is that when rendering with `mkdocs` locally the nesting seems to be okay and the table of content renders. Pages affected live: - https://backstage.io/docs/features/software-templates/software-templates-index - https://backstage.io/docs/features/software-templates/configuration - https://backstage.io/docs/features/software-templates/writing-templates - https://backstage.io/docs/features/software-templates/builtin-actions - https://backstage.io/docs/features/software-templates/writing-custom-actions https://backstage.io/docs/features/software-templates/adding-templates is okay because it has no subheadings. And these two are okay because they have correct nesting starting at level two (`##`): - https://backstage.io/docs/features/software-templates/writing-custom-field-extensions - https://backstage.io/docs/features/software-templates/migrating-from-v1beta2-to-v1beta3 Signed-off-by: Luna Stadler <luc@spreadshirt.net>
2022-03-01 11:46:07 +01:00
parent f587dcc5bf
commit 33ae7f244b
5 changed files with 22 additions and 22 deletions
@@ -15,13 +15,13 @@ A list of all registered actions can be found under `/create/actions`. For local
 development you should be able to reach them at
 `http://localhost:3000/create/actions`.

-### Migrating from `fetch:cookiecutter` to `fetch:template`
+## Migrating from `fetch:cookiecutter` to `fetch:template`

 The `fetch:template` action is a new action with a similar API to
 `fetch:cookiecutter` but no dependency on `cookiecutter`. There are two options
 for migrating templates that use `fetch:cookiecutter` to use `fetch:template`:

-#### Using `cookiecutterCompat` mode
+### Using `cookiecutterCompat` mode

 The new `fetch:template` action has a `cookiecutterCompat` flag which should
 allow most templates built for `fetch:cookiecutter` to work without any changes.
@@ -43,7 +43,7 @@ allow most templates built for `fetch:cookiecutter` to work without any changes.
        values:
 ```

-#### Manual migration
+### Manual migration

 If you prefer, you can manually migrate your templates to avoid the need for
 enabling cookiecutter compatibility mode, which will result in slightly less
@@ -18,7 +18,7 @@ The next step is to add
 [add templates](http://backstage.io/docs/features/software-templates/adding-templates)
 to your Backstage app.

-### Publishing defaults
+## Publishing defaults

 Software templates can define _publish_ actions, such as `publish:github`, to
 create new repositories or submit pull / merge requests to existing
@@ -45,7 +45,7 @@ add the `repoVisibility` key within a software template:
    repoVisibility: public # or 'internal' or 'private'
 ```

-### Disabling Docker in Docker situation (Optional)
+## Disabling Docker in Docker situation (Optional)

 Software templates use the `fetch:template` action by default, which requires no
 external dependencies and offers a
@@ -68,7 +68,7 @@ RUN apt-get update && apt-get install -y python3 python3-pip
 RUN pip3 install cookiecutter
 ```

-### Customizing the ScaffolderPage with Grouping and Filtering
+## Customizing the ScaffolderPage with Grouping and Filtering

 Once you have more than a few software templates you may want to customize your
 `ScaffolderPage` by grouping and surfacing certain templates together. You can
@@ -15,7 +15,7 @@ locations like GitHub or GitLab.
  <source src="https://backstage.io/blog/assets/2020-08-05/feature.mp4" type="video/mp4" />
 </video>

-### Getting Started
+## Getting Started

 > Be sure to have covered
 > [Getting Started with Backstage](../../getting-started) before proceeding.
@@ -27,7 +27,7 @@ Once there, you should see something that looks similar to this:

 ![Create Image](../../assets/software-templates/create.png)

-### Choose a template
+## Choose a template

 When you select a template that you want to create, you'll be taken to the next
 page which may or may not look different for each template. Each template can
@@ -44,7 +44,7 @@ provider, for instance `https://github.com/backstage/my-new-repository`, or

 ![Enter Backstage vars](../../assets/software-templates/template-picked-2.png)

-### Run!
+## Run!

 Once you've entered values and confirmed, you'll then get a popup box with live
 progress of what is currently happening with the creation of your template.
@@ -60,7 +60,7 @@ step that failed which can be helpful in debugging.

 ![Templating failed](../../assets/software-templates/failed.png)

-### View Component in Catalog
+## View Component in Catalog

 When it's been created, you'll see the `View in Catalog` button, which will take
 you to the registered component in the catalog:
@@ -12,7 +12,7 @@ by writing custom actions which can be used along side our
 > built-in actions too**. To ensure you can continue to include the builtin
 > actions, see below to include them during registration of your action.

-### Writing your Custom Action
+## Writing your Custom Action

 Your custom action can live where you choose, but simplest is to include it
 alongside your `backend` package in `packages/backend`.
@@ -79,7 +79,7 @@ The `createTemplateAction` takes an object which specifies the following:
  function using `ctx.output`
 - `handler` - the actual code which is run part of the action, with a context

-#### The context object
+### The context object

 When the action `handler` is called, we provide you a `context` as the only
 argument. It looks like the following:
@@ -98,7 +98,7 @@ argument. It looks like the following:
 - `ctx.metadata` - an object containing a `name` field, indicating the template
  name. More metadata fields may be added later.

-### Registering Custom Actions
+## Registering Custom Actions

 Once you have your Custom Action ready for usage with the scaffolder, you'll
 need to pass this into the `scaffolder-backend` `createRouter` function. You
@@ -145,7 +145,7 @@ return await createRouter({
 });
 ```

-### List of custom action packages
+## List of custom action packages

 Here is a list of Open Source custom actions that you can add to your Backstage
 scaffolder backend:
@@ -99,7 +99,7 @@ spec:

 Let's dive in and pick apart what each of these sections do and what they are.

-### `spec.parameters` - `FormStep | FormStep[]`
+## `spec.parameters` - `FormStep | FormStep[]`

 These `parameters` are template variables which can be modified in the frontend
 as a sequence. It can either be one `Step` if you just want one big list of
@@ -227,7 +227,7 @@ spec:
            inputType: tel
 ```

-#### Hide or mask sensitive data on Review step
+### Hide or mask sensitive data on Review step

 Sometimes, specially in custom fields, you collect some data on Create form that
 must not be shown to the user on Review step. To hide or mask this data, you can
@@ -254,7 +254,7 @@ use `ui:widget: password` or set some properties of `ui:backstage`:
          show: false # wont print any info about 'hidden' property on Review Step
 ```

-#### The Repository Picker
+### The Repository Picker

 In order to make working with repository providers easier, we've built a custom
 picker that can be used by overriding the `ui:field` option in the `uiSchema`
@@ -287,7 +287,7 @@ The `RepoUrlPicker` is a custom field that we provide part of the
 `plugin-scaffolder`. You can provide your own custom fields by
 [writing your own Custom Field Extensions](./writing-custom-field-extensions.md)

-##### Using the Users `oauth` token
+#### Using the Users `oauth` token

 There's a little bit of extra magic that you get out of the box when using the
 `RepoUrlPicker` as a field input. You can provide some additional options under
@@ -360,7 +360,7 @@ There's also the ability to pass additional scopes when requesting the `oauth`
 token from the user, which you can do on a per-provider basis, in case your
 template can be published to multiple providers.

-#### The Owner Picker
+### The Owner Picker

 When the scaffolder needs to add new components to the catalog, it needs to have
 an owner for them. Ideally, users should be able to select an owner when they go
@@ -380,7 +380,7 @@ owner:
      - Group
 ```

-### `spec.steps` - `Action[]`
+## `spec.steps` - `Action[]`

 The `steps` is an array of the things that you want to happen part of this
 template. These follow the same standard format:
@@ -400,7 +400,7 @@ By default we ship some [built in actions](./builtin-actions.md) that you can
 take a look at, or you can
 [create your own custom actions](./writing-custom-actions.md).

-### Outputs
+## Outputs

 Each individual step can output some variables that can be used in the
 scaffolder frontend for after the job is finished. This is useful for things
@@ -415,7 +415,7 @@ output:
  entityRef: ${{ steps.register.output.entityRef }} # link to the entity that has been ingested to the catalog
 ```

-### The templating syntax
+## The templating syntax

 You might have noticed variables wrapped in `${{ }}` in the examples. These are
 template strings for linking and gluing the different parts of the template