/htmlhint

name: htmlhint
description: "Use HTMLHint in .NET repositories that ship static HTML output or standalone frontend templates. USE FOR: static HTML files; generated frontend output; standalone templates under wwwroot, dist, or other web folders; HTML structure checks. DO NOT USE FOR: raw .cshtml or .razor source with server-side directives; JavaScript or TypeScript linting. INVOKES: inspect the repository context, edit targeted files, and run relevant build, test, lint, or validation commands when changes are made."
compatibility: "Requires a .NET repository with static HTML assets or generated frontend output; use on rendered output rather than raw Razor or Blazor source files."

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?"