Run axe-core accessibility checks on your MyST site. This action will build your site before conducting the audit.

To use this action, add a workflow (e.g., .github/workflows/a11y.yml) to your repository.

If your MyST project is at the root of your repository:

name: Accessibility Audit
on: [push, pull_request]

jobs:
  check-a11y:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Run Accessibility Checks
        uses: berkeley-cdss/myst-a11y@v1

The following example is valid when your MyST project is in a subfolder (like /content) and hosted on GitHub Pages (using a BASE_URL, you need to execute notebooks at build time, you want to check WCAG 2.0 A and WCAG 2.0 AA, you don't want iframes with YouTube content flagged, and you don't need to save the JSON report generated by axe-core:

      - name: Run Accessibility Checks
        uses: berkeley-cdss/myst-a11y@v1
        with:
          working_directory: 'content'
          execute: 'true'
          base_url: '/${{ github.event.repository.name }}'
          tags: 'wcag2a,wcag2aa'
          exclude: "iframe[src*='youtube.com'], #movie_player"
          save_report: 'false'

run_build will take precedence over other flags including execute. If you do not run the build, then execution will not happen. If the build isn't run as part of this action, then working_directory will have no impact on the action. If the build is run as part of this action, then build_directory will have no impact on the action.

If you enable execution at build time, this action will set up Python, install jupyterlab, ipykernel, and any Python dependencies found at the root of your repository and/or in your working_directory in requirements.txt files. Please ensure that your requirements.txt are present and up to date. This ensures that code cells can be executed without issue.

This action automatically detects if you have a package.json in your working_directory.

If found, it runs npm install to ensure any custom MyST plugins are available during the build.

It injects local node_modules/.bin into the system PATH so your local dependencies take priority.

If save_report is set to true, a file named axe-report.json will be available in the Actions tab of your repository under the "Artifacts" section of the specific workflow run. You can use this file to debug specific WCAG violations.