rubocop-prose
Markdown and plain-text prose checks for RuboCop.
Use rubocop-md to lint Ruby code inside Markdown.
- Lint Markdown and plain text with native RuboCop configuration and file discovery.
- Wrap or unwrap paragraphs while preserving Markdown syntax and hard breaks.
- Check headings, lists, links, tables, code blocks, and whitespace.
- Validate YAML front matter, require keys, and restrict allowed keys.
- Check reference definitions, local heading fragments, and image alternative text.
- Configure capitalization and proper names, with automatic corrections where supported.
This project was inspired by To Wrap or Not to Wrap in Markdown and borrows many Markdown checks from markdownlint.
Installation
Add to your Gemfile, then run bundle install:
gem 'rubocop-prose', '~> 0.2', require: falseAdd it to .rubocop.yml using RuboCop's plugin interface:
plugins:
- rubocop-proseRuby 3.2 or newer and RuboCop 1.72.1 or newer within 1.x are supported.
See UPGRADING for breaking changes when updating an existing installation.
Usage
Given example.md:
A paragraph split
across two source lines.Run:
bundle exec rubocop example.mdexample.md:2:1: C: [Correctable] Prose/MaxLength: Keep paragraph text on a single source line.
across two source lines.
^^^^^^^^^^^^^^^^^^^^^^^^
Fix it automatically with bundle exec rubocop -a example.md.
Cops
Prose
| Cop | Default | Purpose |
|---|---|---|
| Prose/MaxLength | Enabled | Wrap or unwrap prose paragraphs in Markdown and plain text. |
| Prose/MultipleBlankLines | Enabled | Limit blank lines in prose and quotes, but not code. |
| Prose/SentenceCapitalization | Disabled | Check paragraph openings without changing quoted or code literals. |
| Prose/TrailingNewline | Enabled | Require exactly one final newline. |
Markdown
| Cop | Default | Purpose |
|---|---|---|
| Markdown/AtxHeadingSpace | Enabled | Separate opening ATX heading hashes from text. |
| Markdown/AtxHeadingSpacing | Enabled | Use one space after opening ATX heading hashes. |
| Markdown/BareUrl | Disabled | Require Markdown links or autolinks around bare URLs. |
| Markdown/BlockquoteBlankLines | Enabled | Keep quote markers on blank lines between blockquotes. |
| Markdown/BlockquoteSpacing | Enabled | Use one space after nonempty blockquote markers. |
| Markdown/ClosedHeadingSpace | Enabled | Separate closing ATX heading hashes from text. |
| Markdown/ClosedHeadingSpacing | Enabled | Use one space before closing ATX heading hashes. |
| Markdown/CompactLists | Enabled | Avoid blank lines between simple list items. |
| Markdown/CodeBlockStyle | Disabled | Use fenced, indented, or consistently styled code blocks. |
| Markdown/CodeSpanSpacing | Enabled | Avoid unnecessary padding inside inline code. |
| Markdown/DescriptiveLinkText | Enabled | Require descriptive link text instead of generic labels. |
| Markdown/DuplicateHeadings | Enabled | Avoid duplicate heading text. |
| Markdown/EmphasisHeading | Disabled | Avoid single-line emphasis-only paragraphs in place of headings. |
| Markdown/EmphasisSpacing | Enabled | Remove whitespace immediately inside emphasis delimiters. |
| Markdown/EmphasisStyle | Enabled | Use a configured or consistent emphasis delimiter. |
| Markdown/EmptyLink | Enabled | Require a nonempty link destination. |
| Markdown/FenceBlankLines | Enabled | Surround fenced code blocks with container-aware blank lines. |
| Markdown/FenceLanguage | Enabled | Require a language and optionally restrict fence languages. |
| Markdown/FenceStyle | Enabled | Use backtick, tilde, or consistently styled fences. |
| Markdown/FirstHeading | Disabled | Begin documents with a heading or front-matter title. |
| Markdown/FrontMatterKeys | Disabled | Restrict allowed and require mandatory top-level front matter keys. |
| Markdown/FrontMatterSyntax | Enabled | Report YAML syntax errors in closed leading front matter. |
| Markdown/HardBreakStyle | Enabled | Use backslashes or trailing spaces for paragraph hard breaks. |
| Markdown/HardTabs | Enabled | Report hard tabs with code-block and language exceptions. |
| Markdown/HeadingBlankLines | Enabled | Surround headings with blank lines. |
| Markdown/HeadingCapitalization | Disabled | Enforce initial capitalization or title case in headings. |
| Markdown/HeadingIncrement | Enabled | Increase heading levels without skipping levels. |
| Markdown/HeadingIndentation | Enabled | Avoid leading indentation before headings. |
| Markdown/HeadingPunctuation | Disabled | Avoid configured trailing heading punctuation. |
| Markdown/HeadingStructure | Disabled | Match a configured exact heading outline. |
| Markdown/HeadingStyle | Disabled | Use a consistent heading syntax. |
| Markdown/ImageAltText | Enabled | Require nonblank Markdown image alternative text. |
| Markdown/ImagePathSeparators | Enabled | Use forward slashes in local image destinations. |
| Markdown/KramdownSyntax | Enabled | Report Kramdown GFM parser diagnostics. |
| Markdown/LinkFragment | Disabled | Validate local fragments using configurable heading anchors. |
| Markdown/LinkStyle | Disabled | Configure permitted link and image styles independently. |
| Markdown/LinkTextSpacing | Enabled | Remove leading and trailing whitespace from link text. |
| Markdown/ListBlankLines | Enabled | Surround parsed lists with blank lines. |
| Markdown/ListContinuationIndentation | Enabled | Indent list continuation text to its item's content column. |
| Markdown/ListIndentation | Enabled | Keep sibling list markers consistently indented. |
| Markdown/ListItemCapitalization | Disabled | Enforce consistent initials, initial capitals, or title case in list items. |
| Markdown/ListItemPunctuation | Disabled | Require, forbid, or consistently use terminal punctuation in list items. |
| Markdown/ListMarkerSpacing | Enabled | Configure spaces after ordered and unordered list markers. |
| Markdown/OrderedListNumbering | Disabled | Use sequential numbers or repeated ones in ordered lists. |
| Markdown/OutsideSpacing | Enabled | Report inline formatting directly adjacent to prose words. |
| Markdown/ProperNames | Disabled | Use configured capitalization for proper names outside protected Markdown syntax. |
| Markdown/RawHtml | Disabled | Disallow raw HTML except allowed elements, with optional attribute allowlists. |
| Markdown/ReferenceDefinitions | Enabled | Report duplicate and optionally unused reference definitions. |
| Markdown/ReversedLink | Enabled | Report reversed Markdown link delimiters. |
| Markdown/ShellPrompts | Enabled | Omit configured shell prompts in examples without output. |
| Markdown/SingleTopLevelHeading | Disabled | Allow at most one top-level heading. |
| Markdown/StrongStyle | Enabled | Use a configured or consistent strong delimiter. |
| Markdown/StructuralLineLength | Disabled | Report overlong heading, code-block, and table source lines without reflowing them. |
| Markdown/TableBlankLines | Enabled | Surround Markdown tables with blank lines. |
| Markdown/TableColumns | Enabled | Match table body column counts to the header. |
| Markdown/TablePipes | Enabled | Use consistent leading and trailing table pipes. |
| Markdown/TableSpacing | Enabled | Use configured spacing around table cell content. |
| Markdown/ThematicBreakBlankLines | Enabled | Surround parsed thematic breaks with container-aware blank lines. |
| Markdown/ThematicBreakStyle | Enabled | Use a configured or consistent thematic break. |
| Markdown/TrailingWhitespace | Enabled | Remove trailing whitespace while retaining Markdown hard breaks. |
| Markdown/UnclosedFencedCodeBlock | Enabled | Require an explicit closing fence for fenced code blocks. |
| Markdown/UndefinedReference | Enabled | Require definitions for link and image references. |
| Markdown/UnorderedListIndentation | Enabled | Use a configured indentation width for unordered lists. |
| Markdown/UnorderedListMarker | Enabled | Use a configured or consistent unordered list marker. |
Settings
| Setting | Purpose |
|---|---|
| Markdown/Include | Select files parsed as Markdown using native RuboCop file patterns. |
| Markdown/IgnoreFrontMatter | Ignore closed leading metadata during Markdown inspection. |
Text
| Cop | Default | Purpose |
|---|---|---|
| Text/HardTabs | Enabled | Report tabs on every plain-text line without correction. |
| Text/ProperNames | Disabled | Use configured capitalization for proper names in literal text. |
| Text/TrailingWhitespace | Enabled | Remove all trailing spaces and tabs from plain-text lines. |
Settings
| Setting | Purpose |
|---|---|
| Text/Include | Select files parsed as literal text using native RuboCop file patterns. |
Project Documentation
See CONTRIBUTING for development, testing, and artwork maintenance, DESIGN for architecture and design decisions, and AGENTS for contributor instructions for coding agents.
License
Released under the MIT license.