Datasync/.github/workflows/build-docs.yml at main · CommunityToolkit/Datasync · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
name: Build and Deploy Documentation Site

on:
  push:
    branches: [ main ]
    paths: [ 'docs/**', 'mkdocs.yml', 'mkdocs.shared.yml', 'mkdocs.production.yml', '.github/workflows/build-docs.yml' ]
  pull_request:
    branches: [ main ]
    paths: [ 'docs/**', 'mkdocs.yml', 'mkdocs.shared.yml', 'mkdocs.production.yml', '.github/workflows/build-docs.yml' ]
  release:
    types: [ published ]
  workflow_dispatch:

permissions:
  contents: read

defaults:
  run:
    shell: bash

jobs:
  # Builds the production site and uploads it as a Pages artifact. Only needs to run when the
  # artifact might actually be deployed (see the 'deploy' job below).
  build:
    if: ${{ github.event_name == 'release' || github.event_name == 'workflow_dispatch' }}
    runs-on: ubuntu-latest
    steps:
      - name: Checkout Repository
        uses: actions/checkout@v7
        with:
          fetch-depth: 0

      - name: Install Python
        uses: actions/setup-python@v6
        with:
          python-version: 3.x

      - name: Install mkdocs
        run: pip install mkdocs mkdocs-mermaid2-plugin

      - name: Generate site
        run: mkdocs build -f ./mkdocs.production.yml

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v5
        with:
          path: ./site

  # Validates the docs site without ever deploying it: a strict mkdocs build catches broken
  # internal links/anchors/nav entries, and lychee catches dead external links. Runs on every PR
  # (and push to main, for parity) so problems are caught before they reach a release. --strict is
  # deliberately only used here (not baked into mkdocs.production.yml or used by the 'build' job
  # above) so that a stray warning can never block the artifact that 'deploy' publishes.
  validate:
    if: ${{ github.event_name == 'pull_request' || github.event_name == 'push' || github.event_name == 'workflow_dispatch' }}
    runs-on: ubuntu-latest
    steps:
      - name: Checkout Repository
        uses: actions/checkout@v7

      - name: Install Python
        uses: actions/setup-python@v6
        with:
          python-version: 3.x

      - name: Install mkdocs
        run: pip install mkdocs mkdocs-mermaid2-plugin

      - name: Validate site (strict build)
        run: mkdocs build --strict -f ./mkdocs.production.yml

      - name: Check for broken links
        uses: lycheeverse/lychee-action@v2
        with:
          args: >-
            --no-progress
            --scheme https --scheme http
            --user-agent "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/125.0.0.0 Safari/537.36"
            --exclude "^https://dev\.mysql\.com/"
            --exclude "^https://developers\.facebook\.com/"
            --exclude "^https://dotnet\.microsoft\.com/"
            'docs/**/*.md'
          token: ${{ secrets.GITHUB_TOKEN }}
          fail: true

  # Only deploys to GitHub Pages on a published release (or a manual dispatch against a release
  # tag), never on every push to main and never on a plain feature-branch dispatch.
  deploy:
    if: >-
      ${{ github.event_name == 'release' ||
          (github.event_name == 'workflow_dispatch' && startsWith(github.ref, 'refs/tags/')) }}
    needs: build
    permissions:
      pages: write
      id-token: write
    concurrency:
      group: "pages"
      cancel-in-progress: false
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    steps:
      - name: Setup Pages
        uses: actions/configure-pages@v6

      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v5