{{ 🎀}} Experimental linter for Jinja, Nunjucks, Django templates, Twig, Liquid
Project description
curlylint
{{ 🎀}} Experimental linter for Jinja, Nunjucks, Django templates, Twig, Liquid. Forked from jinjalint.
Features
curlylint is an experimental linter for “curly braces” templates, and their HTML. It supports:
- Linting invalid template / HTML syntax due to mismatched tags – while template errors are easy enough to spot, it’s not rare for HTML issues to make their way to live sites.
- Indentation inconsistencies – Usage of tabs vs spaces, line breaks, indentation size.
- Rules to check for common accessibility issues.
In the future, we’d like to lint for:
- Common accessibility issues in HTML – misuse of ARIA
role
, and making sure alternative text is used where appropriate. - Common security issues – e.g.
rel="noopener noreferrer"
, or preventing usage of HTTP URLs. - General HTML code smells – duplicate attributes, invalid attributes, etc.
- More ideas welcome!
Usage
curlylint is available on PyPI. To install it,
pip install curlylint
We support the following Python versions: 3.6, 3.7, 3.8.
Make sure curlylint is correctly installed by running:
curlylint --version
curlylint --help
You can start linting!
curlylint template-directory/
# Or,
curlylint some-file.html some-other-file.html
Have a look at the CLI flags, Configuration, and Rules below to make the most of it.
CLI flags
--verbose
Turns on verbose mode. This makes it easier to troubleshoot what configuration is used, and what files are being linted.
curlylint --verbose template-directory/
--quiet
Don’t emit non-error messages to stderr. Errors are still emitted; silence those with 2>/dev/null
.
curlylint --quiet template-directory/
--parse-only
Don’t lint, check for syntax errors and exit.
curlylint --parse-only template-directory/
--print-config
Print the configuration for the given file, and exit.
curlylint --print-config some-file.html
--rule
Specify rules, with the syntax --rule 'code: {"json": "value"}'
. Can be provided multiple times to configure multiple rules.
curlylint --rule 'indent: 2' --rule 'html_has_lang: true' template-directory/
Reading from standard input
Pipe the template to curlylint and use a path of -
so curlylint reads from stdin:
cat some-file.html | curlylint -
The --stdin-filepath
flag can be used to provide a fake path corresponding to the piped template for linting and reporting:
cat some-file.html | curlylint - --stdin-filepath some-file.html
Configuration
curlylint is able to read project-specific default values for its command line options from a PEP 518 pyproject.toml
file.
Where curlylint looks for the file
By default curlylint looks for pyproject.toml
starting from the common base directory of all files and directories passed on the command line. If it's not there, it looks in parent directories. It stops looking when it finds the file, or a .git
directory, or a .hg
directory, or the root of the file system, whichever comes first.
You can also explicitly specify the path to a particular file that you want with --config
. In this situation curlylint will not look for any other file.
If you're running with --verbose
, you will see a blue message if a file was found and used.
Configuration format
As the file extension suggests, pyproject.toml
is a
TOML file. It contains separate sections for
different tools. curlylint is using the [tool.curlylint]
section. The option keys are the same as long names of options on the command line.
Example `pyproject.toml`
[tool.curlylint]
# Specify additional Jinja elements which can wrap HTML here. You
# don't neet to specify simple elements which can't wrap anything like
# {% extends %} or {% include %}.
jinja-custom-elements-names = [
["cache", "endcache"],
["captureas", "endcaptureas"]
]
include = '\.(html|jinja)$'
exclude = '''
(
/(
\.eggs # exclude a few common directories in the root of the project
| \.git
| \.venv
| build
| dist
)/
| webpack-stats.html # also separately exclude a file named webpack-stats.html in the root of the project
)
'''
[tool.curlylint.rules]
# How many spaces
indent = 4
html_has_lang = 'en-GB'
Lookup hierarchy
Command-line options have defaults that you can see in --help
. A pyproject.toml
can override those defaults. Finally, options provided by the user on the command line override both.
curlylint will only ever use one pyproject.toml
file during an entire run. It doesn't look for multiple files, and doesn't compose configuration from different levels of the file hierarchy.
Rules
indent
Enforces consistent indentation. Options:
# Use the given number of spaces.
indent = 4
# Use tabs.
indent = "tab"
html_has_lang
Checks all html
elements have a lang
attributes. Options:
# The `lang` attribute must be present.
html_has_lang = true
# The `lang` attribute must be a specific value.
html_has_lang = "en-US"
# The `lang` attribute must be one of the possible values.
html_has_lang = ["en", "en-GB", "en-US"]
aria_role
Checks all role
attributes use valid values. Options:
# The role attribute must be a valid ARIA role.
aria_role = true
# The role attribute must be one of the whitelisted options.
aria_role = ["region", "search", "alert", "dialog"]
Usage with pre-commit git hooks framework
Add to your .pre-commit-config.yaml
:
- repo: https://github.com/thibaudcolas/curlylint
rev: "" # select a tag / sha to point at
hooks:
- id: curlylint
Make sure to fill in the rev
with a valid revision.
Note: by default this configuration will only match .jinja
and .jinja2
files. To match by regex pattern instead, override types
and files
as
follows:
- id: curlylint
types: [file] # restore the default `types` matching
files: \.(html|sls)$
Contributing
See anything you like in here? Anything missing? We welcome all support, whether on bug reports, feature requests, code, design, reviews, tests, documentation, and more. Please have a look at our contribution guidelines.
If you just want to set up the project on your own computer, the contribution guidelines also contain all of the setup commands.
Credits
Image credit: FxEmojis.
This project is a fork of jinjalint.
Test templates extracted from third-party projects. View the full list in tests/README.md
.
View the full list of contributors. MIT licensed.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.