iansan5653/github-markdown-a11y-extension

:accessibility: Check your Markdown for accessibility issues as you write it on GitHub

Markdown Accessibility Checker

Markdown Accessibility Checker is a browser extension for validating Markdown in GitHub text editors. It encourages writing accessible valid Markdown when creating issues, pull requests, discussions, and comments.

Installation

Install from your browser's addons store:

• Chrome or Edge
• Firefox

Alternatively, you can install a specific version by downloading the corresponding zip file from the Releases page.

Linting rules used

Under the hood, the extension is a wrapper around Markdownlint, providing a web-compatible UI for viewing linting errors. The base set of rules comes from markdownlint-github. In addition, a few more rules are enabled:

• no-reversed-links: Enforces valid link syntax (errors if you accidentally flip the square brackets and parentheses)
• no-empty-links: Ensures all links have some visible link text

For now, the set of linting rules is not configurable. In order to minimize friction and distractions, only a small subset of lint rules are enabled. The extension does not try to encourage any sort of style or formatting - it's only here to help you with accessibility and syntax.

Note: Requests for new rules and changes to existing rules should be made in either the Markdownlint or Markdownlint-github repositories, not here.

Development

To run the extension locally and automatically reload when making changes, follow these steps.

Note: The version number is always 0.0.0 when working locally.

Preparation

1. Developing this extension requires Node and npm to be installed on your machine
2. Remove any existing installations of the extension
3. Run npm install to install dependencies
4. Run npm run build:watch to compile the TypeScript code into JavaScript:

   > npm run build:watch
   ...
   Accessibility_Checker_for_GitHub_Markdown (webpack 5.80.0) compiled with 1 warning in 41 ms
   

   Leave this running in the background as you make changes.

Testing in Chrome

The easiest way to test this extension locally in Chrome is to install it unpacked. When you make changes to the TypeScript code, you must press the "refresh" button on the extension card in chrome://extensions to see your changes.

Testing in Firefox

Firefox has a CLI that will automatically reload the extension on changes, making it slightly easier to develop using Firefox:

Run npm run start:firefox to use web-ext run to run the extension in Firefox. By default this will create a new temporary test profile. If you want to use your profile, you can provide a profile to the CLI by passing the --firefox-profile argument like so: npm run start:firefox -- --firefox-profile=my-profile.

> npm run start:firefox
...
Installed /.../markdownlint-browser as a temporary add-on
The extension will reload if any source file changes
Press R to reload (and Ctrl-C to quit)

Checking for Problems

To run the automated checks to look for potential issues in the code, run the combined check script. There are a few warnings that are known and unavoidable due to dependencies, but this script should not exit with an error code.

> npm run check
...
Checking formatting...
All matched files use Prettier code style!
...
WARNING in ./node_modules/markdownlint/lib/markdownlint.js 16:74-81
  Critical dependency: require function is used in a way in which dependencies cannot be statically extracted
   @ ./src/utilities/lint-markdown.ts 1:0-40 3:40-57
   @ ./src/components/linted-markdown-editor.ts 7:0-58 120:19-31
   @ ./src/content-script.ts 5:0-75 16:27-47

  Accessibility_Checker_for_GitHub_Markdown (webpack 5.80.0) compiled with 1 warning in 517 ms
...
WARNINGS:

DANGEROUS_EVAL ...
UNSAFE_VAR_ASSIGNMENT ...
DANGEROUS_EVAL ...

Build Instructions

Follow these instructions to build this extension from source, creating an installable and shareable zip file:

1. Building this extension requires Node and npm to be installed on your machine
2. Run npm install to install dependencies
3. Run npm run package to package the built code into ./web-ext-artifacts/accessibility_checker_for_github_markdown-0.0.0.zip

Release process

Releases are automatically handled by an Actions job after a new GitHub Release is published.

Warning: Release tag names must follow the 0.0.0 version number format (with no leading v).

github-markdown-a11y-extension's Issues

Uploading an image does not automatically trigger a re-lint

When an image is uploaded (ie, via the file upload button in the editor toolbar), linting is not refreshed. This means that the ALT text error does not appear until the user starts typing.

This is a challenge to solve because the editor is setting the value property of the HTMLTextareaElement instance, so no events are emitted. There's nothing to listen for in this case.

Remove rules that lint the Markdown code itself; focus on the rendered output

After using the extension for a while, I think I should remove the unordered list style rule that enforces the use of asterisks instead of hyphens. This does make the Markdown code itself more readable with a screen reader, but it doesn't affect the rendered output and it's a lot of noise for little gain. I think I want this extension to focus on the high-impact rules so that we can maximize the 'signal-to-noise' ratio. In other words, I want to minimize lint errors to focus on the important ones.

Add automated test suite

This is a challenging one... how can we do end-to-end testing on an extension that depends on an external website? Maybe a mock website?

Tooltip position is incorrect

The tooltip is appearing too far to the left, outside the bounds of the editor:

Looks like maybe we aren't adjusting for the editor x-position?

Incorrect highlight position when content ends in a newline

Ban level 1 headings

All GitHub pages already have level 1 headings, so these should be avoided in user-generated content.

We should possibly consider the same for level 2 since most pages already have level 2 headings, restricting headings to level 3 and higher.

GitHub React Markdown editor becomes unresponsive when the extension is installed

A few users have reported the MD editor being unresponsive on the Issues React page. The problem is fixed by disabling the extension

• https://github.com/github/issues/issues/10125
• https://github.com/github/issues/issues/10290
• https://github.com/github/issues/issues/10241

Until the issue is fixed, we'll recommend to our customers to disable the extension.

CC First Responsers to mention this bug by as tracking issue