ramplint
Accessibility linter for Django and Jinja2 templates.
Catch WCAG problems in your .html templates before they reach production.
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:
Try it in 30 seconds
The repository ships with a small demo shop in 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.
git clone https://github.com/iLLcruS/ramplint.git
cd ramplint
pip install .
ramplint examples/
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 32 problems in 6 of 8 files.
See examples/README.md for what each demo template contains.
Highlights
- 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 %},{{ widget.attrs }},{% block %}), ramplint assumes the best and stays quiet. - Zero dependencies. Pure Python standard library (plus
tomlion 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
pip install ramplint
Usage
ramplint # lint every template under the current directory
ramplint templates/ shop/templates/base.html
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 --list-rules
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.
| Exit code | Meaning |
|---|---|
0 |
No problems found |
1 |
Problems found |
2 |
Usage or configuration error |
Rules
| Code | Name | What it checks | WCAG |
|---|---|---|---|
RL101 |
img-alt |
<img> has an alt attribute; <input type="image"> and <area> have non-empty alt |
1.1.1 (A) |
RL102 |
iframe-title |
<iframe> has a title describing its content |
4.1.2 (A) |
RL201 |
table-header |
Data tables use real <th> header cells |
1.3.1 (A) |
RL301 |
heading-order |
Heading levels do not skip (<h2> → <h4>) |
1.3.1 (A) |
RL302 |
empty-heading |
Headings are not empty | 2.4.6 (AA) |
RL303 |
duplicate-id |
id values are unique (same id in {% if %} / {% else %} branches is allowed) |
1.3.1 (A) |
RL401 |
form-label |
<input>, <select> and <textarea> have an associated <label> |
1.3.1, 4.1.2 (A) |
RL402 |
autocomplete-valid |
autocomplete uses valid autofill tokens (catches typos like emial) |
1.3.5 (AA) |
RL501 |
button-name |
Buttons (including icon-only buttons) have an accessible name | 4.1.2 (A) |
RL502 |
link-name |
Links have an accessible name | 2.4.4, 4.1.2 (A) |
RL503 |
no-positive-tabindex |
tabindex is not greater than 0 |
2.4.3 (A) |
RL504 |
anchor-is-valid |
Links have a real target (no href="#", javascript: or click-only <a>) |
2.1.1 (A) |
RL601 |
html-lang |
<html> declares the page language |
3.1.1 (A) |
RL602 |
viewport-zoom |
<meta name="viewport"> does not disable zoom (user-scalable=no, maximum-scale < 2) |
1.4.4 (AA) |
Examples for every rule
RL101 img-alt
{# ✗ #} <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
{# ✗ #} <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.
RL201 table-header
{# ✗ #} <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.
RL301 heading-order
{# ✗ #} <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
{# ✗ #} <h2><i class="icon-star"></i></h2>
{# ✓ #} <h2>{% trans "Favourites" %}</h2>
RL303 duplicate-id
{# ✗ #} <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.
RL401 form-label
{# ✗ #} <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
{# ✗ #} <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
closest valid token.
RL501 button-name
{# ✗ #} <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
{# ✗ #} <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
{# ✗ #} <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
{# ✗ #} <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.
RL601 html-lang
{# ✗ #} <html>
{# ✓ #} <html lang="{{ LANGUAGE_CODE }}">
RL602 viewport-zoom
{# ✗ #} <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%.
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) |
{% if %}, {% for %}, {% with %}, ... |
Nothing (control flow) |
{# ... #}, {% comment %}...{% endcomment %} |
Nothing |
Both branches of an {% if %} are checked, so a problem in either one is reported.
Suppressing problems
<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.
[tool.ramplint]
select = ["RL"] # default: all rules
ignore = ["RL301"]
exclude = ["*/admin/*", "templates/vendor/*"]
extensions = [".html", ".txt"]
pre-commit
# .pre-commit-config.yaml
repos:
- repo: https://github.com/iLLcruS/ramplint
rev: 0.2.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.
- run: pip install ramplint
- run: ramplint templates/
Python API
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
- More rules:
<iframe title>, duplicateids,autocompleteon personal-data inputs -
aria-*attribute and role validation -
--fixfor safe autofixes (e.g.scope="col"on header rows) - SARIF output for GitHub code scanning
- Follow
{% extends %}/{% include %}to check heading order across templates
Contributing
Bug reports, especially about false positives, are very welcome. See CONTRIBUTING.md.
Feedback and support
Questions, ideas, or using ramplint in your project? Open an issue or email me at rostovskii.1020@gmail.com.
ramplint is free and built in my spare time. If it saved you time, you can buy me a coffee:
License
MIT © Vladyslav Rostovskyi
1 maintainer
Metadata
1 maintainer
Release files for ramplint 0.2.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | |
|---|---|---|---|---|
| ramplint-0.2.0.tar.gz | 38.7 kB | With provenance | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| ramplint-0.2.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 69.4 kB
Release files / ramplint-0.2.0.tar.gz
| Download URL | ramplint-0.2.0.tar.gz |
|---|---|
| Size | 38.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
c6dad6d3729260fc72f4de7ca2c82e1f04145d2fb583b28be021fa7218be65b3
|
|
BLAKE2b-256 checksum How to use checksums |
36bb443f29ce86da99a010fc52567dcdf24e39560d1def866d6a6cf40673dc79
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 20, 2026.
Transparency logRelease files / ramplint-0.2.0-py3-none-any.whl
| Download URL | ramplint-0.2.0-py3-none-any.whl |
|---|---|
| Size | 30.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
b2c4f9cf307bf214fad5a5327327639f30eaf0067426896676c86c7174be1aed
|
|
BLAKE2b-256 checksum How to use checksums |
7d436c833577315281fbf8d90a79786643ccf6fa2bd5acb2f70cb206f3e984df
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 20, 2026.
Transparency logSecurity for ramplint 0.2.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
All 2 files in this release have been uploaded with provenance metadata.
Attestation for ramplint-0.2.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 20, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
