MyST Accessibility Checks

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

🚀 Usage

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

Basic Example

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

Advanced Example

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'

🔧 Inputs

Input	Description	Default
working_directory	Relative path to the MyST project root, ensure this begins with a / if not empty	.
execute	true or false, whether to execute notebooks at build time	false
base_url	The URL path prefix (e.g., /${{ github.event.repository.name }})	''
tags	Comma-separated list of axe-core tags to run	wcag2a,wcag2aa,wcag21a,wcag21aa
exclude	Comma-separated CSS selectors to exclude from testing	''
save_report	true or false, whether to save the axe-report.json as a workflow artifact	true

🛠️ Execution at Build Time

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.

📦 Dynamic Plugin Support

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.

📊 Viewing the Report

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.