Skip to content

build: add prettier to update-rules-docs script #510

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 5 commits into from
Aug 24, 2025
Merged

build: add prettier to update-rules-docs script #510

Show file tree
Hide file tree
Changes from 3 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
4474305
build: add `prettier` to `update-rules-docs` script
lumirlumir Aug 21, 2025
30f6aff
wip
lumirlumir Aug 21, 2025
5703b0e
wip
lumirlumir Aug 21, 2025
3a1fedc
Merge branch 'main' of https://github.com/eslint/markdown into build-…
lumirlumir Aug 23, 2025
ba96590
wip: add prettier-ignore
lumirlumir Aug 23, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .prettierignore
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,3 +2,4 @@ dist
CHANGELOG.md
jsr.json
**/*.md
!/README.md
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actually, looking at the JSON and CSS plugins, all of their Markdown files are formatted with Prettier.

I'd like to ask how the team would feel about formatting all Markdown files in this repo with Prettier. (If that's out of scope for this PR, I'm happy to open a separate issue.)

The Markdown repository includes code-block linting examples, so if the main concern is those examples, not adding Prettier here seems reasonable to me.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In theory it shouldn't matter as we should be able to properly lint the Markdown files even after they're formatted. I'd say try formatting them all and then linting. If there aren't any errors (or any errors that aren't easily fixable), then we can move forward with formatting all the .md files.

Copy link
Member Author

@lumirlumir lumirlumir Aug 23, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you for taking a look.

I tried it, but Prettier is more opinionated with Markdown formatting than I expected. (It changes some of the rule examples that we intentionally included.) So, I think it's fine to just format the root-level README.md file as it is now.

167 changes: 86 additions & 81 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ Lint Markdown with ESLint, as well JS, JSX, TypeScript, and more inside Markdown

### Installing

Install the plugin alongside ESLint v9 or greater.
Install the plugin alongside ESLint v9 or greater.

For Node.js and compatible runtimes:

Expand All @@ -39,10 +39,10 @@ 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. |
| **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:

Expand All @@ -52,9 +52,9 @@ import { defineConfig } from "eslint/config";
import markdown from "@eslint/markdown";

export default defineConfig([
markdown.configs.recommended
markdown.configs.recommended,

// your other configs here
// your other configs here
]);
```

Expand All @@ -66,17 +66,17 @@ 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
{
plugins: {
markdown,
},
extends: ["markdown/recommended"],
rules: {
"markdown/no-html": "error",
},
},

// your other configs here
]);
```

Expand All @@ -85,27 +85,29 @@ export default defineConfig([
<!-- 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 |
| [`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-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 Name** | **Description** | **Recommended** |
| :----------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------ | :-------------: |
| [`fenced-code-language`](./docs/rules/fenced-code-language.md) | Require languages for fenced code blocks | yes |
| [`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-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.
Expand All @@ -118,38 +120,41 @@ 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"
}
}
{
files: ["**/*.md"],
plugins: {
markdown,
},
language: "markdown/commonmark",
rules: {
"markdown/no-html": "error",
},
},
]);
```

You can individually disable rules in Markdown using HTML comments, such as:

```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 -->
```

### 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 |
| **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`:

Expand All @@ -159,29 +164,29 @@ 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"
}
}
{
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`.
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. |
Expand All @@ -193,27 +198,27 @@ 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"
}
}
{
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",
},
},
]);
```

### Processors

| **Processor Name** | **Description** |
|---------------|-----------------|
| [`markdown`](./docs/processors/markdown.md) | Extract fenced code blocks from the Markdown code so they can be linted separately. |
| **Processor Name** | **Description** |
| ------------------------------------------- | ----------------------------------------------------------------------------------- |
| [`markdown`](./docs/processors/markdown.md) | Extract fenced code blocks from the Markdown code so they can be linted separately. |

## Editor Integrations

Expand Down
13 changes: 12 additions & 1 deletion tools/update-rules-docs.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,7 @@
import { fromMarkdown } from "mdast-util-from-markdown";
import fs from "node:fs/promises";
import path from "node:path";
import prettier from "prettier";

//-----------------------------------------------------------------------------
// Type Definitions
Expand Down Expand Up @@ -99,4 +100,14 @@ const tableText = await createRulesTableText();

docsText = `${docsText.slice(0, rulesTableRange[0])}\n${tableText}\n${docsText.slice(rulesTableRange[1])}`;

await fs.writeFile(docsFileURL, docsText);
// load prettier config
const prettierConfig = await prettier.resolveConfig(docsFileURL);

// format and write the file
await fs.writeFile(
docsFileURL,
await prettier.format(docsText, {
filepath: docsFileURL.pathname,
...prettierConfig,
}),
);
Loading