htmlhint

HTMLHint for Static HTML in .NET Repositories

Trigger On

• the repo has static HTML files, generated frontend output, or standalone templates under wwwroot/, dist/, or other web folders
• the user asks for HTML structure checks, invalid attribute detection, or basic DOM-quality linting
• the repo wants a narrow HTML gate separate from JS, CSS, and full-site runtime audits

Do Not Use For

• raw .cshtml or .razor source with server-side directives; lint the rendered or published output instead
• JavaScript or TypeScript linting; route that to eslint
• runtime performance, accessibility, SEO, or headers; route that to webhint

Inputs

• the nearest AGENTS.md
• package.json
• .htmlhintrc or equivalent config if present
• the real static HTML target: source templates, built output, or deployed URL

Workflow

1. Choose the right target first:
   • static HTML source files
   • generated build output such as dist/
   • a reachable URL when the page is already served
2. Prefer repo-local installation and checked-in config for repeatable runs.
3. Keep HTMLHint focused on static HTML correctness and lightweight policy.
4. Add narrow scripts to package.json, for example:
   • htmlhint "dist/**/*.html"
   • htmlhint "wwwroot/**/*.html"
5. If the repo has templating syntax that confuses the parser, lint the rendered output instead of forcing source templates through the tool.
6. Use rule overrides deliberately for real project conventions; do not disable broad classes of checks just to make a noisy first pass green.
7. Rerun the publish or frontend build flow if fixes touched generated or packaged HTML sources.

Bootstrap When Missing

1. Detect current state:
   • rg --files -g 'package.json' -g '.htmlhintrc*' -g '*.html'
   • rg -n '"htmlhint"' --glob 'package.json' .
2. Prefer a repo-local install:
   • npm install --save-dev htmlhint
3. Add or refine .htmlhintrc only after confirming the actual target files.
4. Add repeatable commands to AGENTS.md and package.json, then verify with:
   • npx htmlhint "dist/**/*.html"
   • npx htmlhint https://example.com
5. Return status: configured if HTMLHint now owns a clear static-HTML gate, or status: improved if the existing setup was tightened.
6. Return status: not_applicable when the repo's HTML is primarily server-rendered templates that should be validated after rendering instead.

Handle Failures

• Parser noise on Razor, Blazor, or other server-side template syntax is a target-selection problem; lint built output instead of source templates.
• URL-based checks can fail on auth, SPA routing, or environment drift; verify the served target is reachable and stable before trusting the result.
• Large volumes of trivial attribute warnings usually mean the config was copied from another stack and needs to be adapted to the repo's real HTML conventions.

Deliver

• a repeatable static HTML lint gate
• clear targeting rules for source HTML versus rendered output
• checked-in config that matches the repo's actual page structure

Validate

• the lint target contains real static HTML, not unsupported template syntax
• commands are reproducible from repo-local dependencies
• HTMLHint ownership is kept separate from broader site-audit tooling
• fixes were verified on the built or served output that actually ships

Ralph Loop

1. Plan: analyze current state, target outcome, constraints, and risks.
2. Execute one step and produce a concrete delta.
3. Review the result and capture findings.
4. Apply fixes in small batches and rerun checks.
5. Update the plan after each iteration.
6. Repeat until outcomes are acceptable.
7. If a dependency is missing, bootstrap it or return status: not_applicable with a reason.

Required Result Format

• status: complete | clean | improved | configured | not_applicable | blocked
• plan: concise plan and current step
• actions_taken: concrete changes made
• verification: commands, checks, or review evidence
• remaining: unresolved items or none

Example Requests

• "Add HTMLHint for the built static site in this repo."
• "Lint the generated HTML before deployment."
• "Why is HTMLHint failing on Razor pages?"