Cutesy 🥰

A cute little HTML linter, until y̵ou ma̴k̵e i̴͌ͅt̴̖̀ a̵̤̤͕̰͐̅͘͘n̶̦̣͙̑̌̆̄ǵ̷̗̗̀͝r̷̭̈́͂͘ẙ̶͔̟̞̊̈…̴̢͘

Cutesy reformats & lints HTML documents, including HTML templates. It ensures consistent indentation, line breaks, and formatting while automatically fixing most issues.

First-class support for your favorite frameworks ❤️

• Full support for Django templates 🐍💕
• Sorts classes for TailwindCSS 💖✨
• Works with AlpineJS and HTMX ⚡💘

Features ✨

• Auto-fix: Automatically corrects most formatting issues
• Configurable: Extensive configuration options for your project's needs
• Fast: Rust core for high performance

Status

Table of Contents

• Quick Start
• Installation
• Basic Usage
• Configuration
• Framework Support
• Examples
• Documentation
• When to Use Cutesy
• Benefits
• Badge
• License
• Contributing

🚀 Quick Start

Install:

pip install cutesy

Format your HTML files:

cutesy "*.html" --fix

For Django projects with TailwindCSS:

cutesy "templates/**/*.html" --fix --extras=[django,tailwind]

Installation

Cutesy requires Python 3.12+ and works on Linux, macOS, and Windows.

Basic Installation:

pip install cutesy

For system-wide CLI tool:

pipx install cutesy

Development Installation:

git clone https://github.com/chasefinch/cutesy.git
cd cutesy
pip install -e .

📚 Detailed guide: See Installation Documentation for editor integration, pre-commit hooks, and CI/CD setup.

Basic Usage

Command Line

Check files for issues:

cutesy "*.html"                    # Check all HTML files
cutesy "templates/**/*.html"       # Check recursively
cutesy --code '<div>test</div>'    # Check code string

Fix issues automatically:

cutesy "*.html" --fix              # Fix all issues
cutesy "*.html" --fix --quiet      # Fix quietly
cutesy "*.html" --return-zero      # Don't fail CI on issues

Key Options

Configuration

Configuration Files

Create a cutesy.toml file in your project:

fix = true
extras = ["django", "tailwind"]
indentation_type = "spaces"
line_length = 99
ignore = ["F1"]  # Ignore specific rules

Also supports:

• pyproject.toml (under [tool.cutesy])
• setup.cfg (under [cutesy])

Common Configurations

Django + TailwindCSS:

fix = true
extras = ["django", "tailwind"]
line_length = 120
max_items_per_line = 6

📚 Complete guide: See Configuration Documentation for all options and examples.

Framework Support

Django Templates

Enable Django template processing:

cutesy "templates/*.html" --fix --extras=django

Supports:

• {% %} template tags with proper indentation
• {{ }} variables
• Template inheritance ({% extends %}, {% block %})
• Complex template logic with nested HTML

Example transformation:

<!-- Before -->
{% if user.is_authenticated %}
<div class="welcome">
        <h1>Welcome, {{ user.name }}!</h1>
{% endif %}

<!-- After -->
{% if user.is_authenticated %}
    <div class="welcome">
        <h1>Welcome, {{ user.name }}!</h1>
    </div>
{% endif %}

TailwindCSS

Automatic class sorting and organization:

cutesy "*.html" --fix --extras=tailwind

Features:

• Smart sorting: Groups utility classes logically
• Responsive prefixes: Maintains sm:, md:, lg: order
• Pseudo-classes: Preserves hover:, focus:, etc.
• Custom classes: Keeps your custom classes at the end

Example:

<!-- Before -->
<div class="text-red-500 p-4 bg-white hover:bg-gray-100 md:p-8 rounded-lg">

<!-- After -->
<div class="bg-white hover:bg-gray-100 p-4 md:p-8 rounded-lg text-red-500">

AlpineJS & HTMX

Cutesy works great with attribute-heavy frameworks:

