Improve Your Markup — Top THTMLHint Rules to Use Today

How to Integrate THTMLHint into Your Build PipelineIntegrating THTMLHint into your build pipeline helps enforce consistent HTML quality, catch accessibility and syntax issues early, and prevent regressions introduced by new code. This guide covers everything from installing THTMLHint and configuring rules to adding it to common CI systems and automating fix workflows.

---

What is THTMLHint and why use it?

THTMLHint is an HTML linter that analyzes markup for syntax errors, best-practice violations, accessibility problems, and stylistic issues. It runs locally or in CI to:

• Catch markup errors early (missing end tags, invalid attributes).
• Enforce consistency across a team’s HTML.
• Improve accessibility by flagging missing ARIA attributes, alt text, etc.
• Integrate with editors and CI so fixes can be automated or reviewed before merge.

---

Install THTMLHint

If your project uses Node.js, install THTMLHint as a dev dependency:

npm install --save-dev thtmlhint 

For Yarn:

yarn add --dev thtmlhint 

You can also install it globally for running ad-hoc checks:

npm install -g thtmlhint 

---

Configure rules

THTMLHint is configured with a config file (commonly .thtmlhintrc or thtmlhint.config.json). Place it at your project root so the CLI and editor integrations pick it up automatically.

Example .thtmlhintrc:

{   "attr-lowercase": true,   "attr-no-dup": true,   "doctype-first": true,   "tagname-lowercase": true,   "attr-value-not-empty": true,   "alt-require": true,   "id-unique": true,   "spec-char-escape": true } 

• Start with the default recommended rules, then tailor to your codebase.
• For large legacy codebases, you can disable strict rules and enable them progressively.
• Use overrides or multiple config files if your repo mixes HTML types (static templates vs. components).

---

Run THTMLHint locally

Add an npm script for convenience:

{   "scripts": {     "lint:html": "thtmlhint "src/**/*.html""   } } 

Run:

npm run lint:html 

Key CLI options:

• Specify globs to target files: thtmlhint “app/*/.html”
• Use –config to point to a different config file
• Use –reporter to change output format (useful for CI integrations)

---

Integrate into Git hooks (pre-commit)

Prevent broken HTML from entering the repo by running THTMLHint in a pre-commit hook. Use Husky and lint-staged for an efficient setup:

Install dev dependencies:

npm install --save-dev husky lint-staged 

package.json example:

{   "husky": {     "hooks": {       "pre-commit": "lint-staged"     }   },   "lint-staged": {     "src/**/*.html": [       "thtmlhint",       "git add"     ]   } } 

This checks only staged files and blocks commits when violations are found.

---

Add to continuous integration

Integrate THTMLHint into CI so pull requests are automatically verified. Below are examples for GitHub Actions, GitLab CI, and CircleCI.

GitHub Actions example (.github/workflows/lint-html.yml):

name: Lint HTML on: [push, pull_request] jobs:   thtmlhint:     runs-on: ubuntu-latest     steps:       - uses: actions/checkout@v4       - uses: actions/setup-node@v4         with:           node-version: '18'       - run: npm ci       - run: npm run lint:html 

Key tips:

• Use npm ci for deterministic installs.
• Cache node_modules to speed builds if needed.
• Use a reporter that outputs machine-readable results (Jest/JUnit-style) if your CI supports annotations.

---

Integrate with build tools

If your project uses task runners or bundlers, run THTMLHint as part of build/test stages.

• Gulp:
  • Use gulp-shell or a dedicated plugin to run thtmlhint before build tasks.
• Webpack:
  • Run thtmlhint via an npm script in the prebuild step or use the new plugin ecosystem to surface warnings as build-time errors.
• Makefile:
  • Add a lint target:

lint-html: 	npm run lint:html 

Call it from CI or local builds: make lint-html.

---

Reporters and annotations

For better developer feedback, integrate THTMLHint output with your tooling:

• Use a CI-friendly reporter (JSON, JUnit) and convert to platform annotations.
• GitHub Actions: parse output and create check annotations using actions/upload-artifact or custom scripts.
• Use third-party tools to display issues inline in PRs, or integrate with code review bots.

---

Auto-fix and formatting

THTMLHint may not support automatic fixing for all rules. For rules that are autofixable, combine with formatters (Prettier for HTML) to apply deterministic formatting. Example workflow:

1. Run thtmlhint to detect issues.
2. Run Prettier to format markup.
3. Re-run thtmlhint — remaining issues should be semantic or accessibility related.

Automate this in pre-commit hooks or CI pipelines to reduce manual fixes.

---

Handling legacy codebases

Large codebases often produce many initial lint errors. Strategies:

• Start with a baseline: run thtmlhint, export current violations, and set that as a baseline to avoid failing CI initially.
• Introduce rules gradually: enable a small set of high-value checks first (syntax, missing alt).
• Use per-directory configs or comments to disable rules for specific files temporarily.
• Include a plan and timeline to progressively tighten the rules.

---

Testing and monitoring

• Add a CI job that fails on new violations but allows the baseline to pass.
• Use metrics: track number of HTML lint issues per PR and per week to see improvement.
• Enforce zero-new-issues policy on pull requests.

---

Example end-to-end workflow

1. Developer edits HTML and formats with Prettier in their editor.
2. Commit triggers Husky -> lint-staged -> thtmlhint on staged files.
3. Push opens PR; GitHub Actions runs npm ci and npm run lint:html.
4. If issues are found, the CI job fails and annotates the PR with errors.
5. Developer fixes issues and re-runs same checks before merging.

---

Troubleshooting common problems

• False positives: adjust config or disable rule for file(s).
• Performance on large repos: lint only changed files in hooks; in CI, run full lint on main branch nightly.
• Conflicting formatters: ensure Prettier and THTMLHint rules align or run formatters before linting.

---

Conclusion

Integrating THTMLHint into your build pipeline raises HTML quality, catches issues early, and improves accessibility. Install it as a dev dependency, configure rules appropriate to your codebase, and enforce checks at commit, CI, and build stages. Start with high-impact rules, use baselining for legacy code, and automate reporting to give developers clear, actionable feedback.