📖 GitHub Action for Backstage TechDocs

This GitHub Action can be used for generating and publishing Backstage TechDocs.

Features

The action facilitated TechDocs CLI to generate and publish TechDocs sites.

• Building TechDocs only
• Building and publish TechDocs to cloud object storage
  • AWS S3
  • Azure Blob

Usage

Minimal Example

The following shows a minimal example of building and publishing TechDocs to AWS S3.

name: Publish TechDocs Site

on:
  push:
    branches:
      - main
    paths:
      - "docs/**"
      - "mkdocs.yml"
      - ".github/workflows/techdocs.yml"

jobs:
  publish-techdocs-site:
    name: Publish TechDocs Site
    runs-on: ubuntu-20.04
    steps:
      - name: Setup Node
        uses: Staffbase/backstage-techdocs-action@v1
        with:
          entity-name: 'pizza-service'
          publisher-type: 'azureBlobStorage'
          storage-name: 'techdocs'
          azure-account-name: ${{ secrets.TECHDOCS_AZURE_ACCOUNT_NAME }}
          azure-account-key: ${{ secrets.TECHDOCS_AZURE_ACCESS_KEY }}

Advanced Example

The following will skip the publish step (e.g. to verify site generation in a pull request) and installs additional plugins:

name: Publish TechDocs Site

on:
  push:
    paths:
      - "docs/**"
      - "mkdocs.yml"
      - ".github/workflows/techdocs.yml"

jobs:
  publish-techdocs-site:
    name: Publish TechDocs Site
    runs-on: ubuntu-20.04
    steps:
      - name: Setup Node
        uses: Staffbase/backstage-techdocs-action@v1
        with:
          entity-name: 'pizza-service'
          additional-plugins: 'mkdocs-minify-plugin\>=0.3 mkdocs-awesome-pages-plugin==2.8.0 mdx_include==1.4.2'
          skip-publish: 'true'

Configuration

Name	Description	Required	Default
entity-namespace	Entity namespace in Backstage	true	default
entity-kind	Kind of the Backstage entity	true	Component
entity-name	Name of the Backstage entity	true
publisher-type	awsS3 or azureBlobStorage. If not set, generated site will not be published.	false
storage-name	In case of AWS, use the bucket name. In case of Azure, use container name.	false
aws-region	Required if publisher-type: awsS3 - AWS Region	false	eu-central-1
aws-access-key-id	Required if publisher-type: awsS3 - AWS Access Key ID	false
aws-secret-access-key	Required if publisher-type: awsS3 - AWS Secret Access Key	false
azure-account-name	Required if publisher-type: azureBlobStorage - Azure Account Name	false
azure-account-key	Required if publisher-type: azureBlobStorage - Azure Account Key	false
additional-plugins	Space separated list of additional python plugins (Bash quoting for special chars)	false
skip-publish	Indicates whether publish step should be skipped	false	false

Contributing

Please read CONTRIBUTING.md for details on our code of conduct, and the process for submitting pull requests to us.

License

This project is licensed under the Apache-2.0 License - see the LICENSE.md file for details.

Staffbase GmbH Staffbase is an internal communications platform built to revolutionize the way you work and unite your company. Staffbase is hiring: jobs.staffbase.com GitHub | Website | Jobs