first commit
This commit is contained in:
+313
@@ -0,0 +1,313 @@
|
||||
# ESLint Markdown Language Plugin
|
||||
|
||||
[](https://www.npmjs.com/package/@eslint/markdown)
|
||||
[](https://www.npmjs.com/package/@eslint/markdown)
|
||||
[](https://github.com/eslint/markdown/actions)
|
||||
|
||||
Lint Markdown with ESLint, as well JS, JSX, TypeScript, and more inside Markdown.
|
||||
|
||||
<img
|
||||
src="screenshot.png"
|
||||
height="142"
|
||||
width="432"
|
||||
alt="A JS code snippet in a Markdown editor has red squiggly underlines. A tooltip explains the problem."
|
||||
/>
|
||||
|
||||
## Usage
|
||||
|
||||
### Installing
|
||||
|
||||
Install the plugin alongside ESLint v9.15.0 or greater. Type compatibility is guaranteed with ESLint v9.39.0 or greater.
|
||||
|
||||
For Node.js and compatible runtimes:
|
||||
|
||||
```sh
|
||||
npm install @eslint/markdown -D
|
||||
# or
|
||||
yarn add @eslint/markdown -D
|
||||
# or
|
||||
pnpm install @eslint/markdown -D
|
||||
# or
|
||||
bun add @eslint/markdown -D
|
||||
```
|
||||
|
||||
For Deno:
|
||||
|
||||
```sh
|
||||
deno add jsr:@eslint/markdown
|
||||
```
|
||||
|
||||
### Configurations
|
||||
|
||||
| **Configuration Name** | **Description** |
|
||||
| ---------------------- | ---------------------------------------------------------------------------------------------------------- |
|
||||
| `recommended` | Lints all `.md` files with the recommended rules and assumes [CommonMark](https://commonmark.org/) format. |
|
||||
| `processor` | Enables extracting code blocks from all `.md` files so code blocks can be individually linted. |
|
||||
|
||||
In your `eslint.config.js` file, import `@eslint/markdown` and include the recommended config to enable Markdown parsing and linting:
|
||||
|
||||
```js
|
||||
// eslint.config.js
|
||||
import { defineConfig } from "eslint/config";
|
||||
import markdown from "@eslint/markdown";
|
||||
|
||||
export default defineConfig([
|
||||
{
|
||||
files: ["**/*.md"],
|
||||
plugins: {
|
||||
markdown,
|
||||
},
|
||||
extends: ["markdown/recommended"],
|
||||
},
|
||||
// your other configs here
|
||||
]);
|
||||
```
|
||||
|
||||
You can also modify the recommended config by using `extends`:
|
||||
|
||||
```js
|
||||
// eslint.config.js
|
||||
import { defineConfig } from "eslint/config";
|
||||
import markdown from "@eslint/markdown";
|
||||
|
||||
export default defineConfig([
|
||||
{
|
||||
plugins: {
|
||||
markdown,
|
||||
},
|
||||
extends: ["markdown/recommended"],
|
||||
rules: {
|
||||
"markdown/no-html": "error",
|
||||
},
|
||||
},
|
||||
|
||||
// your other configs here
|
||||
]);
|
||||
```
|
||||
|
||||
### Rules
|
||||
|
||||
<!-- NOTE: The following table is autogenerated. Do not manually edit. -->
|
||||
|
||||
<!-- Rule Table Start -->
|
||||
|
||||
| **Rule Name** | **Description** | **Recommended** |
|
||||
| :----------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------ | :-------------: |
|
||||
| [`fenced-code-language`](./docs/rules/fenced-code-language.md) | Require languages for fenced code blocks | yes |
|
||||
| [`fenced-code-meta`](./docs/rules/fenced-code-meta.md) | Require or disallow metadata for fenced code blocks | no |
|
||||
| [`heading-increment`](./docs/rules/heading-increment.md) | Enforce heading levels increment by one | yes |
|
||||
| [`no-bare-urls`](./docs/rules/no-bare-urls.md) | Disallow bare URLs | no |
|
||||
| [`no-duplicate-definitions`](./docs/rules/no-duplicate-definitions.md) | Disallow duplicate definitions | yes |
|
||||
| [`no-duplicate-headings`](./docs/rules/no-duplicate-headings.md) | Disallow duplicate headings in the same document | no |
|
||||
| [`no-empty-definitions`](./docs/rules/no-empty-definitions.md) | Disallow empty definitions | yes |
|
||||
| [`no-empty-images`](./docs/rules/no-empty-images.md) | Disallow empty images | yes |
|
||||
| [`no-empty-links`](./docs/rules/no-empty-links.md) | Disallow empty links | yes |
|
||||
| [`no-html`](./docs/rules/no-html.md) | Disallow HTML tags | no |
|
||||
| [`no-invalid-label-refs`](./docs/rules/no-invalid-label-refs.md) | Disallow invalid label references | yes |
|
||||
| [`no-missing-atx-heading-space`](./docs/rules/no-missing-atx-heading-space.md) | Disallow headings without a space after the hash characters | yes |
|
||||
| [`no-missing-label-refs`](./docs/rules/no-missing-label-refs.md) | Disallow missing label references | yes |
|
||||
| [`no-missing-link-fragments`](./docs/rules/no-missing-link-fragments.md) | Disallow link fragments that do not reference valid headings | yes |
|
||||
| [`no-multiple-h1`](./docs/rules/no-multiple-h1.md) | Disallow multiple H1 headings in the same document | yes |
|
||||
| [`no-reference-like-urls`](./docs/rules/no-reference-like-urls.md) | Disallow URLs that match defined reference identifiers | yes |
|
||||
| [`no-reversed-media-syntax`](./docs/rules/no-reversed-media-syntax.md) | Disallow reversed link and image syntax | yes |
|
||||
| [`no-space-in-emphasis`](./docs/rules/no-space-in-emphasis.md) | Disallow spaces around emphasis markers | yes |
|
||||
| [`no-unused-definitions`](./docs/rules/no-unused-definitions.md) | Disallow unused definitions | yes |
|
||||
| [`require-alt-text`](./docs/rules/require-alt-text.md) | Require alternative text for images | yes |
|
||||
| [`table-column-count`](./docs/rules/table-column-count.md) | Disallow data rows in a GitHub Flavored Markdown table from having more cells than the header row | yes |
|
||||
|
||||
<!-- Rule Table End -->
|
||||
|
||||
**Note:** This plugin does not provide formatting rules. We recommend using a source code formatter such as [Prettier](https://prettier.io) for that purpose.
|
||||
|
||||
In order to individually configure a rule in your `eslint.config.js` file, import `@eslint/markdown` and configure each rule with a prefix:
|
||||
|
||||
```js
|
||||
// eslint.config.js
|
||||
import { defineConfig } from "eslint/config";
|
||||
import markdown from "@eslint/markdown";
|
||||
|
||||
export default defineConfig([
|
||||
{
|
||||
files: ["**/*.md"],
|
||||
plugins: {
|
||||
markdown,
|
||||
},
|
||||
language: "markdown/commonmark",
|
||||
rules: {
|
||||
"markdown/no-html": "error",
|
||||
},
|
||||
},
|
||||
]);
|
||||
```
|
||||
|
||||
You can individually disable rules in Markdown using HTML comments, such as:
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
```markdown
|
||||
<!-- eslint-disable-next-line markdown/no-html -- I want to allow HTML here -->
|
||||
<custom-element>Hello world!</custom-element>
|
||||
|
||||
<!-- eslint-disable markdown/no-html -- here too -->
|
||||
<another-element>Goodbye world!</another-element>
|
||||
<!-- eslint-enable markdown/no-html -- safe to re-enable now -->
|
||||
|
||||
[Object] <!-- eslint-disable-line markdown/no-missing-label-refs -- not meant to be a link ref -->
|
||||
```
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
### Languages
|
||||
|
||||
| **Language Name** | **Description** |
|
||||
| ----------------- | ----------------------------------------------------------------------------- |
|
||||
| `commonmark` | Parse using [CommonMark](https://commonmark.org) Markdown format |
|
||||
| `gfm` | Parse using [GitHub-Flavored Markdown](https://github.github.com/gfm/) format |
|
||||
|
||||
In order to individually configure a language in your `eslint.config.js` file, import `@eslint/markdown` and configure a `language`:
|
||||
|
||||
```js
|
||||
// eslint.config.js
|
||||
import { defineConfig } from "eslint/config";
|
||||
import markdown from "@eslint/markdown";
|
||||
|
||||
export default defineConfig([
|
||||
{
|
||||
files: ["**/*.md"],
|
||||
plugins: {
|
||||
markdown,
|
||||
},
|
||||
language: "markdown/gfm",
|
||||
rules: {
|
||||
"markdown/no-html": "error",
|
||||
},
|
||||
},
|
||||
]);
|
||||
```
|
||||
|
||||
### Language Options
|
||||
|
||||
#### Enabling Front Matter in both `commonmark` and `gfm`
|
||||
|
||||
By default, Markdown parsers do not support [front matter](https://jekyllrb.com/docs/front-matter/). To enable front matter in both `commonmark` and `gfm`, you can use the `frontmatter` option in `languageOptions`.
|
||||
|
||||
> `@eslint/markdown` internally uses [`micromark-extension-frontmatter`](https://github.com/micromark/micromark-extension-frontmatter) and [`mdast-util-frontmatter`](https://github.com/syntax-tree/mdast-util-frontmatter) to parse front matter.
|
||||
|
||||
| **Option Value** | **Description** |
|
||||
| ---------------- | ---------------------------------------------------------- |
|
||||
| `false` | Disables front matter parsing in Markdown files. (Default) |
|
||||
| `"yaml"` | Enables YAML front matter parsing in Markdown files. |
|
||||
| `"toml"` | Enables TOML front matter parsing in Markdown files. |
|
||||
| `"json"` | Enables JSON front matter parsing in Markdown files. |
|
||||
|
||||
```js
|
||||
// eslint.config.js
|
||||
import { defineConfig } from "eslint/config";
|
||||
import markdown from "@eslint/markdown";
|
||||
|
||||
export default defineConfig([
|
||||
{
|
||||
files: ["**/*.md"],
|
||||
plugins: {
|
||||
markdown,
|
||||
},
|
||||
language: "markdown/gfm",
|
||||
languageOptions: {
|
||||
frontmatter: "yaml", // Or pass `"toml"` or `"json"` to enable TOML or JSON front matter parsing.
|
||||
},
|
||||
rules: {
|
||||
"markdown/no-html": "error",
|
||||
},
|
||||
},
|
||||
]);
|
||||
```
|
||||
|
||||
#### Enabling Math (LaTeX) in both `commonmark` and `gfm`
|
||||
|
||||
By default, Markdown parsers do not support [math](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/writing-mathematical-expressions) ([LaTeX](https://www.latex-project.org/)). To enable math in both `commonmark` and `gfm`, you can use the `math` option in `languageOptions`.
|
||||
|
||||
> `@eslint/markdown` internally uses [`micromark-extension-math`](https://github.com/micromark/micromark-extension-math) and [`mdast-util-math`](https://github.com/syntax-tree/mdast-util-math) to parse math.
|
||||
|
||||
| **Option Value** | **Description** |
|
||||
| ---------------- | -------------------------------------------------- |
|
||||
| `false` | Disables math parsing in Markdown files. (Default) |
|
||||
| `true` | Enables math parsing in Markdown files. |
|
||||
|
||||
```js
|
||||
// eslint.config.js
|
||||
import { defineConfig } from "eslint/config";
|
||||
import markdown from "@eslint/markdown";
|
||||
|
||||
export default defineConfig([
|
||||
{
|
||||
files: ["**/*.md"],
|
||||
plugins: {
|
||||
markdown,
|
||||
},
|
||||
language: "markdown/gfm",
|
||||
languageOptions: {
|
||||
math: true, // Or pass `false` to disable math parsing.
|
||||
},
|
||||
rules: {
|
||||
"markdown/no-html": "error",
|
||||
},
|
||||
},
|
||||
]);
|
||||
```
|
||||
|
||||
### Processors
|
||||
|
||||
| **Processor Name** | **Description** |
|
||||
| ------------------------------------------- | ----------------------------------------------------------------------------------- |
|
||||
| [`markdown`](./docs/processors/markdown.md) | Extract fenced code blocks from the Markdown code so they can be linted separately. |
|
||||
|
||||
## Migration from `eslint-plugin-markdown`
|
||||
|
||||
See [Migration](./docs/migration.md#from-eslint-plugin-markdown).
|
||||
|
||||
## Editor Integrations
|
||||
|
||||
### VSCode
|
||||
|
||||
[`vscode-eslint`](https://github.com/microsoft/vscode-eslint) has built-in support for the Markdown processor.
|
||||
|
||||
## File Name Details
|
||||
|
||||
This processor will use file names from blocks if a `filename` meta is present.
|
||||
|
||||
For example, the following block will result in a parsed file name of `src/index.js`:
|
||||
|
||||
````md
|
||||
```js filename="src/index.js"
|
||||
export const value = "Hello, world!";
|
||||
```
|
||||
````
|
||||
|
||||
This can be useful for user configurations that include linting overrides for specific file paths. In this example, you could then target the specific code block in your configuration using `"file-name.md/*src/index.js"`.
|
||||
|
||||
## Contributing
|
||||
|
||||
```sh
|
||||
$ git clone https://github.com/eslint/markdown.git
|
||||
$ cd markdown
|
||||
$ npm install
|
||||
$ npm test
|
||||
```
|
||||
|
||||
This project follows the [ESLint contribution guidelines](https://eslint.org/docs/latest/contribute/).
|
||||
|
||||
<!-- NOTE: This section is autogenerated. Do not manually edit.-->
|
||||
<!--sponsorsstart-->
|
||||
|
||||
## Sponsors
|
||||
|
||||
The following companies, organizations, and individuals support ESLint's ongoing maintenance and development. [Become a Sponsor](https://eslint.org/donate)
|
||||
to get your logo on our READMEs and [website](https://eslint.org/sponsors).
|
||||
|
||||
<h3>Platinum Sponsors</h3>
|
||||
<p><a href="https://automattic.com"><img src="https://images.opencollective.com/automattic/d0ef3e1/logo.png" alt="Automattic" height="128"></a></p><h3>Gold Sponsors</h3>
|
||||
<p><a href="https://qlty.sh/"><img src="https://images.opencollective.com/qltysh/33d157d/logo.png" alt="Qlty Software" height="96"></a> <a href="https://shopify.engineering/"><img src="https://avatars.githubusercontent.com/u/8085" alt="Shopify" height="96"></a> <a href="https://www.coderabbit.ai/?utm_source=cr_org&utm_medium=github"><img src="https://avatars.githubusercontent.com/u/132028505" alt="CodeRabbit" height="96"></a></p><h3>Silver Sponsors</h3>
|
||||
<p><a href="https://vite.dev/"><img src="https://images.opencollective.com/vite/d472863/logo.png" alt="Vite" height="64"></a> <a href="https://liftoff.io/"><img src="https://images.opencollective.com/liftoff/2d6c3b6/logo.png" alt="Liftoff" height="64"></a> <a href="https://stackblitz.com"><img src="https://avatars.githubusercontent.com/u/28635252" alt="StackBlitz" height="64"></a></p><h3>Bronze Sponsors</h3>
|
||||
<p><a href="https://cybozu.co.jp/"><img src="https://images.opencollective.com/cybozu/933e46d/logo.png" alt="Cybozu" height="32"></a> <a href="https://opensource.sap.com"><img src="https://avatars.githubusercontent.com/u/2531208" alt="SAP" height="32"></a> <a href="https://www.crawljobs.com/"><img src="https://images.opencollective.com/crawljobs-poland/fa43a17/logo.png" alt="CrawlJobs" height="32"></a> <a href="https://depot.dev"><img src="https://images.opencollective.com/depot/39125a1/logo.png" alt="Depot" height="32"></a> <a href="https://icons8.com/"><img src="https://images.opencollective.com/icons8/7fa1641/logo.png" alt="Icons8" height="32"></a> <a href="https://discord.com"><img src="https://images.opencollective.com/discordapp/f9645d9/logo.png" alt="Discord" height="32"></a> <a href="https://www.gitbook.com"><img src="https://avatars.githubusercontent.com/u/7111340" alt="GitBook" height="32"></a> <a href="https://citadel.co.jp"><img src="https://avatars.githubusercontent.com/u/75781367" alt="Citadel AI" height="32"></a></p>
|
||||
<h3>Technology Sponsors</h3>
|
||||
Technology sponsors allow us to use their products and services for free as part of a contribution to the open source ecosystem and our work.
|
||||
<p><a href="https://netlify.com"><img src="https://raw.githubusercontent.com/eslint/eslint.org/main/src/assets/images/techsponsors/netlify-icon.svg" alt="Netlify" height="32"></a> <a href="https://algolia.com"><img src="https://raw.githubusercontent.com/eslint/eslint.org/main/src/assets/images/techsponsors/algolia-icon.svg" alt="Algolia" height="32"></a> <a href="https://1password.com"><img src="https://raw.githubusercontent.com/eslint/eslint.org/main/src/assets/images/techsponsors/1password-icon.svg" alt="1Password" height="32"></a></p>
|
||||
<!--sponsorsend-->
|
||||
Reference in New Issue
Block a user