Markdown
An ESLint plugin to lint JavaScript, JSX, TypeScript, and other code blocks within Markdown documents.
What is Markdown?
@eslint/markdown (ESLint Markdown Language Plugin) is an official ESLint plugin that extends ESLint to parse and lint Markdown files. It lints the Markdown structure itself for issues like invalid headings and missing alt text, and also extracts and lints JavaScript, JSX, TypeScript, and other code blocks embedded within the Markdown. It ensures code quality and consistency in documentation, READMEs, and any Markdown content containing executable snippets.
Developers and technical writers who maintain documentation, READMEs, or code repositories with significant Markdown content that includes embedded code examples. It is particularly useful for teams enforcing consistent documentation standards alongside their code quality rules.
Developers choose this plugin because it is the official, first-party ESLint solution for Markdown, ensuring deep integration and reliability. It uniquely combines structural Markdown linting with the ability to apply the full power of ESLint to code blocks within documentation, treating documentation as a first-class citizen in the development workflow.
Overview
Lint JavaScript code blocks in Markdown documents
Use Cases
Best For
- Enforcing consistent style and structure in project documentation and README files.
- Linting JavaScript, JSX, or TypeScript code examples embedded in Markdown documentation to catch syntax errors or style violations.
- Teams using GitHub-Flavored Markdown (GFM) or CommonMark who need to validate table structure, heading hierarchy, and link references.
- Ensuring accessibility in documentation by validating image alt text and link fragments.
- Projects with documentation containing front matter (YAML, TOML, JSON) or mathematical expressions (LaTeX) that need parsing support.
- Integrating documentation linting into an existing ESLint and editor (e.g., VSCode) workflow without needing a separate tool.
Not Ideal For
- Projects requiring automated Markdown formatting and beautification (e.g., line wrapping, list standardization)
- Teams using non-standard or custom Markdown dialects beyond CommonMark and GitHub-Flavored Markdown
- Environments where ESLint is not already part of the build or development workflow
Pros & Cons
Pros
As a first-party plugin from the ESLint team, it ensures deep compatibility with ESLint v9.15.0+ and seamless integration into existing ESLint configurations.
Lints both Markdown structure (e.g., enforcing heading hierarchy with rules like 'heading-increment') and embedded code blocks, applying full ESLint rules to JavaScript, TypeScript, and more.
Supports CommonMark and GitHub-Flavored Markdown, with optional front matter (YAML, TOML, JSON) and math (LaTeX) parsing through configurable language options.
Offers over 20 dedicated rules for Markdown, such as 'require-alt-text' for accessibility and 'table-column-count' for GFM tables, covering common documentation pitfalls.
Cons
The README explicitly states it does not provide formatting rules and recommends Prettier, requiring additional tooling for Markdown beautification.
It cannot function independently; projects must have ESLint configured, adding complexity if Markdown linting is the sole need or if ESLint isn't already in use.
Parsing and linting both Markdown and embedded code blocks can slow down linting in large documentation sets with numerous code snippets, impacting CI/CD pipelines.
Frequently Asked Questions
Found a gem we're missing?
Open-Awesome is built by the community, for the community. Submit a project, suggest an awesome list, or help improve the catalog on GitHub.