Metadata-Version: 2.5
Name: ramplint
Version: 0.7.1
Summary: Accessibility (WCAG) linter for Django and Jinja2 templates
Project-URL: Homepage, https://github.com/iLLcruS/ramplint
Project-URL: Issues, https://github.com/iLLcruS/ramplint/issues
Project-URL: Changelog, https://github.com/iLLcruS/ramplint/blob/main/CHANGELOG.md
Project-URL: Funding, https://ko-fi.com/innerexcept
Author-email: Vladyslav Rostovskyi <rostovskii.1020@gmail.com>
License-Expression: PolyForm-Small-Business-1.0.0 OR PolyForm-Noncommercial-1.0.0
License-File: LICENSE
License-File: LICENSES/PolyForm-Noncommercial-1.0.0.md
License-File: LICENSES/PolyForm-Small-Business-1.0.0.md
Keywords: a11y,accessibility,aria,browser,django,django-forms,django-templates,jinja,jinja2,linter,playwright,pre-commit,screen-reader,templates,wcag
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Framework :: Django
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Text Processing :: Markup :: HTML
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: tomli>=1.1; python_version < '3.11'
Provides-Extra: browser
Requires-Dist: playwright>=1.45; extra == 'browser'
Provides-Extra: dev
Requires-Dist: django>=4.2; extra == 'dev'
Requires-Dist: greenlet>=3; extra == 'dev'
Requires-Dist: jinja2>=3; extra == 'dev'
Requires-Dist: jsonschema>=4; extra == 'dev'
Requires-Dist: pytest-cov>=4; extra == 'dev'
Requires-Dist: pytest>=7; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Description-Content-Type: text/markdown

<h1 align="center">ramplint</h1>

<p align="center">
  <strong>Accessibility linter for Django and Jinja2 templates.</strong><br>
  Catch WCAG problems in your <code>.html</code> templates and Django forms before they reach production.
</p>

<p align="center">
  <a href="https://github.com/iLLcruS/ramplint/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/iLLcruS/ramplint/actions/workflows/ci.yml/badge.svg"></a>
  <a href="https://pypi.org/project/ramplint/"><img alt="PyPI" src="https://img.shields.io/pypi/v/ramplint.svg"></a>
  <img alt="Python 3.10+" src="https://img.shields.io/badge/python-3.10%2B-blue.svg">
  <a href="https://github.com/iLLcruS/ramplint/blob/main/LICENSE"><img alt="License: free for individuals and small businesses" src="https://img.shields.io/badge/license-PolyForm%20Small%20Business%20%7C%20Noncommercial-blue.svg"></a>
  <a href="https://ko-fi.com/innerexcept"><img alt="Support on Ko-fi" src="https://img.shields.io/badge/Ko--fi-support-72a4f2?logo=ko-fi&logoColor=white"></a>
</p>

---

Generic HTML linters choke on `{% if %}`, `{{ variables }}` and `{% include %}`,
and browser-based checkers only see the pages you remember to open.
**ramplint** reads your templates directly, understands the template syntax,
and reports problems with the exact line and column in the template source:

<p align="center">
  <img src="https://raw.githubusercontent.com/iLLcruS/ramplint/main/docs/demo.svg" alt="Terminal output of ramplint reporting six accessibility problems in a Django product page template">
</p>

## Try it in 30 seconds