• Proper indentation for multi-line attributes
• Whitespace normalization inside attributes
• Consistent formatting across your components

Examples

Cutesy ensures that HTML documents contain consistent whitespace, follow best practices, and adhere to common conventions. In --fix mode, Cutesy turns this:

    <!doctype html>
<html>
                    <head>
        <title>Cutesy 🥰 demo</title>
    </head>
<body>
            <h1>Hi     there!</h1>


            {% if request.user.is_authenticated %}
                    <p>Cutesy is so happy      when your code is neat.</p>
                            {% endif %}



                <div     class='danger-zone'
                        id="lintTrap"   ></div    >
                    </body>
</html>

…into this:

<!doctype html>
<html>
<head>
    <title>Cutesy 🥰 demo</title>
</head>
<body>
    <h1>Hi there!</h1>

    {% if request.user.is_authenticated %}
        <p>Cutesy is so happy when your code is neat.</p>
    {% endif %}

    <div id="lintTrap" class="danger-zone"></div>
</body>
</html>

Real-World Usage

Django Project:

# Format all templates
cutesy "templates/**/*.html" --fix --extras=[django,tailwind]

# Check before committing
cutesy "templates/**/*.html" --quiet

Static Site:

# Format with custom config
cutesy "src/**/*.html" --fix --line-length=120

# Format specific files
cutesy "src/components/*.html" --fix --extras=tailwind

Documentation

When to Use Cutesy

Cutesy is great for:

• Server-rendered HTML templates with Django, Jinja2, ERB, Liquid, and other template engines
• Attribute-heavy patterns like AlpineJS and HTMX, with smart attribute reordering and formatting
• Component frameworks like Svelte and Vue (.svelte, .vue files) with HTMLX-style syntax
• Speed-focused static analysis for HTML — fast, with additional linting and best-practice checks beyond formatting
• Pluggability — better hooks for custom attribute ordering, validation, and transformation
• AI code validation — an all-in validation strategy to maximize code quality and catch errors, which agents can use to validate and update their own output

Not for

• JSX / TSX files — Cutesy formats HTML templates, not JavaScript files.
• Standalone JS / CSS files — Cutesy’s just for HTML, the templates that generate it, and the styles & scripts inside it. Use a CSS/JS toolchain for external files. Avoid JS or CSS “templates” which accept server instructions; Keep this in your HTML.

Why not Prettier, Stylelint & ESLint? Cutesy uses all three under the hood for formatting scripts & styles, and it will even respect your configuration for each. Cutesy provides access to these tools (as well as Typescript and automated testing) for server-rendered HTML templates, for <style> and <script> blocks inside of HTML documents, and for styles & scripts inside of HTML attributes.

Aside from that, Cutesy enforces an opinionated style for the HTML itself, along with any template-language tags, and it includes additional post-format analysis such as HTML & framework best practices. (Think image sizing, load order, template tag formatting, Tailwind theme setup, etc.)

Benefits

• ✅ Validate AI code output - Catch inconsistencies in generated HTML
• ✅ Enforce team standards - Consistent formatting across all developers
• ✅ Catch errors early - Find malformed HTML and template syntax issues
• ✅ Save time - No more manual formatting or style discussions
• ✅ Better code reviews - Focus on logic, not formatting
• ✅ Framework integration - Works with your existing tools and workflows

Badge

Show off how Cutesy keeps you in line.

[![code style: cutesy](https://img.shields.io/badge/code_style-cutesy_🥰-fd7f9c.svg?style=flat)](https://github.com/chasefinch/cutesy)

License

MIT License - see LICENSE file for details.

Contributing

We welcome contributions! Whether it's:

• 🐛 Bug reports via GitHub Issues
• 💡 Feature requests via GitHub Discussions
• 🔧 Code contributions via Pull Requests
• 📖 Documentation improvements

See our Development Guide for getting started.

Keep your HTML tidy with Cutesy! 🥰

or els̴͔e