action-build-mkdocs

This action builds mkdocs Markdown documents into an HTML site. By default it also creates the techdocs-metadata.json that backstage requires for publication.

Usage

This action is intended to be used as part of a workflow that builds and publishes backstage documents to Flexport's Backstage Portal but it is not tied to it. It can be used stand alone to just generate HTML sites from mkdocs structured documentation.

Inputs

• docs-dir: The directory where the mkdocs.yml and the requirements.txt files are to be found and where the Markdown content needs to be located.
  • Default: ., the root directory of the repository
• site-target-dir: The directory where the HTML site is to be generated, RELATIVE to the value specified in docs-dir
  • Default: ./gen-site
• requirements-file-name: The name of the python pip requirements file containing all the extensions and plugins for mkdocs RELATIVE to docs-dir. Note that this action supports some extensions that require non-python tools, installed separately. These are:
  • PlantUml for diagraming
  • Latex/Texlive For math formatting
  • Graphviz as support for PlantUml and to access other types of diagrams.
  • Pandoc for format conversions. If your mkdocs configuration needs other non-python tools, it is your responsibility to configure them at the right place in your workflow before calling this action.
  • Default: requirements.txt
• mkdocs-file-name: The name of the mkdocs config file relative to docs-dir
  • Default: mkdocs.yml

Outputs

• generated-site: The path to the directory of the generated site, RELATIVE to the root of the repository.

Versions

This action follows Semantic versioning.

• v1 : Latest of the 1.x.y series
• v1.0: Latest of the 1.0.y series
• v1.0.0: Current version

Example Workflow

---
name: commerce-search-docs-gen-publish
on:
  push:
    branches:
      - main
jobs:
  generate-domain-docs:
    name: generate-docs
    runs-on: default
    steps:
      - name: Checkout code
        uses: actions/checkout@v3
      - name: Generate Docs
        id: gen-docs
        uses: jmpicnic/actions-gen-mkdocs@v1
        with:
          docs-dir: "./docs"
          site-target-dir: "site"
          requirements-file-name: special-requirements.txt
          mkdocs-file-name: mkdocs-ghpages.yml
          for-techdocs: False
      - name: Upload Pages artifact
        uses: actions/upload-pages-artifact@v2 
        with:
          path: ${{ steps.generate-docs.outputs.generated-site }}