diff --git a/.gitignore b/.gitignore index 203f78a88e..19f02bd55e 100644 --- a/.gitignore +++ b/.gitignore @@ -17,3 +17,5 @@ # Use pipenv to manage dependencies # so we don't want to track this file in git requirements.txt + +**/*.quarto_ipynb diff --git a/_quarto.yml b/_quarto.yml index ab3f52c664..09ff007e75 100644 --- a/_quarto.yml +++ b/_quarto.yml @@ -224,6 +224,7 @@ website: - docs/output-formats/html-multi-format.qmd - docs/output-formats/html-lightbox-figures.qmd - docs/output-formats/html-publishing.qmd + - docs/output-formats/html-accessibility.qmd - section: "PDF" contents: - docs/output-formats/pdf-basics.qmd diff --git a/docs/output-formats/autodark.css b/docs/output-formats/autodark.css new file mode 100644 index 0000000000..a5beecc335 --- /dev/null +++ b/docs/output-formats/autodark.css @@ -0,0 +1,3 @@ +img.autodark { + filter: invert(100%) hue-rotate(180deg); +} \ No newline at end of file diff --git a/docs/output-formats/html-accessibility.qmd b/docs/output-formats/html-accessibility.qmd new file mode 100644 index 0000000000..d14f028ed5 --- /dev/null +++ b/docs/output-formats/html-accessibility.qmd @@ -0,0 +1,117 @@ +--- +title: "HTML Accessibility Checks" +css: + - autodark.css +--- + +::: callout-note +This feature was introduced in Quarto 1.8. +::: + +Quarto includes integrated support for [`axe-core`](https://github.com/dequelabs/axe-core), a broadly-supported, open source, industry standard tool for accessibility checks in HTML documents. + +## Accessibility checks with `axe-core` + +To enable the simplest form of accessibility checks in Quarto 1.8, add the `axe` YAML metadata configuration to HTML `format`s (`html`, `dashboard`, and `revealjs`): + +``` yaml +format: + html: + axe: true +``` + +In this situation, if your webpage has accessibility violations that `axe-core` can catch, Quarto will produce console messages that are visible by opening your browser's development tools. + +### Customization + +Quarto supports two additional output formats for the accessibility checks, available through the `output` option. + +- `document`: embedded reports + + ``` yaml + format: + html: + axe: + output: document + ``` + + With this option, Quarto will generate a visible report of `axe-core` violations on the webpage itself. This is useful for visual inspection of a page. Note that with this setting, Quarto will always produce a report. + + If you wish to use this feature, we recommend adding it to a "debug" [project profile](/docs/projects/profiles.qmd) to reduce the chance you will accidentally publish a website to production with these reports. + +- `json`: JSON-formatted console output + + ``` yaml + format: + html: + axe: + output: json + ``` + + This option is useful if you're comfortable with browser automation tools such as [Puppeteer](https://pptr.dev/) and [Playwright](https://playwright.dev/), since it produces output to the console in a format that can be easily consumed. + + Specifically, the JSON object produced is the result of running `axe-core`'s `run` method on the webpage. We defer to `axe-core`'s [documentation for full information on that object](https://github.com/dequelabs/axe-core). + +- `console` + + ``` yaml + format: + html: + axe: + output: console + ``` + + This option is equivalent to `axe: true`. + +## Example: insufficient contrast + +As a minimal example of how this works in Quarto, consider this simple document: + +::: light-content + +``` qmd +--- +title: Testing Quarto's accessibility checker +format: + html: + axe: + output: document +--- + +This violates contrast rules: [insufficient contrast.]{style="color: #eee"}. +``` + +::: + +::: dark-content + +``` qmd +--- +title: Testing Quarto's accessibility checker +format: + html: + axe: + output: document +--- + +This violates contrast rules: [insufficient contrast.]{style="color: #111"}. +``` + +::: + + +This is the produced result visible on the page: + +::: {.light-content} +![The rendered webpage with an accessibility violation warning](images/axe-violation.png) +::: + +::: {.dark-content} +![The rendered webpage with an accessibility violation warning](images/axe-violation.png){.autodark} +::: + +## Planned work: automated checks before publishing + +Currently, this feature requires users to open the webpage in a [local preview](/docs/websites/index.html#website-preview), and it uses a CDN to load the `axe-core` library itself. + +In the future, we envision a mode where every page of a website can be checked at the time of `quarto render` or `quarto publish` in order to reduce the amount of required manual intervention. \ No newline at end of file diff --git a/docs/output-formats/images/axe-violation.png b/docs/output-formats/images/axe-violation.png new file mode 100644 index 0000000000..1b08959967 Binary files /dev/null and b/docs/output-formats/images/axe-violation.png differ