Skip to content
play

GitHub Action

MkDocs check and Backstage TechDocs publish

v1.0.3 Latest version

MkDocs check and Backstage TechDocs publish

play

MkDocs check and Backstage TechDocs publish

Run command for technical documentation generation

Installation

Copy and paste the following snippet into your .yml file.

 
              
- name: MkDocs check and Backstage TechDocs publish

              
  uses: TwistoPayments/actions-techdocs@v1.0.3
Learn more about this action in TwistoPayments/actions-techdocs

Choose a version

actions-techdocs

Github Action for Backstage's techdocs plugin from Spotify.

What does it do?

It scans the whole repository for the following files:

  • mkdocs.yaml
  • catalog-info.yaml

The action has two commands:

  • check - runs mkdocs build in all directories containing mkdocs.yaml and checks for any warnings or errors in the output
  • publish - runs techdocs publish in all directories containing catalog-info.yaml and mkdocs.yaml (the catalog file is used to extract kind/namespace/name of entity)

Usage

jobs:
  techdocs:
    name: Check & Publish
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repo
        uses: actions/checkout@v3

      # Runs mkdocs check in all directories containing **/mkdocs.yaml file
      - name: Run mkdocs check
        uses: TwistoPayments/actions-techdocs@main
        with:
          command: check

      # Runs techdocs generate and techdocs publish commands in all directories containgin
      # **/mkdocs.yaml file. Currently only S3 publisher is supported.
      - name: Run techdocs publish
        uses: TwistoPayments/actions-techdocs@main
        with:
          command: publish
        env:
          TECHDOCS_PUBLISHER_TYPE: awsS3
          TECHDOCS_S3_BUCKET_NAME: ${{ secrets.TECHDOCS_S3_BUCKET_NAME }}
          AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
          AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
          AWS_REGION: ${{ secrets.AWS_REGION }}

Alternatively, you can pull image from Docker Hub which will be faster as you won't need to build the image each time, just replace

        uses: TwistoPayments/actions-techdocs@main
        with:
          command: <check/publish>

with

        uses: docker://twistopayments/actions-techdocs:main
        with:
          args: <check/publish>