The repository ships with a small demo shop in [`examples/`](https://github.com/iLLcruS/ramplint/tree/main/examples): a
deliberately inaccessible set of Django templates that triggers every rule,
plus a file full of tricky-but-valid template patterns that must stay silent.

```bash
git clone https://github.com/iLLcruS/ramplint.git
cd ramplint
pip install .
ramplint examples/
```

```console
examples/templates/base.html:3:1: RL601 <html> is missing a lang attribute; add e.g. lang="en" or lang="{{ LANGUAGE_CODE }}" [html-lang]
examples/templates/base.html:6:3: RL602 Viewport meta tag: user-scalable=no disables zooming; maximum-scale=1 limits zoom below 200%. Users must be able to zoom; remove these settings [viewport-zoom]
examples/templates/base.html:13:5: RL502 <a> link has no accessible name; add text, an aria-label, or alt text on the image inside it [link-name]
examples/templates/base.html:13:45: RL101 <img> is missing an alt attribute (use alt="" for decorative images) [img-alt]
examples/templates/accounts/login.html:10:3: RL401 <input type="text"> has no associated label; add an id and a matching <label for>, or wrap it in a <label> (a placeholder is not a label) [form-label]
...
examples/templates/products/detail.html:28:3: RL101 <input type="image"> needs a non-empty alt attribute describing the action [img-alt]

Found 62 problems in 16 of 24 files.
```

See [`examples/README.md`](https://github.com/iLLcruS/ramplint/blob/main/examples/README.md) for what each demo template contains.

## Highlights

- **Knows your Django project.** Reads `TEMPLATES` and `INSTALLED_APPS` from your settings (without importing them) and lints exactly the folders Django loads templates from.
- **Checks Django forms.** Finds fields rendered with `{{ field }}` or `{% render_field %}` but no label, empty `label=""` in `forms.py`, and custom widgets that lose the id their `<label for>` points to.
- **Sees across templates.** Follows `{% extends %}` and `{% include %}`: a skipped heading after the `<h1>` in `base.html`, an empty page title or a label for a field in an included partial are all checked.
- **50 rules.** Images, tables, lists, landmarks, forms, controls, page language and WAI-ARIA in templates, plus contrast, focus, target size, reflow and site-wide consistency in the browser scan, each with a documentation page.
- **Template-aware.** Django and Jinja2 tags, variables and comments are understood, not stripped blindly.
- **Low noise.** If something is only known at render time (`{% include %}`, `{{ form.email }}`, `{{ widget.attrs }}`, `{% block %}`), ramplint assumes the best and stays quiet.
- **Zero dependencies.** Pure Python standard library (plus `tomli` on Python < 3.11).
- **Made for CI.** Exit codes, JSON output, GitHub Actions annotations and a pre-commit hook.
- **Fast.** No browser and no rendering. A whole project is checked in well under a second.
- **Also in the browser.** `ramplint --runserver` crawls your Django project in Chromium, opens menus and dialogs, and reports problems at the template lines that produced them (`pip install "ramplint[browser]"`).

## Installation

```bash
pip install ramplint
```

Free for personal use, learning, research, non-profits and companies with
fewer than 100 people and less than 1M USD revenue. Larger companies need a
[commercial license](https://github.com/iLLcruS/ramplint/blob/main/COMMERCIAL.md).

## Usage

```bash
ramplint                        # lint the template folders of the Django project here
ramplint templates/ shop/templates/base.html
ramplint --list-templates       # which project, settings and template folders were found
ramplint --select RL1,RL5       # only image and control rules
ramplint --ignore heading-order # rules can be referenced by code or name
ramplint --format json          # machine-readable output
ramplint --statistics          # problems per rule, most frequent first
ramplint -o report.json --format json  # save the report to a file
ramplint -o a11y-report.html --format html  # shareable HTML report
ramplint --list-rules
ramplint --explain RL303        # what a rule checks and how to fix it
```

By default ramplint looks at `.html`, `.htm`, `.jinja`, `.jinja2`, `.j2` and
`.djhtml` files and skips folders such as `node_modules`, `.venv`, `build` and `dist`.
Files passed explicitly are always checked, whatever their extension.

## Django projects

Run `ramplint` in the folder with `manage.py` and it lints the templates Django
actually uses, and nothing else (no `static/`, `node_modules/` or docs):

1. **Settings.** The module from `--settings` or `django-settings` in
   `pyproject.toml`, else `DJANGO_SETTINGS_MODULE`, else the
   `os.environ.setdefault(...)` in `manage.py`, `wsgi.py` or `asgi.py`, else a
   `settings.py` / `settings/` package next to `manage.py`.
2. **Template folders.** Every folder in `TEMPLATES[...]["DIRS"]`, then
   `<app>/templates/` (or `<app>/jinja2/` for the Jinja2 backend) for each app of
   yours in `INSTALLED_APPS` when `APP_DIRS` or the app directories loader is on.
   Django's own and third-party apps are skipped.
3. **No usable settings?** Every `templates/` and `jinja2/` folder next to an
   `apps.py` or `models.py`, plus the project-level `templates/`.

Settings are **read, never imported**: ramplint evaluates assignments, star
imports (`from .base import *`), `+=`, `.append()` and the usual path building
(`BASE_DIR / "templates"`, `os.path.join(...)`, `Path(__file__).resolve().parent`).
Values it cannot compute, such as `env("TEMPLATE_DIR")`, are skipped and listed
as warnings. Settings packages, cookiecutter-django, `src/` layouts, apps in a
subfolder and Jinja2 are supported; in a monorepo, every project below the
current folder is found.

Check what was found:

```console
$ cd examples/django_project && ramplint --list-templates
Project   .
Settings  config.settings.dev (from manage.py)
Template folders:
  templates           DIRS          4 templates
  catalog/templates   app catalog   2 templates
  accounts/templates  app accounts  2 templates
  catalog/jinja2      app catalog   1 template (jinja2)

9 templates and 1 forms module to lint.
```

`--list-templates --format json` gives the same as data, and `--verbose` prints
it to stderr before linting. Explicit paths always win: `ramplint some/file.html`
lints that file, and a folder without `manage.py` is walked as before. Turn
discovery off with `--no-django` or `django = false`, or list the folders
yourself with `template-dirs` (see [Configuration](#configuration)).

### Django forms accessibility

Most accessibility bugs in Django forms are invisible in the template: `{{ field }}`
looks fine, but it renders only the `<input>`, without its `<label>`. ramplint
checks the template **and** your `forms.py` (read with `ast`, never imported):

| Problem | Rule |
|---------|------|
| `{{ field }}`, `{{ form.email }}`, `{{ form.email\|add_class:"x" }}` or `{% render_field form.email %}` (django-widget-tweaks) with no `{{ field.label_tag }}` / `<label for="{{ field.id_for_label }}">` | `RL404` |
| `label=""`, `labels = {"bio": ""}` in `Meta`, `self.fields["x"].label = ""`: an empty `<label>` and a placeholder-only field | `RL405` |
| A custom widget whose template drops `widget.attrs`, or whose `id_for_label()` returns `None`: `<label for>` and `aria-describedby` point to nothing | `RL406` |

`forms.py` files and `forms/` packages are linted together with the templates
when ramplint finds your project; pass them explicitly (`ramplint shop/forms.py`)
otherwise. Works with plain Django forms, `ModelForm`, django-crispy-forms
(`|as_crispy_field` renders the label, so it is fine) and django-widget-tweaks.

### Across templates

With the template folders known, ramplint resolves `{% extends %}` and
`{% include %}` the way Django's loaders do (outside a project, it uses the
nearest folder called `templates` or `jinja2`):

| Rule | What it sees |
|------|--------------|
| `RL301` heading-order | A child template's headings follow the heading `base.html` renders before the block |
| `RL603` document-title | A page whose `<title>{% block title %}{% endblock %}</title>` stays empty |
| `RL306` landmark-one-main | A `<main>` inside a block that `base.html` already wraps in `<main>` |
| `RL403`, `RL703` | Ids from included partials and from the templates a page extends |

When a template cannot be resolved (a name from a variable, `{{ block.super }}`,
a missing file), these checks stay quiet.

### Output formats

| Format   | Use it for                                                       |
|----------|------------------------------------------------------------------|
| `text`   | Reading in the terminal (default; colored when it is a terminal) |
| `json`   | Scripts, dashboards and other tools                              |
| `github` | Annotations in GitHub pull requests (default inside Actions)     |
| `html`   | A single self-contained page to share with your team or a client |
| `sarif`  | GitHub Code Scanning and other security dashboards               |

`--output FILE` writes the report to a file and prints a one-line summary
instead. Missing folders are created, and colors are never written to files.

The HTML report needs no internet connection, so it can be attached to an email
or stored as a CI artifact. Every problem comes with the surrounding template
lines, rule names link to their documentation, and you can filter by rule or
template. It follows the light or dark theme of the viewer's system, and it
passes ramplint itself.

<p align="center">
  <img src="https://raw.githubusercontent.com/iLLcruS/ramplint/main/docs/html-report.png" alt="HTML report: a blue header with 32 problems in 6 templates, a table of problems by rule and a list of templates with problems" width="800">
</p>

<p align="center">
  <img src="https://raw.githubusercontent.com/iLLcruS/ramplint/main/docs/html-report-details.png" alt="HTML report details: filters by rule and template, and each problem with the highlighted line of template source" width="800">
</p>

`--statistics` replaces the list of problems with a count per rule, which helps
decide what to fix first:

```console
$ ramplint examples/ --statistics
7  RL401  form-label
6  RL502  link-name
5  RL101  img-alt
4  RL501  button-name
3  RL301  heading-order
2  RL201  table-header
2  RL306  landmark-one-main
2  RL603  document-title
1  RL102  iframe-title
1  RL103  video-caption
1  RL104  svg-img-alt
1  RL105  object-alt
1  RL106  media-autoplay
1  RL202  th-scope
1  RL203  empty-table-header
1  RL302  empty-heading
1  RL303  duplicate-id
1  RL304  list-structure
1  RL305  definition-list
1  RL402  autocomplete-valid
1  RL403  label-for-target
1  RL404  field-label
1  RL405  form-label-empty
1  RL406  widget-id
1  RL503  no-positive-tabindex
1  RL504  anchor-is-valid
1  RL505  nested-interactive
1  RL506  duplicate-accesskey
1  RL507  focusable-role
1  RL601  html-lang
1  RL602  viewport-zoom
1  RL604  valid-lang
1  RL605  meta-refresh
1  RL606  obsolete-elements
1  RL701  aria-role
1  RL702  aria-valid-attr
1  RL703  aria-valid-attr-value
1  RL704  aria-required-attr
1  RL705  aria-hidden-focus

Found 62 problems in 16 of 24 files.
```

It works with `--format text` (default) and `--format json`.

| Exit code | Meaning                      |
|-----------|------------------------------|
| `0`       | No problems found            |
| `1`       | Problems found               |
| `2`       | Usage or configuration error |

## Browser scan

Templates are not the whole page: JavaScript adds markup, CSS decides colours
and sizes, and menus and dialogs only exist once you open them. The browser
scan opens your site in Chromium, finds its pages, checks what is actually
rendered - and, for a Django project, still points every problem at the
template line that produced it.

```bash
pip install "ramplint[browser]"
playwright install chromium

ramplint --runserver                        # start this Django project, crawl it, stop it
ramplint http://localhost:8000/             # crawl a site that is already running
ramplint --runserver --format html -o a11y/ # report folder with screenshots
```

```text
catalog/templates/catalog/product_list.html:8:1: RL301 Heading level skips from <h1> to <h3>; use <h2> here or restructure the outline [heading-order] (on http://127.0.0.1:8000/ #content > h3, confirmed in the browser)
templates/base.html:7:3: RL603 <title> is empty; describe the page, e.g. <title>Orders | Shop</title> [document-title] (on http://127.0.0.1:8000/ html > head > title and 2 more pages)
http://localhost:8000/ #menu-img (after clicking "Menu" (#menu-toggle)): RL101 <img> is missing an alt attribute (use alt="" for decorative images) [img-alt]
```

### What it does

- **Finds the pages.** It reads `ROOT_URLCONF` with `ast` (never importing your
  code) and starts from every URL without parameters, then follows links, GET
  forms, `<link rel="next">`, `hx-get` and the sitemap from `robots.txt`.
  `ramplint --list-urls` shows what it found.
- **Spends the page budget on templates, not on more of the same.** URLs are
  grouped by URL pattern (`/products/<int:pk>/`); at most `--per-pattern` (2) of
  each are opened, patterns not seen yet come first, and the total is capped by
  `--max-pages` (50). Patterns with parameters that no link leads to are listed
  as **needs sample**: add example URLs in the config.
- **Stays safe.** Same origin only, GET only, and logout, delete and admin URLs
  are never opened (`deny` adds more, by URL or by URL name).
- **Opens menus, dialogs, tabs and `<details>`** (up to `--max-states`, 10 per
  page) on a fresh page each time and checks the markup that appeared. While it
  does, the page cannot navigate, open windows or send anything but GET.
- **Checks what only a browser knows** (rules RL801-RL807): contrast, target
  size, reflow at 320 px, visible focus, focus hidden by sticky banners, dialog
  focus and keyboard traps, `aria-expanded` that does not change.
- **Compares pages** (RL901-RL904): duplicate titles, navigation in a
  different order, the same control named differently, no way to skip
  repeated navigation.
- **Lists what the pages call:** XHR and fetch endpoints, HTML fragments
  (checked like partial templates) and `hx-post` targets (never sent).
- Hidden elements are skipped, accessible names Chromium computes are trusted,
  and `<!-- ramplint: ignore ... -->` comments work in rendered pages too.

### Problems point at templates

`ramplint --runserver` starts `manage.py runserver` with a generated settings
module that wraps your template loaders with `ramplint.django.SourceMapLoader`
(your files are not changed). Every element then knows its template, line and
column, so the text, GitHub and SARIF outputs show the template location and
the same problem on 500 product pages is one finding. A problem the template
linter also finds is reported once, marked *confirmed in the browser*.

To scan a server you start yourself, add the loader to your **development**
settings (it does nothing unless `DEBUG` is on):

```python
TEMPLATES[0]["APP_DIRS"] = False
TEMPLATES[0]["OPTIONS"]["loaders"] = [
    (
        "ramplint.django.SourceMapLoader",
        [
            "django.template.loaders.filesystem.Loader",
            "django.template.loaders.app_directories.Loader",
        ],
    )
]
```

Jinja2 templates and markup added by JavaScript fall back to the URL and a CSS
selector.

### Pages behind a login

```bash
ramplint http://localhost:8000/accounts/login/ --save-auth auth/staff.json
ramplint --runserver --auth auth/staff.json --auth auth/customer.json
```

`--save-auth` opens a browser window at the login page; log in by hand and close
it, and the session (cookies, never a password) is saved. Each `--auth` file is
a role: the site is scanned once per role and every problem says which roles saw
it. Pages that redirect to `LOGIN_URL` are listed as **needs login**, and a
saved session that expired is pointed out. Keep the files out of git; ramplint
warns when they are not ignored.

### The report

`--format html -o a11y/` writes a folder that opens from disk, offline:

```text
a11y/
  index.html      every problem, by template (or URL pattern), with a picture of each element
  pages/          one page per URL and viewport: screenshot with numbered markers and the problems
  site-map.html   URL patterns and what the crawl did with each (scanned, needs sample, needs login...)
  api.html        XHR / fetch endpoints the pages called
  screenshots/
  scan.json       everything, for tools and --baseline
```

`-o report.html --embed-screenshots` writes a single file instead. Text, JSON,
GitHub and SARIF outputs include the URL, selector, viewport, state, role and
template of every problem.

### Only new problems: baselines

```bash
ramplint --runserver --write-baseline a11y-baseline.json   # once, commit it
ramplint --runserver --baseline a11y-baseline.json         # in CI
```

With a baseline every problem is *new*, *existing* or *fixed*; the run fails
only on new ones, and the text output shows only those. Problems are matched by
rule, template (or URL pattern), selector and message, not by line number, so
unrelated edits do not turn old problems into new ones.

### Options

| Option | |
|---|---|
| `--runserver` | start the Django project in this folder, scan it, stop it |
| `--viewport desktop,mobile` | `desktop`, `tablet`, `mobile` or `WIDTHxHEIGHT` |
| `--max-pages N`, `--per-pattern N` | page budget (50) and pages per URL pattern (2) |
| `--include GLOB`, `--exclude-url GLOB` | which URLs (path like `/shop/*`, or a full URL) |
| `--no-crawl` | check only the given URLs |
| `--max-states N` | menus and dialogs opened per page (10; 0 turns it off) |
| `--concurrency N` | pages opened at the same time |
| `--save-auth FILE`, `--auth FILE` | pages behind a login |
| `--baseline FILE`, `--write-baseline FILE` | report only new problems |
| `--embed-screenshots` | one HTML file with the pictures inside |
| `--timeout S`, `--delay MS`, `--wait-for SELECTOR`, `--headed` | page loading |
| `--save-snapshots DIR`, `--screenshot-format png` | debugging |

The same settings go in `pyproject.toml`:

```toml
[tool.ramplint.browser]
base-url = "http://localhost:8000/"   # used when you pass browser options but no URL
viewports = ["desktop", "mobile"]
max-pages = 100
per-pattern = 2
max-states = 10
concurrency = 2
exclude = ["/admin/*"]
deny = ["*/reset/*", "shop:checkout"]
auth = ["auth/staff.json"]

[tool.ramplint.browser.samples]
"catalog:detail" = ["/products/1/", "/products/2/"]
```

Ctrl+C stops a scan, closes the browser and exits with 130.

## Rules

| Code    | Name            | What it checks                                                                           | WCAG             |
|---------|-----------------|------------------------------------------------------------------------------------------|------------------|
| [`RL101`](https://github.com/iLLcruS/ramplint/blob/main/docs/rules/RL101.md) | `img-alt`       | `<img>` has an `alt` attribute; `<input type="image">` and `<area>` have non-empty `alt` | 1.1.1 (A)        |
| [`RL102`](https://github.com/iLLcruS/ramplint/blob/main/docs/rules/RL102.md) | `iframe-title`  | `<iframe>` has a `title` describing its content                                          | 4.1.2 (A)        |
| [`RL103`](https://github.com/iLLcruS/ramplint/blob/main/docs/rules/RL103.md) | `video-caption` | `<video>` has a captions or subtitles `<track>` (muted videos are skipped) | 1.2.2 (A) |
| [`RL104`](https://github.com/iLLcruS/ramplint/blob/main/docs/rules/RL104.md) | `svg-img-alt` | `<svg role="img">` has a `<title>` or `aria-label` | 1.1.1 (A) |
| [`RL105`](https://github.com/iLLcruS/ramplint/blob/main/docs/rules/RL105.md) | `object-alt` | `<object>` has fallback text or a label; `<embed>` has a `title` or `aria-label` | 1.1.1 (A) |
| [`RL106`](https://github.com/iLLcruS/ramplint/blob/main/docs/rules/RL106.md) | `media-autoplay` | `<video autoplay>` / `<audio autoplay>` are `muted` | 1.4.2 (A) |
| [`RL201`](https://github.com/iLLcruS/ramplint/blob/main/docs/rules/RL201.md) | `table-header`  | Data tables use real `<th>` header cells                                                 | 1.3.1 (A)        |
| [`RL202`](https://github.com/iLLcruS/ramplint/blob/main/docs/rules/RL202.md) | `th-scope` | `scope` is `row`, `col`, `rowgroup` or `colgroup`, and only used on `<th>` | 1.3.1 (A) |
| [`RL203`](https://github.com/iLLcruS/ramplint/blob/main/docs/rules/RL203.md) | `empty-table-header` | `<th>` cells are not empty (the top-left corner cell is allowed) | 1.3.1 (A) |
| [`RL301`](https://github.com/iLLcruS/ramplint/blob/main/docs/rules/RL301.md) | `heading-order` | Heading levels do not skip (`<h2>` → `<h4>`)                                             | 1.3.1 (A)        |
| [`RL302`](https://github.com/iLLcruS/ramplint/blob/main/docs/rules/RL302.md) | `empty-heading` | Headings are not empty                                                                   | 2.4.6 (AA)       |
| [`RL303`](https://github.com/iLLcruS/ramplint/blob/main/docs/rules/RL303.md) | `duplicate-id`  | `id` values are unique (same id in `{% if %}` / `{% else %}` branches is allowed)        | 1.3.1 (A)        |
| [`RL304`](https://github.com/iLLcruS/ramplint/blob/main/docs/rules/RL304.md) | `list-structure` | `<ul>` / `<ol>` contain only `<li>`, and `<li>` is inside a list | 1.3.1 (A) |
| [`RL305`](https://github.com/iLLcruS/ramplint/blob/main/docs/rules/RL305.md) | `definition-list` | `<dl>` contains only `<dt>`, `<dd>` and `<div>` groups of them | 1.3.1 (A) |
| [`RL306`](https://github.com/iLLcruS/ramplint/blob/main/docs/rules/RL306.md) | `landmark-one-main` | One `<main>` per page: no duplicates, none missing in full-page templates | 1.3.1, 2.4.1 (A) |
| [`RL401`](https://github.com/iLLcruS/ramplint/blob/main/docs/rules/RL401.md) | `form-label`    | `<input>`, `<select>` and `<textarea>` have an associated `<label>`                      | 1.3.1, 4.1.2 (A) |
| [`RL402`](https://github.com/iLLcruS/ramplint/blob/main/docs/rules/RL402.md) | `autocomplete-valid` | `autocomplete` uses valid autofill tokens (catches typos like `emial`)              | 1.3.5 (AA)       |
| [`RL403`](https://github.com/iLLcruS/ramplint/blob/main/docs/rules/RL403.md) | `label-for-target` | `<label for>` points to an existing `id` (catches `for` matching the `name`) | 1.3.1, 4.1.2 (A) |
| [`RL404`](https://github.com/iLLcruS/ramplint/blob/main/docs/rules/RL404.md) | `field-label` | `{{ field }}`, `{{ form.email }}` and `{% render_field %}` have their `<label>` | 1.3.1, 4.1.2 (A) |
| [`RL405`](https://github.com/iLLcruS/ramplint/blob/main/docs/rules/RL405.md) | `form-label-empty` | No `label=""` on fields in `forms.py` (placeholder-only fields) | 1.3.1, 4.1.2 (A) |
| [`RL406`](https://github.com/iLLcruS/ramplint/blob/main/docs/rules/RL406.md) | `widget-id` | Custom widgets keep the `id` that `<label for>` and `aria-describedby` point to | 1.3.1, 4.1.2 (A) |
| [`RL501`](https://github.com/iLLcruS/ramplint/blob/main/docs/rules/RL501.md) | `button-name`   | Buttons (including icon-only buttons) have an accessible name                            | 4.1.2 (A)        |
| [`RL502`](https://github.com/iLLcruS/ramplint/blob/main/docs/rules/RL502.md) | `link-name`     | Links have an accessible name                                                            | 2.4.4, 4.1.2 (A) |
| [`RL503`](https://github.com/iLLcruS/ramplint/blob/main/docs/rules/RL503.md) | `no-positive-tabindex` | `tabindex` is not greater than `0`                                                | 2.4.3 (A)        |
| [`RL504`](https://github.com/iLLcruS/ramplint/blob/main/docs/rules/RL504.md) | `anchor-is-valid` | Links have a real target (no `href="#"`, `javascript:` or click-only `<a>`)        | 2.1.1 (A)        |
| [`RL505`](https://github.com/iLLcruS/ramplint/blob/main/docs/rules/RL505.md) | `nested-interactive` | No buttons, links or other controls inside `<a href>` or `<button>` | 4.1.2 (A) |
| [`RL506`](https://github.com/iLLcruS/ramplint/blob/main/docs/rules/RL506.md) | `duplicate-accesskey` | `accesskey` values are unique | Best practice |
| [`RL507`](https://github.com/iLLcruS/ramplint/blob/main/docs/rules/RL507.md) | `focusable-role` | Elements with an interactive role can get keyboard focus (`<div role="switch">` needs `tabindex`) | 2.1.1, 4.1.2 (A) |
| [`RL601`](https://github.com/iLLcruS/ramplint/blob/main/docs/rules/RL601.md) | `html-lang`     | `<html>` declares the page language                                                      | 3.1.1 (A)        |
| [`RL602`](https://github.com/iLLcruS/ramplint/blob/main/docs/rules/RL602.md) | `viewport-zoom` | `<meta name="viewport">` does not disable zoom (`user-scalable=no`, `maximum-scale` < 2) | 1.4.4 (AA)       |
| [`RL603`](https://github.com/iLLcruS/ramplint/blob/main/docs/rules/RL603.md) | `document-title` | Full-page templates have a non-empty `<title>` | 2.4.2 (A) |
| [`RL604`](https://github.com/iLLcruS/ramplint/blob/main/docs/rules/RL604.md) | `valid-lang` | `lang` / `xml:lang` are valid language tags (catches `english`, `ua`, `en_US`) | 3.1.1 (A), 3.1.2 (AA) |
| [`RL605`](https://github.com/iLLcruS/ramplint/blob/main/docs/rules/RL605.md) | `meta-refresh` | No timed reloads or redirects with `<meta http-equiv="refresh">` | 2.2.1 (A) |
| [`RL606`](https://github.com/iLLcruS/ramplint/blob/main/docs/rules/RL606.md) | `obsolete-elements` | No `<marquee>` or `<blink>` | 2.2.2 (A) |
| [`RL701`](https://github.com/iLLcruS/ramplint/blob/main/docs/rules/RL701.md) | `aria-role` | `role` is a real, non-abstract WAI-ARIA role (catches typos like `dailog`) | 4.1.2 (A) |
| [`RL702`](https://github.com/iLLcruS/ramplint/blob/main/docs/rules/RL702.md) | `aria-valid-attr` | `aria-*` attributes exist (catches `aria-lable`, `aria-labeledby`) | 4.1.2 (A) |
| [`RL703`](https://github.com/iLLcruS/ramplint/blob/main/docs/rules/RL703.md) | `aria-valid-attr-value` | ARIA values match their type (`aria-hidden="yes"`, missing `aria-labelledby` ids) | 4.1.2 (A) |
| [`RL704`](https://github.com/iLLcruS/ramplint/blob/main/docs/rules/RL704.md) | `aria-required-attr` | Roles have their required states (`role="switch"` needs `aria-checked`) | 4.1.2 (A) |
| [`RL705`](https://github.com/iLLcruS/ramplint/blob/main/docs/rules/RL705.md) | `aria-hidden-focus` | Nothing focusable inside `aria-hidden="true"` | 4.1.2 (A) |
| [`RL801`](https://github.com/iLLcruS/ramplint/blob/main/docs/rules/RL801.md) | `color-contrast` | Text contrast is at least 4.5:1 (3:1 for large text) (browser scan) | 1.4.3 (AA) |
| [`RL802`](https://github.com/iLLcruS/ramplint/blob/main/docs/rules/RL802.md) | `target-size` | Clickable targets are 24x24 px or have room around them (browser scan) | 2.5.8 (AA) |
| [`RL803`](https://github.com/iLLcruS/ramplint/blob/main/docs/rules/RL803.md) | `reflow` | Pages do not scroll sideways at 320 px (browser scan) | 1.4.10 (AA) |
| [`RL804`](https://github.com/iLLcruS/ramplint/blob/main/docs/rules/RL804.md) | `focus-visible` | Keyboard focus is visible (browser scan) | 2.4.7 (AA) |
| [`RL805`](https://github.com/iLLcruS/ramplint/blob/main/docs/rules/RL805.md) | `focus-obscured` | Focused elements are not hidden behind sticky or fixed content (browser scan) | 2.4.11 (AA) |
| [`RL806`](https://github.com/iLLcruS/ramplint/blob/main/docs/rules/RL806.md) | `dialog-focus` | Modal dialogs take and keep focus; no keyboard traps (browser scan) | 2.4.3 (A) |
| [`RL807`](https://github.com/iLLcruS/ramplint/blob/main/docs/rules/RL807.md) | `expanded-state` | `aria-expanded` becomes `"true"` when content opens (browser scan) | 4.1.2 (A) |
| [`RL901`](https://github.com/iLLcruS/ramplint/blob/main/docs/rules/RL901.md) | `page-title-unique` | Different pages have different titles (browser scan) | 2.4.2 (A) |
| [`RL902`](https://github.com/iLLcruS/ramplint/blob/main/docs/rules/RL902.md) | `consistent-navigation` | Repeated navigation keeps its order (browser scan) | 3.2.3 (AA) |
| [`RL903`](https://github.com/iLLcruS/ramplint/blob/main/docs/rules/RL903.md) | `consistent-identification` | The same control has the same name on every page (browser scan) | 3.2.4 (AA) |
| [`RL904`](https://github.com/iLLcruS/ramplint/blob/main/docs/rules/RL904.md) | `bypass-blocks` | Repeated navigation can be skipped (browser scan) | 2.4.1 (A) |

Every rule has its own page with examples and the reasoning behind it: see
[docs/rules](https://github.com/iLLcruS/ramplint/blob/main/docs/rules/README.md),
or run `ramplint --explain RL101` in the terminal.

<details>
<summary><strong>Examples for every rule</strong></summary>

#### RL101 `img-alt`

```django
{# ✗ #} <img src="{% static 'logo.png' %}">
{# ✓ #} <img src="{% static 'logo.png' %}" alt="ACME">
{# ✓ #} <img src="{% static 'divider.png' %}" alt="">   {# decorative #}
{# ✓ #} <img src="{{ product.image.url }}" alt="{{ product.name }}">
```

#### RL102 `iframe-title`

```django
{# ✗ #} <iframe src="https://www.youtube.com/embed/{{ video.id }}"></iframe>
{# ✓ #} <iframe src="https://www.youtube.com/embed/{{ video.id }}" title="{{ video.title }}"></iframe>
```

Frames hidden with `aria-hidden="true"` are skipped.

#### RL103 `video-caption`

```django
{# ✗ #} <video controls src="{{ product.video.url }}"></video>
{# ✓ #} <video controls src="{{ product.video.url }}"><track kind="captions" src="{{ product.captions.url }}" srclang="en"></video>
{# ✓ #} <video autoplay muted loop src="{% static 'video/bg.mp4' %}"></video>
```

#### RL104 `svg-img-alt`

```django
{# ✗ #} <svg role="img" viewBox="0 0 24 24"><path d="…"/></svg>
{# ✓ #} <svg role="img" viewBox="0 0 24 24"><title>{% trans "Cart" %}</title><path d="…"/></svg>
{# ✓ #} <svg aria-hidden="true"><use href="#icon-star"></use></svg>
```

#### RL105 `object-alt`

```django
{# ✗ #} <object data="{% static 'prices.pdf' %}" type="application/pdf"></object>
{# ✓ #} <object data="{% static 'prices.pdf' %}" type="application/pdf"><a href="{% static 'prices.pdf' %}">Download the price list (PDF)</a></object>
```

#### RL106 `media-autoplay`

```django
{# ✗ #} <audio autoplay src="{% static 'jingle.mp3' %}"></audio>
{# ✓ #} <audio controls src="{% static 'jingle.mp3' %}"></audio>
```

#### RL201 `table-header`

```django
{# ✗ #} <table><tr><td>Name</td><td>Price</td></tr>…</table>
{# ✓ #} <table><tr><th scope="col">Name</th><th scope="col">Price</th></tr>…</table>
{# ✓ #} <table role="presentation">…</table>              {# layout table #}
```

`role="columnheader"` on a `<td>` is not accepted. Use a real `<th>`.
Tables whose rows come from `{% include %}`, `{% block %}` or `{{ form.as_table }}`
are skipped because their content is not visible in the template.

#### RL202 `th-scope`

```django
{# ✗ #} <table><tr><th scope="column">Name</th></tr></table>
{# ✗ #} <table><tr><td scope="row">{{ p.name }}</td></tr></table>
{# ✓ #} <table><tr><th scope="col">Name</th></tr></table>
```

A typo in `scope` is silently ignored. ramplint suggests the closest valid value.

#### RL203 `empty-table-header`

```django
{# ✗ #} <table><tr><th>Order</th><th></th></tr>…</table>
{# ✓ #} <table><tr><th>Order</th><th><span class="visually-hidden">Actions</span></th></tr>…</table>
```

The empty top-left corner cell of a table with both column and row headers is allowed.

#### RL301 `heading-order`

```django
{# ✗ #} <h2>Orders</h2> <h4>Recent</h4>
{# ✓ #} <h2>Orders</h2> <h3>Recent</h3>
```

The first heading in a file sets the baseline. A child template that starts at
`<h2>` (because `base.html` owns the `<h1>`) is fine.

#### RL302 `empty-heading`

```django
{# ✗ #} <h2><i class="icon-star"></i></h2>
{# ✓ #} <h2>{% trans "Favourites" %}</h2>
```

#### RL303 `duplicate-id`

```django
{# ✗ #} <p id="help">…</p> … <p id="help">…</p>
{# ✓ #} {% if user.is_authenticated %}<p id="greeting">…</p>{% else %}<p id="greeting">…</p>{% endif %}
```

ramplint knows which `{% if %}` / `{% elif %}` / `{% else %}` (and `{% for %}` /
`{% empty %}`) branch an element is in, so the same id in mutually exclusive
branches is not reported. Ids built from variables are skipped.

#### RL304 `list-structure`

```django
{# ✗ #} <ul>{% for c in categories %}<a href="{{ c.url }}">{{ c.name }}</a>{% endfor %}</ul>
{# ✓ #} <ul>{% for c in categories %}<li><a href="{{ c.url }}">{{ c.name }}</a></li>{% endfor %}</ul>
{# ✓ #} <ul>{% include "partials/menu_items.html" %}</ul>
```

A partial whose top level is `<li>` items (included into a list elsewhere) is fine.

#### RL305 `definition-list`

```django
{# ✗ #} <dl><span class="row"><dt>Weight</dt><dd>{{ p.weight }}</dd></span></dl>
{# ✗ #} <dl><dt>Weight</dt><div><dd>{{ p.weight }}</dd></div></dl>
{# ✓ #} <dl><div class="row"><dt>Weight</dt><dd>{{ p.weight }}</dd></div></dl>
```

Every `<dt>` needs a `<dd>` after it, and every `<dd>` a `<dt>` before it.

#### RL306 `landmark-one-main`

```django
{# ✗ #} <main>{% block content %}{% endblock %}</main><main>{% block sidebar %}{% endblock %}</main>
{# ✓ #} <main>{% block content %}{% endblock %}</main><aside>{% block sidebar %}{% endblock %}</aside>
```

Full-page templates without a `<main>` are reported too, unless a `{% block %}`
or `{% include %}` could render it. Standalone pages such as `500.html` are the
usual case. Child templates and partials are not checked for a missing `<main>`.

#### RL401 `form-label`

```django
{# ✗ #} <input type="email" name="email" placeholder="Email">
{# ✓ #} <label for="email">Email</label> <input type="email" id="email" name="email">
{# ✓ #} <label>Email <input type="email" name="email"></label>
{# ✓ #} <input type="search" name="q" aria-label="Search">
```

Hidden, submit, reset, button and image inputs are not checked. Neither are
widgets whose attributes are rendered dynamically (`<input {{ widget.attrs }}>`).

#### RL402 `autocomplete-valid`

```django
{# ✗ #} <input type="email" name="email" autocomplete="emial" aria-label="Email">
{# ✗ #} <input name="phone" autocomplete="mobile street-address" aria-label="Phone">
{# ✓ #} <input name="email" autocomplete="email" aria-label="Email">
{# ✓ #} <input name="ship" autocomplete="section-gift shipping street-address" aria-label="Address">
```

A typo in `autocomplete` silently breaks autofill and password managers.
ramplint validates the full token grammar from the HTML spec and suggests the
token you most likely meant, including for common names such as `zip`
(`postal-code`) or `phone` (`tel`).

#### RL403 `label-for-target`

```django
{# ✗ #} <label for="email">Email</label> <input type="email" name="email">
{# ✓ #} <label for="email">Email</label> <input type="email" id="email" name="email">
{# ✓ #} <label for="{{ form.email.id_for_label }}">{{ form.email.label }}</label> {{ form.email }}
```

Templates that render fields ramplint cannot see (`{{ form.email }}`,
`{% include %}`, a `{% block %}` of a base template) are skipped.

#### RL404 `field-label`

```django
{# ✗ #} {% for field in form %}<div class="field">{{ field }}</div>{% endfor %}
{# ✗ #} {% render_field form.email class="input" placeholder="Email" %}
{# ✓ #} {% for field in form %}<div class="field">{{ field.label_tag }} {{ field }}</div>{% endfor %}
{# ✓ #} {% for field in form %}{{ field.as_field_group }}{% endfor %}
```

`{{ field }}` renders only the widget. Hidden fields and filters that render the
label (`|as_crispy_field`) are skipped.

#### RL405 `form-label-empty` and RL406 `widget-id` (in `forms.py`)

```python
class NewsletterForm(forms.Form):
    # RL405: renders <label></label>; a placeholder is not a label
    email = forms.EmailField(label="", widget=forms.EmailInput(attrs={"placeholder": "Email"}))


class StarRatingWidget(forms.Widget):
    # RL406: the template never renders widget.attrs, so the input has no id
    template_name = "widgets/star_rating.html"
```

#### RL501 `button-name`

```django
{# ✗ #} <button><i class="fa fa-trash"></i></button>
{# ✓ #} <button aria-label="{% trans 'Delete' %}"><i class="fa fa-trash" aria-hidden="true"></i></button>
{# ✓ #} <button><span class="visually-hidden">Delete</span><i class="fa fa-trash"></i></button>
```

#### RL502 `link-name`

```django
{# ✗ #} <a href="{% url 'cart' %}"><svg>…</svg></a>
{# ✓ #} <a href="{% url 'cart' %}"><svg><title>Cart</title>…</svg></a>
{# ✓ #} <a href="/"><img src="logo.png" alt="ACME home"></a>
```

#### RL503 `no-positive-tabindex`

```django
{# ✗ #} <a href="{% url 'search' %}" tabindex="1">Search</a>
{# ✓ #} <div role="button" tabindex="0">Menu</div>
{# ✓ #} <div id="dialog" tabindex="-1">…</div>
```

A positive `tabindex` moves the element to the front of the keyboard focus
order, ahead of everything else on the page. Reorder the markup instead.

#### RL504 `anchor-is-valid`

```django
{# ✗ #} <a href="#" onclick="addToWishlist()">Add to wishlist</a>
{# ✗ #} <a href="javascript:void(0)">Open chat</a>
{# ✗ #} <a onclick="openMenu()">Menu</a>
{# ✓ #} <button type="button" onclick="addToWishlist()">Add to wishlist</button>
{# ✓ #} <a href="#reviews">Jump to reviews</a>
```

Links navigate, buttons act. A fake link is missing from the keyboard focus
order (no `href`) or does not react to the Space key like a button would.

#### RL505 `nested-interactive`

```django
{# ✗ #} <a href="{{ p.url }}" class="card">{{ p.name }} <button type="button">Add to cart</button></a>
{# ✓ #} <div class="card"><a href="{{ p.url }}">{{ p.name }}</a> <button type="button">Add to cart</button></div>
```

Browsers and screen readers handle a control inside a link (or a link inside a
button) differently, and the inner one is often unreachable by keyboard.

#### RL506 `duplicate-accesskey`

```django
{# ✗ #} <a href="/search/" accesskey="s">Search</a> <button accesskey="s">Save</button>
{# ✓ #} <a href="/search/" accesskey="f">Search</a> <button accesskey="s">Save</button>
```

#### RL507 `focusable-role`

```django
{# ✗ #} <span role="button" onclick="toggle()">Menu</span>
{# ✓ #} <button type="button" onclick="toggle()">Menu</button>
{# ✓ #} <span role="tab" tabindex="-1" aria-selected="false">Reviews</span>
```

Any `tabindex` (including `-1` for roving focus) is accepted; options, tree
items and grid cells are skipped because their container usually manages focus.

#### RL601 `html-lang`

```django
{# ✗ #} <html>
{# ✓ #} <html lang="{{ LANGUAGE_CODE }}">{% block body %}{% endblock %}</html>
```

#### RL602 `viewport-zoom`

```django
{# ✗ #} <meta name="viewport" content="width=device-width, initial-scale=1, user-scalable=no">
{# ✗ #} <meta name="viewport" content="width=device-width, maximum-scale=1">
{# ✓ #} <meta name="viewport" content="width=device-width, initial-scale=1">
```

Low-vision users rely on pinch-to-zoom; WCAG requires text to be resizable up to 200%.

#### RL603 `document-title`

```django
{# ✗ #} <html lang="en"><head><meta charset="utf-8"></head><body><main>…</main></body></html>
{# ✓ #} <html lang="en"><head><title>{% block title %}Shoply{% endblock %}</title></head><body><main>…</main></body></html>
```

Only full-page templates (with `<html>`) are checked. A `{% block %}` or
`{% include %}` in `<head>` that may render the title is accepted.

#### RL604 `valid-lang`

```django
{# ✗ #} <p lang="ua">Привіт</p>
{# ✗ #} <p lang="en_US">Color</p>
{# ✓ #} <p lang="uk">Привіт</p>
{# ✓ #} <p lang="en-US">Color</p>
```

Country codes and language names get a suggestion: `ua` → `uk`, `cz` → `cs`,
`english` → `en`.

#### RL605 `meta-refresh`

```django
{# ✗ #} <meta http-equiv="refresh" content="5; url={% url 'home' %}">
{# ✓ #} <meta http-equiv="refresh" content="0; url={% url 'home' %}">
```

#### RL606 `obsolete-elements`

```django
{# ✗ #} <marquee>{% trans "Free shipping!" %}</marquee>
{# ✓ #} <p class="banner">{% trans "Free shipping!" %}</p>
```

#### RL701–RL705: ARIA

```django
{# ✗ #} <div role="dailog" aria-modal="true">…</div>
{# ✗ #} <button aria-lable="Close">×</button>
{# ✗ #} <div class="backdrop" aria-hidden="yes"></div>
{# ✗ #} <div role="switch" tabindex="0">Dark mode</div>
{# ✗ #} <div aria-hidden="true"><a href="/">Home</a></div>
{# ✓ #} <div role="switch" tabindex="0" aria-checked="false">Dark mode</div>
{# ✓ #} <div aria-hidden="true"><a href="/" tabindex="-1">Home</a></div>
```

</details>

## How templates are handled

Before parsing, every template token is replaced by a placeholder of the same
length, so positions in the report always match your source:

| Template code                                                | Treated as                      |
|--------------------------------------------------------------|---------------------------------|
| `{{ variable }}`, `{% trans %}`, `{% url %}`, `{% static %}` | Text that exists at runtime     |
| `{% include %}`, `{% block %}`, custom tags                  | Unknown markup (rules back off) |
| `{{ form }}`, `{{ form.email }}`, `{{ field }}`, `{{ form.as_p }}`, `\|safe`, `\|as_crispy_field` | Unknown markup (rules back off) |
| `{% if %}`, `{% for %}`, `{% with %}`, ...                   | Nothing (control flow)          |
| `{# ... #}`, `{% comment %}...{% endcomment %}`              | Nothing                         |

Both branches of an `{% if %}` are checked, so a problem in either one is reported.
In a child template (one with `{% extends %}`), `{% block %}` renders the content
written right there, and content outside blocks is ignored, as Django does.

## Suppressing problems

```django
<img src="spacer.gif"> {# ramplint: ignore RL101 #}

{# ramplint: ignore img-alt, link-name #}
<a href="/"><img src="logo.png"></a>

{# ramplint: ignore-file #}
```

`ignore` applies to its own line and the next one. With no codes it silences
every rule. HTML comments work too: `<!-- ramplint: ignore RL201 -->`.

## Configuration

Add a `[tool.ramplint]` section to `pyproject.toml`. Command-line options take
precedence over it.

```toml
[tool.ramplint]
select = ["RL"]                          # default: all rules
ignore = ["RL301"]
exclude = ["*/admin/*", "templates/vendor/*"]
extensions = [".html", ".txt"]

# Django projects (all optional)
django-settings = "config.settings.base"   # instead of manage.py / DJANGO_SETTINGS_MODULE
template-dirs = ["templates", "shop/templates"]  # use these folders, skip discovery
django = false                           # walk every folder instead
```

`template-dirs` are relative to the folder of `pyproject.toml`. On the command
line, `--settings MODULE` and `--no-django` do the same.

## pre-commit

```yaml
# .pre-commit-config.yaml
repos:
  - repo: https://github.com/iLLcruS/ramplint
    rev: 0.7.1
    hooks:
      - id: ramplint
```

## GitHub Actions

When `GITHUB_ACTIONS=true`, ramplint switches to the `github` format and
problems appear as annotations right in the pull request diff.

```yaml
- run: pip install ramplint
- run: ramplint templates/
```

### Browser scan in CI

```yaml
jobs:
  accessibility:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.13"
      - run: pip install -r requirements.txt "ramplint[browser]"
      - run: python -m playwright install --with-deps chromium
      # Annotations land on template lines; only problems not in the baseline fail.
      - run: ramplint --runserver --baseline a11y-baseline.json
      - run: ramplint --runserver --format html -o a11y/
        if: always()
      - uses: actions/upload-artifact@v4
        if: always()
        with:
          name: accessibility-report
          path: a11y/
```

### GitHub Code Scanning

With `--format sarif`, problems also show up in the repository's
**Security → Code scanning** tab, where they are tracked over time and can be
dismissed with a reason. Code scanning is free for public repositories; private
repositories need GitHub Advanced Security.

```yaml
name: Accessibility

on: [push, pull_request]

jobs:
  ramplint:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      security-events: write
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"
      - run: pip install ramplint
      # --exit-zero: let Code Scanning decide whether the check fails
      - run: ramplint templates/ --format sarif -o ramplint.sarif --exit-zero
      - uses: github/codeql-action/upload-sarif@v4
        with:
          sarif_file: ramplint.sarif
          category: ramplint
```

## Python API

```python
from ramplint import lint_source, select_rules

for problem in lint_source('<img src="a.png">', rules=select_rules(["RL1"])):
    print(problem.line, problem.col, problem.code, problem.message)
```

## Limitations

The template linter catches structural problems early and cheaply; the browser
scan adds what only a rendered page shows (contrast, focus, target size,
reflow). Neither can tell whether an `alt` text is actually meaningful or a
page makes sense with a screen reader, so use ramplint together with manual
testing.

## Roadmap

- [x] 36 rules for images, tables, structure, forms, controls, the document and WAI-ARIA
- [x] HTML report and SARIF output for GitHub Code Scanning
- [x] Find Django template folders from the settings; follow `{% extends %}` / `{% include %}`
- [x] Browser scan: crawl a Django project, menus and dialogs, rendered-page and site-wide rules, template source maps, report with screenshots, baselines
- [ ] `--fix` for safe autofixes (e.g. `scope="col"` on header rows)
- [ ] Check partials against the templates that include them (a `<label>` in the page, the field in the partial)
- [ ] Jinja2 macros
- [ ] VS Code extension

## Contributing

Bug reports, especially about false positives, are very welcome.
See [CONTRIBUTING.md](https://github.com/iLLcruS/ramplint/blob/main/CONTRIBUTING.md).

## Feedback and support

Questions, ideas, or using ramplint in your project? Open an
[issue](https://github.com/iLLcruS/ramplint/issues) or email me at
[rostovskii.1020@gmail.com](mailto:rostovskii.1020@gmail.com).

ramplint is built in my spare time. If it saved you time, you can buy me a
coffee:

<a href="https://ko-fi.com/innerexcept"><img src="https://ko-fi.com/img/githubbutton_sm.svg" alt="Support me on Ko-fi" height="36"></a>

## License

ramplint is source-available under your choice of the
[PolyForm Small Business License 1.0.0](https://github.com/iLLcruS/ramplint/blob/main/LICENSES/PolyForm-Small-Business-1.0.0.md)
or the
[PolyForm Noncommercial License 1.0.0](https://github.com/iLLcruS/ramplint/blob/main/LICENSES/PolyForm-Noncommercial-1.0.0.md):

| Who | License |
|-----|---------|
| Individuals: personal projects, learning, research | Free |
| Schools, charities, public institutions | Free |
| Companies with fewer than 100 people and less than 1M USD revenue | Free |
| Larger companies (on developers' machines, in CI, in pre-commit) | [Commercial license](https://github.com/iLLcruS/ramplint/blob/main/COMMERCIAL.md) |

To get a commercial license, write to
[rostovskii.1020@gmail.com](mailto:rostovskii.1020@gmail.com).

Versions 0.5.0 and earlier were released under the MIT License and stay
available under it.

© Vladyslav Rostovskyi
