Lint Your JavaScript Code Blocks Right in Markdown

We've all been there—you're writing documentation, a blog post, or maybe even a README with JavaScript examples, and you want to make sure the code actually works. But running ESLint on individual code blocks scattered across markdown files? That's always been a manual process. Until now.

The eslint/markdown project solves this exact problem. It lets you lint JavaScript code blocks within your markdown documents as part of your normal ESLint workflow. No more copy-pasting code into separate files just to check for syntax errors or style issues.

What It Does

This ESLint plugin extends your existing ESLint configuration to parse and lint JavaScript code blocks in markdown files. It automatically detects ```javascript and ```js fenced code blocks, then applies your ESLint rules to the JavaScript code inside them.

Think of it as giving ESLint the ability to peer into your markdown files and focus only on the JavaScript bits that matter.

Why It's Cool

The beauty of this plugin is in its simplicity and integration. It doesn't require you to learn new tools or change your workflow—it just slots right into your existing ESLint setup.

Some standout features:

• Selective linting: Only targets JavaScript code blocks, ignoring all the markdown content around them
• Full ESLint compatibility: Works with all your existing ESLint rules and configurations
• Configurable per block: You can use ESLint directives like // eslint-disable-next-line right within your markdown code examples
• Zero configuration: In many cases, it just works out of the box once you add the plugin

This is particularly useful for documentation-heavy projects, technical blogs, or any codebase where you maintain examples alongside your implementation.

How to Try It

Getting started is straightforward. First, install the plugin:

npm install --save-dev eslint-plugin-markdown

Then update your ESLint configuration (usually in .eslintrc.js or .eslintrc.json):

{
  "plugins": ["markdown"],
  "overrides": [
    {
      "files": ["**/*.md"],
      "processor": "markdown/markdown"
    }
  ]
}

That's it! Now when you run ESLint on your markdown files (or your entire project), it will automatically pick up and lint any JavaScript code blocks.

You can test it by creating a markdown file with a code block that violates your ESLint rules—the plugin should catch it just like regular JavaScript files.

Final Thoughts

As someone who writes a lot of technical documentation, this plugin feels like it's filling a gap I didn't realize was so obvious. It's one of those tools that makes you wonder why it wasn't always part of the ecosystem.

If you're maintaining documentation with code examples, writing technical tutorials, or just want to ensure your README examples are syntactically correct, this is definitely worth adding to your toolchain. It's the kind of quality-of-life improvement that pays off in small but meaningful ways every time you write or update examples.

@githubprojects