MDX and AsciiDoc Linting: Beyond Standard Markdown

Standard markdown serves many documentation needs well, but modern documentation workflows often demand more sophisticated formats. MDX combines markdown with React components for interactive documentation. AsciiDoc provides advanced features for technical manuals and books. HTML and plain text also need reliable style checking. Each format has specialized syntax that standard grammar checkers don't understand.

When you paste MDX with JSX components into a typical grammar checker, it flags the component syntax as errors. AsciiDoc's powerful include directives, admonitions, and block structures confuse tools designed for simple prose. You need linting that understands these formats natively—checking the prose content while respecting the specialized syntax.

ProseLint Web provides native support for advanced documentation formats, bringing professional style guide enforcement to MDX, AsciiDoc, HTML, plain text, and Markdown.

Why advanced formats need specialized linting

Technical documentation has evolved beyond basic markdown:

Modern documentation is interactive

Static markdown pages are being replaced by interactive documentation:

MDX brings components to markdown: Documentation frameworks like Docusaurus, Nextra, and Gatsby use MDX to embed React components directly in markdown content. You can include interactive code playgrounds, live API demos, and dynamic examples.

Linting must understand JSX syntax: A linter that treats <CodeBlock> as prose will flag it as an error. Proper MDX linting parses JSX components, extracts markdown content, and lints only the prose portions.

Component properties need exclusion: Linters shouldn't check code within component props. ProseLint Web distinguishes between markdown prose and JSX code.

Technical documentation needs advanced features

Complex documentation requires formats beyond markdown's capabilities:

AsciiDoc for comprehensive technical writing: AsciiDoc supports cross-references, bibliographies, indexes, conditional content, and sophisticated table structures. Technical manuals, user guides, and book-length documentation benefit from these features.

HTML for published docs: Many teams author directly in HTML for docs portals and static sites. Linting should extract prose from markup without breaking structure.

Plain text for lightweight workflows: Notes, release checklists, and internal docs are often plain text. Those files still need consistent style and clarity.

Standard markdown tools can't lint these formats effectively because they don't parse the specialized syntax correctly.

Format-aware linting prevents false positives

When linters don't understand format syntax:

Code blocks flagged as prose: Linters that don't parse code fences try to apply grammar rules to code examples, creating nonsense warnings

Markup treated as typos: AsciiDoc directives like include:: or HTML tag names get flagged as spelling errors

Component names become grammar errors: MDX components like <Callout> trigger capitalization rules designed for prose

Escape sequences confuse analysis: Format-specific escapes and special characters create false positives

Format-aware linting solves this by parsing the document structure first, then applying prose rules only to actual content.

How ProseLint Web handles advanced formats

ProseLint Web uses format-specific processors to handle complex documentation:

MDX processing pipeline

When you lint MDX content in ProseLint Web:

MDX parsing: Content parses using mdx2vast (MDX to Virtual AST) to identify markdown vs. JSX portions
Component extraction: JSX components, imports, and expressions are identified and excluded from prose checking
Markdown extraction: Pure markdown prose extracts for linting
Vale linting: Prose content lints using your selected style guide package
Position mapping: Issues map back to original MDX source with correct line numbers

This ensures Vale checks your writing without flagging <Alert type="warning"> as a grammar error.

MDX features supported:

JSX component syntax (<ComponentName>)
Import/export statements
JavaScript expressions in curly braces {variable}
Markdown frontmatter (YAML)
Standard markdown within MDX

AsciiDoc processing pipeline

AsciiDoc linting uses Asciidoctor to parse complex structures:

AsciiDoc parsing: Content processes through Asciidoctor to generate structured output
HTML conversion: AsciiDoc converts to HTML, preserving structure
Prose extraction: Text content extracts while respecting blocks, attributes, and directives
Vale linting: Extracted prose checks against style guides
Source mapping: Issues map to original AsciiDoc line numbers

This approach handles AsciiDoc's rich feature set:

Block structures:

Literal blocks, listing blocks, example blocks
Sidebar, quote, and verse blocks
Admonitions (NOTE, TIP, IMPORTANT, WARNING, CAUTION)
Open blocks and passthrough blocks

Inline formatting:

Bold, italic, monospace, and custom styles
Cross-references and inter-document links
Attributes and attribute references
Inline macros

