CommunitySolidServer/.github/workflows/mkdocs.yml

name: Documentation
on:
  workflow_call:

  # Additional trigger to deploy changes to the documentation/ folder
  #   on push to main, ignoring tags so we don't trigger twice upon release
  push:
    branches:
      - main
    paths:
      - documentation/**
    tags-ignore:
      - '*'

jobs:
  mkdocs-prep:
    # Runs the markdown linter to ensure we don't release faulty markdown.
    # Also gets the correct major version, whether the job is triggered by a version tag
    #   or a push to main to update the latest documentation.
    runs-on: ubuntu-latest
    outputs:
      major: ${{ steps.tagged_version.outputs.major || steps.current_version.outputs.major }}
    steps:
      - uses: actions/checkout@v4.2.0
      - uses: actions/setup-node@v4
        with:
          node-version: 16.x
      - run: npm ci --ignore-scripts
      - name: Lint documentation markdown
        run: npm run lint:markdown -- documentation/**/*.md
      - if: startsWith(github.ref, 'refs/tags/v')
        name: Get tagged version
        id: tagged_version
        uses: battila7/get-version-action@v2
      - if: github.ref == 'refs/heads/main'
        name: Get current version
        id: current_version
        run: |
          VERSION=$(git show origin/main:package.json | jq -r .version | grep -Po '^(\d+)')
          echo "major=$VERSION" >> $GITHUB_OUTPUT

  mkdocs:
    runs-on: ubuntu-latest
    needs: mkdocs-prep
    steps:
      - uses: actions/checkout@v4.2.0
      - uses: actions/setup-python@v5
        with:
          python-version: 3.x
      - run: pip install mkdocs-material
      - run: pip install mike
      - run: git config user.name ci-bot
      - run: git config user.email ci-bot@example.com
      - run: git fetch origin gh-pages --depth=1
      - run: |
          cd documentation && mike deploy --push --update-aliases \
            ${{ needs.mkdocs-prep.outputs.major }}.x latest

  typedocs:
    # Build typedocs and publish them to the GH page.
    # `mike deploy` overwrites the entire folder for a version so these need to be (re)built afterwards.
    needs: [mkdocs-prep, mkdocs]
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4.2.0
      - uses: actions/setup-node@v4
        with:
          node-version: 16.x
      - run: npm ci --ignore-scripts
      - name: Generate typedocs
        run: npm run typedocs
      - name: Deploy typedocs
        uses: peaceiris/actions-gh-pages@v4
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./docs
          destination_dir: ${{ needs.mkdocs-prep.outputs.major }}.x/docs