Metadata-Version: 2.5
Name: ramplint
Version: 0.6.0
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,django,django-forms,django-templates,jinja,jinja2,linter,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: 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 23 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.
- **39 rules.** Images, tables, lists, landmarks, forms, controls, page language and WAI-ARIA, 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.

## 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   1 template
  accounts/templates  app accounts  2 templates
  catalog/jinja2      app catalog   1 template (jinja2)

8 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 23 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 |

## 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) |

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.6.0
    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/
```

### 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

ramplint is a static checker. It catches structural problems early and cheaply,
but it cannot judge colour contrast or focus order, or tell whether an `alt`
text is actually meaningful. Use it together with manual testing and a runtime
tool such as axe.

## 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 %}`
- [ ] `--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