Advanced features:

Include directives
Conditional content (ifdef, ifndef)
Tables with cell spanning and formatting
Bibliographies and footnotes

ProseLint Web lints the prose while respecting all these structural elements.

Other supported formats

Beyond MDX and AsciiDoc:

HTML: Vale extracts text content from HTML tags, respecting semantic structure and ignoring code in <script> and <style> tags

Markdown: Native markdown linting with syntax-aware prose extraction

Plain text: Direct linting of unformatted text files

Practical MDX linting workflows

Here's how to lint MDX effectively:

Component library documentation

Documentation for React component libraries typically uses MDX:

Example MDX content:

---
title: Button Component
---

import { Button } from '@/components/Button'
import { CodeBlock } from '@/components/CodeBlock'

# Button Component

The `Button` component provides a accessible, customizable button element.

<CodeBlock language="jsx">
  <Button variant="primary">Click me</Button>
</CodeBlock>

## Props

- `variant`: Visual style (`primary`, `secondary`, `danger`)
- `size`: Button size (`small`, `medium`, `large`)
- `disabled`: Disables user interaction

<Alert type="warning">
  Always provide accessible labels for icon-only buttons.
</Alert>

Linting this in ProseLint Web:

Paste entire MDX into the editor (or upload .mdx file)
Select your style guide (Google Developer Documentation for component docs)
Lint: Vale checks prose portions only:
- Heading text ("Button Component")
- Description paragraphs
- Prop descriptions
- Alert content
JSX ignored: Components, imports, and code blocks don't generate false positives
Apply fixes: Address style issues in prose while keeping MDX syntax intact

Next.js and Docusaurus documentation

Modern documentation frameworks use MDX extensively:

Workflow:

Draft documentation in MDX with embedded components
Lint locally before committing using ProseLint Web
Fix prose issues while preserving interactive elements
Commit clean MDX with both working components and polished prose

Common patterns Vale handles correctly:

Frontmatter metadata (title, description, tags)
Import statements for components
Inline component usage within paragraphs
Code blocks with syntax highlighting
Component composition and nesting

Practical AsciiDoc linting workflows

AsciiDoc workflows benefit from format-aware linting:

Technical manual authoring

Enterprise technical documentation often uses AsciiDoc:

Example AsciiDoc content:

= Installation Guide
:toc: left
:icons: font

== Prerequisites

Before installing the software, ensure your system meets these requirements:

* Operating System: Linux (Ubuntu 20.04 or later)
* Memory: 8 GB RAM minimum
* Disk Space: 50 GB available

[NOTE]
====
For production deployments, we recommend 16 GB RAM and SSD storage.
====

== Installation Steps

. Download the installation package:
+
[source,bash]
----
wget https://example.com/installer.tar.gz
----

. Extract the archive:
+
[source,bash]
----
tar -xzf installer.tar.gz
----

. Run the installer:
+
[source,bash]
----
./install.sh
----

[IMPORTANT]
====
The installer requires root privileges. Use `sudo` if necessary.
====

Linting in ProseLint Web:

Paste or upload AsciiDoc content
Select appropriate style guide (Red Hat for enterprise technical docs)
Vale extracts prose:
- Heading text
- Prerequisite descriptions
- Step instructions
- Admonition content
Syntax preserved:
- Block delimiters (====)
- Attributes (:toc:, :icons:)
- Source code blocks
- Inline formatting

Book and long-form documentation

AsciiDoc excels at book-length content:

Features Vale handles:

Chapter and section organization
Cross-references between sections
Include directives for content reuse
Index entries and glossary terms
Bibliographic references
Conditional content for multi-version docs

Workflow:

Lint individual chapters as AsciiDoc files
Check cross-referenced content for consistency
Verify terminology across included files
Apply style guide (Microsoft, Red Hat, custom) consistently

Format-specific linting best practices

Different formats have different linting considerations:

For MDX content

Separate content from code: Keep prose paragraphs separate from code examples where possible for clearer linting results

Lint component content: Remember to check prose within component bodies (like alert messages, callouts)

Test after fixes: After applying Vale suggestions to MDX, verify components still render correctly

Version control friendly: Format-aware linting means you can apply prose fixes without touching component code, creating cleaner diffs

