curlylint 0.10.0

{{ 🎀}} Experimental linter for Jinja, Nunjucks, Django templates, Twig, Liquid

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.