DOCSEARCHbyAlgolia
Submit Docs

curlylint

repository·main·Indexed 42 days ago

https://github.com/thibaudcolas/curlylint

An experimental linter for HTML and 'curly brace' template languages including Jinja, Nunjucks, Django templates, Twig, and Liquid. It focuses on identifying accessibility issues and enforcing HTML best practices through built-in rules such as aria_role, image_alt, and html_has_lang. Version 0.1.0 supports configuration via pyproject.toml or CLI flags.

Tokens
9.8K
Snippets
41
Records
56
Agent score
49%

What's inside curlylint

  1. Overview of curlylint features

    main

    curlylint is an experimental HTML and template linter. Its primary focus is on checking for common accessibility issues within HTML and template languages.

    Supported template languages include:

    • Jinja
    • Nunjucks
    • Django templates
    • Twig
    • Liquid

    Future roadmap items include expanded accessibility checks and security checks (e.g., checking for rel="noopener noreferrer" or known XSS vulnerabilities).

  3. Understand curlylint version support policy

    main
    The project does not provide formal support targets for versions older than the latest release. Security fixes for older versions are handled on a case-by-case basis, depending on the effort required and the prevalence of the affected versions in use.

  4. Enforce template-specific best practices like Django form rendering

    main

    Beyond standard HTML, Curlylint can enforce best practices specific to template languages (such as Jinja, Twig, or Liquid) and frameworks.

    A key example is the django_forms_rendering rule, which is specifically designed for Django projects. This rule restricts how forms are rendered to ensure they meet accessibility requirements. This capability allows you to codify framework-specific best practices (like those for Django or Wagtail) directly into your linting workflow.

  5. Supported template languages in curlylint

    main

    curlylint is designed to lint template languages that use "curly braces" syntax. It supports languages that use double curly braces for variable interpolation ({{ ... }}), curly braces with percent signs for special blocks or tags ({% ... %}), and pipes for filters (|).

    Supported languages include:

    • Jinja: Primary target; the parser and AST nomenclature are based on Jinja.
    • Nunjucks: Identical to Jinja for linting purposes.
    • Django templates: Nearly identical to Jinja.
    • Twig: Supported via syntax similarity; HTML checks work well, but template syntax checks may be less stable.
    • Liquid: Supported via syntax similarity; HTML checks work well, but template syntax checks may be less stable.
    • HTML: Can be used as a standalone HTML linter.
    <!-- Double curly braces for variables interpolation -->
{{ pretty_cool_variable }}
<!-- Curly braces with percent signs for special blocks or tags -->
{% my_special_tag %}
<!-- Pipes for filters -->
{{ pretty_cool_list|length }}

  6. Understand how Curlylint rule documentation is generated

    main

    Curlylint rule documentation is automatically generated from three primary sources:

    1. JSON Schema: Defines configuration options, including titles, descriptions, and examples.
    2. Test Cases: The success and failure examples shown in the documentation are pulled directly from the project's test suite using specific flags.
    3. MDX: Combines these elements using Markdown-inspired syntax with React components to provide interactive features like language tabs and annotated code snippets.

  7. Understand Curlylint configuration lookup hierarchy

    main

    Curlylint follows a specific precedence order when resolving configuration options. If a setting is defined in multiple places, the highest precedence wins:

    1. Command-line options: Options provided directly by the user during execution have the highest priority.
    2. pyproject.toml: Values defined in the [tool.curlylint] section override the tool's internal defaults.
    3. Internal defaults: The fallback values used if no configuration is provided.

    Note: Curlylint only uses a single pyproject.toml file per run. It does not compose or merge configurations from multiple files found in different levels of the directory hierarchy.

  8. Lint templates with the curlylint CLI

    main

    Once installed, you can lint a directory containing templates by passing the directory path to the curlylint command. It is designed to lint HTML and "curly brace" templates (such as Jinja, Nunjucks, Django, Twig, and Liquid) while focusing on accessibility issues.

    curlylint template-directory/

  12. Use accessibility-related linting rules in Curlylint

    main

    Curlylint includes 7 built-in accessibility rules designed to enforce HTML best practices within your templates. These rules automate the checking of attributes against established standards to ensure your templates are more accessible by default.

    Available accessibility rules include:

    • aria_role: Validates that role attributes contain valid ARIA roles.
    • html_has_lang: Ensures the <html> element has a lang attribute.
    • image_alt: Checks for the presence of alt attributes on <img> tags.
    • meta_viewport: Ensures the meta viewport tag is present.
    • no_autofocus: Detects the use of the autofocus attribute.
    • tabindex_no_positive: Prevents the use of positive tabindex values (which can disrupt natural tab order).

    For a complete list of all available rules, refer to the All rules documentation.