For AsciiDoc content

Respect block boundaries: When fixing issues inside admonitions or examples, maintain block delimiters exactly

Check included files separately: If your AsciiDoc uses include:: directives, lint included files independently for complete coverage

Attribute references: Be cautious when linting content with attribute references—Vale sees the rendered text, not the attribute name

Table content: Complex AsciiDoc tables may need manual review for formatting after prose fixes

For HTML content

Semantic HTML helps: Vale extracts prose better from semantic HTML (<p>, <h1>-<h6>, <article>) than generic <div> soup

Check alt text: Image alt attributes are prose content that should follow style guides—ProseLint Web checks these

Skip generated HTML: Auto-generated HTML from build tools may have style issues in generated parts—focus linting on source content instead

Comparing format support across tools

Most linting tools struggle with advanced formats:

Standard grammar checkers (Grammarly, ProWritingAid)

Format support: Basic markdown at best, often just plain text MDX handling: Completely broken—flags JSX as errors AsciiDoc handling: Not supported Result: Unusable for modern documentation workflows

Vale CLI (command-line tool)

Format support: Excellent—native parsing for Markdown, MDX, HTML, AsciiDoc, and plain text MDX handling: Supported with correct parsing AsciiDoc handling: Full support via Asciidoctor integration Result: Industry-standard for multi-format linting, but requires local installation

ProseLint Web (browser-based)

Format support: Comprehensive—Markdown, MDX, AsciiDoc, HTML, and plain text MDX handling: Full parsing with component-aware linting AsciiDoc handling: Native support via WebAssembly Asciidoctor Result: Same format support as Vale CLI, but zero installation required

Migration strategies for advanced formats

If you're currently struggling with format-incompatible linters:

From basic markdown to MDX

When adopting MDX for interactive documentation:

Start linting MDX early: Don't wait until you have complex component composition—lint simple MDX from the start
Verify component handling: Test that your linting tool correctly ignores JSX before committing to MDX workflows
Standardize on style guide: Choose Microsoft or Google developer guides for consistency
Integrate with CI: Use Vale CLI in continuous integration to catch MDX prose issues automatically

From markdown to AsciiDoc

When moving to AsciiDoc for advanced features:

Lint existing markdown: Clean up prose quality before migration using Vale with your chosen style guide
Migrate with linting: As you convert markdown to AsciiDoc, re-lint to ensure quality carries over
Leverage AsciiDoc features: Use admonitions, includes, and advanced structures—Vale handles all of them
Maintain consistency: Keep using the same style guide (Microsoft, Red Hat, etc.) before and after migration

Supporting multiple formats

Many documentation projects use different formats for different purposes:

MDX for web documentation: Interactive docs sites with components
AsciiDoc for manuals: Comprehensive technical guides and books
Markdown for README files: Simple project documentation

Unified linting approach:

Use ProseLint Web for quick checks across all formats
Use Vale CLI in CI to enforce style regardless of format
Maintain single style guide configuration for consistency

Advanced format features coming soon

Future enhancements may include:

Enhanced MDX support: TypeScript types in MDX, MDX v3 features, custom component definitions

Extended AsciiDoc: Diagram syntax (PlantUML, Mermaid), bibliography management, multi-document projects

HTML improvements: Better handling for complex semantic structures and embedded content

Jupyter Notebooks: Lint markdown cells in .ipynb files for data science documentation

Conclusion: format flexibility without quality compromise

Modern documentation workflows use sophisticated formats that standard grammar checkers don't understand. You shouldn't have to choose between advanced formatting features and writing quality checks.

ProseLint Web brings professional linting to MDX, AsciiDoc, HTML, plain text, and Markdown. Whether you're building interactive React documentation, writing enterprise technical manuals, or maintaining product docs, you get format-aware linting that respects specialized syntax while enforcing style guides on prose content.

Try ProseLint Web with your MDX or AsciiDoc content and experience linting that understands modern documentation formats.

Resources

ProseLint Web editor — multi-format linting for Markdown, MDX, AsciiDoc, HTML, and plain text
Vale CLI — command-line linting with comprehensive format support
MDX documentation — learn MDX for interactive documentation
AsciiDoc specification — comprehensive AsciiDoc reference
Asciidoctor — AsciiDoc processing toolchain