docs: add docs for using HTML ESLint with other HTML-processing plugins #435

Copilot · 2025-11-01T16:45:01Z

Users need to configure HTML ESLint alongside other plugins like eslint-plugin-html to lint both HTML syntax and inline JavaScript, but ESLint's parser architecture prevents using both in a single config file. This creates confusion and undocumented workarounds.

Changes

Documentation

New guide: docs/using-with-other-plugins.md explaining the parser conflict and solution
- Why separate config files are required (different parsers for same file extensions)
- Step-by-step setup with complete working examples
- npm scripts integration pattern
- Links to upstream ESLint issues (#18808, #14286, #17655)

Integration

README: Added guide link to TOC and "Lint JavaScript inside HTML" section
FAQ: New entry referencing the comprehensive guide
Website nav: Added menu item for easy discovery

Example Configuration

// eslinthtml.config.mjs - HTML syntax
import html from "@html-eslint/eslint-plugin";
export default [{ 
  files: ["**/*.html"], 
  plugins: { html },
  extends: ["html/recommended"],
  language: "html/html"
}];

// eslintjs.config.mjs - JavaScript in HTML  
import htmlPlugin from "eslint-plugin-html";
export default [{ 
  files: ["**/*.html"],
  plugins: { html: htmlPlugin },
  rules: { "no-unused-vars": "error" }
}];

Run both: eslint --config eslinthtml.config.mjs "**/*.html" && eslint --config eslintjs.config.mjs "**/*.html"

Resolves #108, #211

Original prompt

This section details on the original issue you should resolve

<issue_title>feature_request(docs): configuring HTML ESLint with other plugins for HTML files</issue_title>
<issue_description>Related issues — #108, #211

1. Summary

It would be helpful if HTML ESLint documentation will contain information on how users should configure HTML ESLint if they use other ESLint plugins for HTML files like eslint-plugin-html.

2. Argumentation of the need of the documentation improvements

I created the additional configuration file eslinthtml.config.mjs for HTML ESLint and additionally need launching ESLint with the argument --config — eslint --config eslinthtml.config.mjs. I can’t configure HTML ESLint and eslint-plugin-html both in a single file eslint.config.mjs. Due to the ESLint discussion #18808 opened by @yeonjuan and issues #14286 and #17655 it’s not possible and not planned. If it’s possible, please show me what I need to change in my MCVE (the item 4.3.1 of this issue).

Whether it’s possible or not, setting the HTML ESLint configuration may take a lot of time. Documentation improvements can significantly reduce the time needed for setting.

3. MCVE

3.1. Installation

npm init

npm install --save-dev eslint eslint-plugin-html @eslint/js @html-eslint/eslint-plugin @html-eslint/parser

3.2. HTML file for testing

KiraExample.html:

<!-- example comment -->
<!DOCTYPE html>
<html lang="en">

<head>
	<meta charset="UTF-8">
	<meta content="width=device-width, initial-scale=1.0" name="viewport">
	<title>Kira example HTML</title>

	<script>
		let Kira = "Goddess"

	</script>
</head>

<body>
	<p>Kira Goddess!</p>
</body>

</html>

4. Configurations

4.1. Solely for HTML ESLint

4.1.1. Configuration file

eslinthtml.config.mjs:

import eslintPluginHtml from "@html-eslint/eslint-plugin";
import htmlParser from "@html-eslint/parser";

export default [{
	files: ["**/*.html"],
	languageOptions: {
		parser: htmlParser
	},
	plugins: {
		"@html-eslint": eslintPluginHtml,
	},
	rules: {
		...eslintPluginHtml.configs["flat/recommended"].rules
	}
}];

4.1.2. CLI command

D:\SashaDebugging\KiraESLintHTML>npx eslint KiraExample.html --config eslinthtml.config.mjs

D:\SashaDebugging\KiraESLintHTML\KiraExample.html
   5:1  error  Expected indentation of 4 space but found no indent  @html-eslint/indent
   6:1  error  Expected indentation of 8 space but found 1 tab      @html-eslint/indent
   7:1  error  Expected indentation of 8 space but found 1 tab      @html-eslint/indent
   8:1  error  Expected indentation of 8 space but found 1 tab      @html-eslint/indent
  10:1  error  Expected indentation of 8 space but found 1 tab      @html-eslint/indent
  13:1  error  Expected indentation of 8 space but found 1 tab      @html-eslint/indent
  14:1  error  Expected indentation of 4 space but found no indent  @html-eslint/indent
  16:1  error  Expected indentation of 4 space but found no indent  @html-eslint/indent
  17:1  error  Expected indentation of 8 space but found 1 tab      @html-eslint/indent
  18:1  error  Expected indentation of 4 space but found no indent  @html-eslint/indent

✖ 10 problems (10 errors, 0 warnings)
  10 errors and 0 warnings potentially fixable with the `--fix` option.

4.1.3. Behavior

Expected. ESLint returns HTML ESLint’s errors.

4.2. Solely for eslint-plugin-html

4.2.1. Configuration file

eslintjs.config.mjs:

import pluginJs from "@eslint/js";
import eslintPluginHtmlInlineScripts from "eslint-plugin-html";

export default [{
	files: ["**/*.{cjs,js,html,mjs}"],
	plugins: {
		eslintPluginHtmlInlineScripts
	},
	rules: {
		...pluginJs.configs.all.rules
	}
}];

4.2.2. CLI command

D:\SashaDebugging\KiraESLintHTML>npx eslint KiraExample.html --config eslintjs.config.mjs

D:\SashaDebugging\KiraESLintHTML\KiraExample.html
  11:7  error  'Kira' is assigned a value but never used        no-unused-vars
  11:7  error  'Kira' is never reassigned. Use 'const' instead  prefer-const

✖ 2 problems (2 errors, 0 warnings)
  1 error and 0 warnings potentially fixable with the `--fix` option.

4.2.3. Behavior

Expected. ESLint returns JavaScript errors in the HTML file.

4.3. Merged configuration

4.3.1. Configuration file

eslint.config.mjs:

import pluginJs from "@eslint/js";
import eslintPluginHtml from "@html-eslint/eslint-plugin";
import htmlParser from "@html-eslint/parser";
import eslintPluginHtmlInlineScripts from "eslint-plugin-html";
import { defineConfig } from "eslint/config";

export default defineConfig([{
		files: ["**/*.{cjs,js,html,mjs}"],
		plugins: {
			eslintPluginHtmlInlineScripts
		},
...

</details>

- Fixes yeonjuan/html-eslint#433

<!-- START COPILOT CODING AGENT TIPS -->
---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our [2 minute survey](https://gh.io/copilot-coding-agent-survey).

Co-authored-by: yeonjuan <41323220+yeonjuan@users.noreply.github.com>

Kristinita · 2025-11-05T14:38:08Z

.cspell.json

    "controlslist",
-    "describedby"
+    "describedby",
+    "eslinthtml",


Type: Suggestion ➕

1. Suggestion

I suggest using file names like eslint-html and eslint-js instead of eslinthtml and eslintjs, respectively.

2. The reason for the suggested changes

File names like eslintjs and eslinthtml are anti-patterns for spell checkers. Spell checkers don’t recognize two different words in eslintjs and eslinthtml, and users need to add eslintjs and eslinthtml to the list of exceptions. On the other hand, good spell checkers like CSpell should recognize two different words in eslint-html, eslint_html, and eslintHtml.

Thanks.

@Kristinita Thanks! I made the following changes

eslinthtml -> eslint-html

eslint-js -> eslint

yeonjuan · 2025-12-13T08:41:24Z

The content does not seem to be an appropriate solution. I will create a separate pull request myself.

codecov · 2025-12-13T13:19:44Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 98.71%. Comparing base (68100e4) to head (cb2c1f3).
⚠️ Report is 3 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #435   +/-   ##
=======================================
  Coverage   98.71%   98.71%           
=======================================
  Files          85       85           
  Lines        2810     2810           
  Branches      772      772           
=======================================
  Hits         2774     2774           
  Misses         36       36

Flag	Coverage Δ
unittest	`98.71% <ø> (ø)`

Flags with carried forward coverage won't be shown. Click here to find out more.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

Initial plan

3134c0d

Copilot AI assigned Copilot and yeonjuan Nov 1, 2025

Copilot started work on behalf of yeonjuan November 1, 2025 16:45 View session

Copilot AI and others added 2 commits November 1, 2025 17:01

Add documentation for using HTML ESLint with other plugins

1f0ca9c

Co-authored-by: yeonjuan <41323220+yeonjuan@users.noreply.github.com>

Fix plugin naming to match official documentation format

ea5c0d6

Co-authored-by: yeonjuan <41323220+yeonjuan@users.noreply.github.com>

Copilot AI changed the title ~~[WIP] Add documentation for configuring HTML ESLint with plugins~~ Add documentation for using HTML ESLint with other HTML-processing plugins Nov 1, 2025

Copilot AI requested a review from yeonjuan November 1, 2025 17:06

Copilot finished work on behalf of yeonjuan November 1, 2025 17:06

Kristinita reviewed Nov 5, 2025

View reviewed changes

Merge branch 'main' into copilot/update-html-eslint-documentation

547da03

yeonjuan changed the title ~~Add documentation for using HTML ESLint with other HTML-processing plugins~~ docs: add docs for using HTML ESLint with other HTML-processing plugins Dec 13, 2025

apply review

3eb59ba

yeonjuan marked this pull request as ready for review December 13, 2025 08:31

Update using-with-other-plugins.md

cb2c1f3

yeonjuan closed this Dec 13, 2025

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

docs: add docs for using HTML ESLint with other HTML-processing plugins #435

docs: add docs for using HTML ESLint with other HTML-processing plugins #435

Uh oh!

Copilot AI commented Nov 1, 2025 •

edited

Loading

Uh oh!

Kristinita Nov 5, 2025

Uh oh!

yeonjuan Dec 13, 2025 •

edited

Loading

Uh oh!

yeonjuan commented Dec 13, 2025

Uh oh!

codecov bot commented Dec 13, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

docs: add docs for using HTML ESLint with other HTML-processing plugins #435

docs: add docs for using HTML ESLint with other HTML-processing plugins #435

Uh oh!

Conversation

Copilot AI commented Nov 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changes

Documentation

Integration

Example Configuration

1. Summary

2. Argumentation of the need of the documentation improvements

3. MCVE

3.1. Installation

3.2. HTML file for testing

4. Configurations

4.1. Solely for HTML ESLint

4.1.1. Configuration file

4.1.2. CLI command

4.1.3. Behavior

4.2. Solely for eslint-plugin-html

4.2.1. Configuration file

4.2.2. CLI command

4.2.3. Behavior

4.3. Merged configuration

4.3.1. Configuration file

Uh oh!

Kristinita Nov 5, 2025

Choose a reason for hiding this comment

1. Suggestion

2. The reason for the suggested changes

Uh oh!

yeonjuan Dec 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

yeonjuan commented Dec 13, 2025

Uh oh!

codecov bot commented Dec 13, 2025

Codecov Report

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Copilot AI commented Nov 1, 2025 •

edited

Loading

yeonjuan Dec 13, 2025 •

edited

Loading