rubocop-prose 0.1.0

data/docs/cops/markdown/image_alt_text.md

@@ -0,0 +1,26 @@
+# Markdown/ImageAltText
+
+Requires nonblank alternative text for Markdown images, including reference images and images inside links.
+
+Report-only: add a meaningful description inside the brackets.
+
+## Configuration
+
+```yaml
+Markdown/ImageAltText:
+  Enabled: true
+```
+
+## Example
+
+### Bad
+
+```markdown
+![](/logo.png)
+```
+
+### Good
+
+```markdown
+![Project logo](/logo.png)
+```

data/docs/cops/markdown/image_path_separators.md

@@ -0,0 +1,32 @@
+# Markdown/ImagePathSeparators
+
+Checks local image destinations for backslashes used as path separators. The check applies to inline images and resolved reference-style images; ordinary links and unresolved references are not checked.
+
+The cop corrects clear separators to forward slashes. Backslashes before Markdown-escapable ASCII punctuation, such as the parentheses in `diagram\(v2\).png`, are preserved. Consecutive backslashes before a path component are reported without correction because their intended meaning is ambiguous. External URI destinations are left unchanged.
+
+## Configuration
+
+Enabled by default with no options.
+
+## Example
+
+### Bad
+
+```markdown
+![Diagram](images\diagram.png)
+```
+
+### Good
+
+```markdown
+![Diagram](images/diagram.png)
+
+![Versioned diagram](images/diagram\(v2\).png)
+```
+
+For this configuration:
+
+```yaml
+Markdown/ImagePathSeparators:
+  Enabled: false
+```

data/docs/cops/markdown/link_fragment.md

@@ -0,0 +1,35 @@
+# Markdown/LinkFragment
+
+Checks links beginning with `#` against headings and explicit anchors in the same document. Matching is case-sensitive and decodes entities and percent escapes; `+` stays literal.
+
+`Renderer` selects approximate GitHub, GitLab, or Kramdown heading IDs. GitLab collapses repeated hyphens; Kramdown uses ASCII IDs. Duplicate headings receive numbered suffixes. Explicit heading IDs, HTML `id` attributes, and HTML anchor `name` attributes are accepted.
+
+Report-only. Page-top links are configured independently of [Markdown/EmptyLink](empty_link.md).
+
+## Configuration
+
+```yaml
+Markdown/LinkFragment:
+  Enabled: false
+  Renderer: github # Also supports gitlab and kramdown.
+  AdditionalAnchors: [] # Case-sensitive IDs supplied by the site's renderer or template.
+  AllowEmptyFragment: true # Allow # as a page-top link.
+```
+
+## Example
+
+### Bad
+
+```markdown
+# Installation
+
+[Install](#missing)
+```
+
+### Good
+
+```markdown
+# Installation
+
+[Install](#installation)
+```

data/docs/cops/markdown/link_style.md

@@ -0,0 +1,49 @@
+# Markdown/LinkStyle
+
+Restricts link and image styles independently, including images nested in links.
+
+Use `inline`, `reference`, or individual reference forms: `full_reference`, `collapsed_reference`, and `shortcut_reference`. Links also support `autolink` for angle-bracketed URLs and email addresses. Bare URLs belong to [Markdown/BareUrl](bare_url.md).
+
+Report-only: changing styles may require new labels or definitions.
+
+## Configuration
+
+```yaml
+Markdown/LinkStyle:
+  Enabled: false
+  AllowedLinkStyles: # An empty list prohibits all link syntax.
+    - inline
+    - reference
+    - autolink
+  AllowedImageStyles: # An empty list prohibits all image syntax.
+    - inline
+    - reference
+```
+
+## Example
+
+For this configuration:
+
+```yaml
+Markdown/LinkStyle:
+  Enabled: true
+  AllowedLinkStyles:
+    - reference
+    - autolink
+  AllowedImageStyles:
+    - inline
+```
+
+### Bad
+
+```markdown
+[Read the guide](/guide)
+```
+
+### Good
+
+```markdown
+[Read the guide][docs]
+
+[docs]: /guide
+```

data/docs/cops/markdown/link_text_spacing.md

@@ -0,0 +1,26 @@
+# Markdown/LinkTextSpacing
+
+Trims leading and trailing whitespace from inline and reference link labels without changing their targets. Images and autolinks are not checked.
+
+Whitespace-only labels are report-only because trimming them could change the link syntax.
+
+## Configuration
+
+```yaml
+Markdown/LinkTextSpacing:
+  Enabled: true
+```
+
+## Example
+
+### Bad
+
+```markdown
+[ guide ](/guide)
+```
+
+### Good
+
+```markdown
+[guide](/guide)
+```

data/docs/cops/markdown/list_blank_lines.md

@@ -0,0 +1,31 @@
+# Markdown/ListBlankLines
+
+Adds blank lines around lists, preserving blockquote nesting. Document boundaries and a preceding front-matter header do not require padding.
+
+Nested lists need no separation from their parent items. Continuation text within an item is not content after the list.
+
+## Configuration
+
+```yaml
+Markdown/ListBlankLines:
+  Enabled: true
+```
+
+## Example
+
+### Bad
+
+```markdown
+# Items
+- one
+- two
+```
+
+### Good
+
+```markdown
+# Items
+
+- one
+- two
+```

data/docs/cops/markdown/list_continuation_indentation.md

@@ -0,0 +1,28 @@
+# Markdown/ListContinuationIndentation
+
+Requires continuation lines in parsed list-item paragraphs to align with the item's content column. This checks indentation only; it does not require paragraph reflow or sibling marker alignment.
+
+## Configuration
+
+Enabled by default. This cop reports offenses without autocorrection because changing indentation can alter which Markdown item or block owns the text.
+
+```yaml
+Markdown/ListContinuationIndentation:
+  Enabled: true
+```
+
+## Example
+
+### Bad
+
+```markdown
+- Item text
+continued text.
+```
+
+### Good
+
+```markdown
+- Item text
+  continued text.
+```

data/docs/cops/markdown/list_indentation.md

@@ -0,0 +1,28 @@
+# Markdown/ListIndentation
+
+Requires sibling markers to align with the first item in each ordered or unordered list. Nested lists are checked independently; blockquote prefixes do not count toward indentation.
+
+Indentation counts source characters, not tab stops. Report-only: moving a marker could change which content belongs to the item.
+
+## Configuration
+
+```yaml
+Markdown/ListIndentation:
+  Enabled: true
+```
+
+## Example
+
+### Bad
+
+```markdown
+- one
+ - two
+```
+
+### Good
+
+```markdown
+- one
+- two
+```

data/docs/cops/markdown/list_marker_spacing.md

@@ -0,0 +1,32 @@
+# Markdown/ListMarkerSpacing
+
+Enforces spacing after list markers. A list uses its `Multi` setting if any item spans multiple lines, including nested content; otherwise it uses `Single`. Empty items are ignored.
+
+Autocorrection supports simple one-line items and widths from one to four spaces. Other cases are report-only to preserve item structure.
+
+## Configuration
+
+```yaml
+Markdown/ListMarkerSpacing:
+  Enabled: true
+  UnorderedSingle: 1
+  OrderedSingle: 1
+  UnorderedMulti: 1
+  OrderedMulti: 1
+```
+
+## Example
+
+### Bad
+
+```markdown
+-  one
+-  two
+```
+
+### Good
+
+```markdown
+- one
+- two
+```

data/docs/cops/markdown/ordered_list_numbering.md

@@ -0,0 +1,29 @@
+# Markdown/OrderedListNumbering
+
+Enforces sequential numbering or repeated ones. Sequential numbering starts at each list's first number, including zero; nested and quoted lists are checked independently.
+
+Autocorrection preserves punctuation. Changes in number width are report-only because they can affect continuation indentation.
+
+## Configuration
+
+```yaml
+Markdown/OrderedListNumbering:
+  Enabled: false
+  EnforcedStyle: sequential # Or ones, requiring every marker to be 1.
+```
+
+## Example
+
+### Bad
+
+```markdown
+1. one
+1. two
+```
+
+### Good
+
+```markdown
+1. one
+2. two
+```

data/docs/cops/markdown/outside_spacing.md

@@ -0,0 +1,26 @@
+# Markdown/OutsideSpacing
+
+Reports inline code and emphasis that directly touch a neighboring prose word. It checks Unicode letters and numbers using original character positions and leaves boundaries in scripts commonly written without spaces, such as CJK, unchanged.
+
+The cop reports only and never inserts spaces: source text cannot establish whether adjoining letters form separate words or intentional intraword formatting, and changing adjacency can alter meaning. Such cases are left as written and can be resolved by editing the source or disabling this cop for the relevant files.
+
+## Configuration
+
+```yaml
+Markdown/OutsideSpacing:
+  Enabled: true
+```
+
+## Example
+
+### Bad
+
+```markdown
+Use`command`now; read**important**text.
+```
+
+### Good
+
+```markdown
+Use `command` now; read **important** text.
+```

data/docs/cops/markdown/proper_names.md

@@ -0,0 +1,39 @@
+# Markdown/ProperNames
+
+Corrects configured names to their canonical capitalization in prose, headings, and tables. Matching is case-insensitive, uses whole-word boundaries, and treats punctuation in names literally.
+
+Code is checked only when enabled.
+
+## Configuration
+
+```yaml
+Markdown/ProperNames:
+  Enabled: false
+  Names: [] # Canonical spellings; an empty list disables checks.
+  CodeBlocks: false # Set true to check inline code and code blocks, but never fence info strings.
+```
+
+## Example
+
+For this configuration:
+
+```yaml
+Markdown/ProperNames:
+  Enabled: true
+  Names:
+    - GitHub
+    - Ruby
+    - C++
+```
+
+### Bad
+
+```markdown
+Use github and ruby.
+```
+
+### Good
+
+```markdown
+Use GitHub and Ruby.
+```

data/docs/cops/markdown/raw_html.md

@@ -0,0 +1,27 @@
+# Markdown/RawHtml
+
+Reports HTML elements outside the configured allowlist, including nested elements and table cells. Only opening tags are checked; comments are ignored.
+
+Report-only: removing HTML can discard content or structure.
+
+## Configuration
+
+```yaml
+Markdown/RawHtml:
+  Enabled: false
+  AllowedElements: [] # Case-insensitive element names without angle brackets.
+```
+
+## Example
+
+### Bad
+
+```markdown
+<b>Important</b>
+```
+
+### Good
+
+```markdown
+**Important**
+```

data/docs/cops/markdown/reference_definitions.md

@@ -0,0 +1,36 @@
+# Markdown/ReferenceDefinitions
+
+Reports duplicate reference definitions and, when enabled, unused definitions. All link and image reference forms count as uses; IDs ignore case and repeated whitespace. Footnotes are not checked.
+
+Set `AllowIdenticalDuplicates: true` to repeat definitions near their uses while still reporting conflicts. Destinations are compared after decoding Markdown escapes and HTML entities; titles must also match. The first definition still determines the link target. Unused-definition checking remains independent.
+
+Report-only: removing definitions can change link targets or remove comments.
+
+## Configuration
+
+```yaml
+Markdown/ReferenceDefinitions:
+  Enabled: true
+  CheckUnused: false
+  CheckDuplicates: true
+  AllowIdenticalDuplicates: false
+  IgnoredDefinitions: # Allow conventional comment-like definitions, using normalized IDs.
+    - "//"
+```
+
+## Example
+
+### Bad
+
+```markdown
+[docs]: /guide
+[docs]: /another-guide
+```
+
+### Good
+
+```markdown
+[Read the guide][docs]
+
+[docs]: /guide
+```

data/docs/cops/markdown/reversed_link.md

@@ -0,0 +1,26 @@
+# Markdown/ReversedLink
+
+Reports reversed link syntax such as `(Documentation)[https://example.test]`. Use `[Documentation](https://example.test)` instead. Valid references and single citation-shaped keys such as `(abbrev)[@citekey]` or `(abbrev)[-@citekey]` are left alone. This is a narrow diagnostic exclusion, not full Pandoc or R Markdown citation support.
+
+Report-only: review the intended link before rewriting it.
+
+## Configuration
+
+```yaml
+Markdown/ReversedLink:
+  Enabled: true
+```
+
+## Example
+
+### Bad
+
+```markdown
+(Read the guide)[/guide]
+```
+
+### Good
+
+```markdown
+[Read the guide](/guide)
+```

data/docs/cops/markdown/shell_prompts.md

@@ -0,0 +1,57 @@
+# Markdown/ShellPrompts
+
+Removes leading `$` and `%` prompts followed by a space in shell-language fences by default. Every nonblank line other than a shell comment must start with a configured prompt. Blocks containing output or unprompted continuation lines are left alone; comments, blank lines, and nesting are preserved.
+
+`Prompts` is a positive set of literal markers, not an allowed/forbidden pair. An explicit list replaces the defaults. Markers must be nonempty strings without whitespace; the list must contain at least one marker. Language names are case-sensitive.
+
+`#` is not a default prompt: shell comments are never stripped. When explicitly configured, `#` prompts are reported, but the entire block remains uncorrected because commands cannot reliably be distinguished from comments. The same safeguard applies to any configured marker beginning with `#`. Corrections are also withheld if removing any prompt could expose a closing fence.
+
+## Configuration
+
+```yaml
+Markdown/ShellPrompts:
+  Enabled: true
+  Prompts:
+    - '$'
+    - '%'
+  ShellLanguages: # Case-sensitive fenced language names.
+    - bash
+    - console
+    - ksh
+    - sh
+    - shell
+    - zsh
+```
+
+## Example
+
+### Bad
+
+````markdown
+```sh
+$ echo hello
+% echo hello
+# Keep this shell comment.
+```
+````
+
+### Good
+
+````markdown
+```sh
+echo hello
+echo hello
+# Keep this shell comment.
+```
+````
+
+For this configuration:
+
+```yaml
+Markdown/ShellPrompts:
+  Prompts:
+    - '%'
+    - '#'
+```
+
+Both `% echo hello` and `# echo hello` are reported in shell-language fences. A block containing `# echo hello` or `# Keep this shell comment.` is report-only; neither line is silently rewritten. `$` is no longer recognized as a prompt with this configuration.

data/docs/cops/markdown/single_top_level_heading.md

@@ -0,0 +1,31 @@
+# Markdown/SingleTopLevelHeading
+
+Allows at most one heading at the configured top level. Front-matter titles do not count; use [Markdown/FirstHeading](first_heading.md) for that policy.
+
+Report-only: removing or demoting a heading changes structure.
+
+## Configuration
+
+```yaml
+Markdown/SingleTopLevelHeading:
+  Enabled: false
+  Level: 1
+```
+
+## Example
+
+### Bad
+
+```markdown
+# Guide
+
+# Usage
+```
+
+### Good
+
+```markdown
+# Guide
+
+## Usage
+```

data/docs/cops/markdown/strong_style.md

@@ -0,0 +1,34 @@
+# Markdown/StrongStyle
+
+Enforces `**`, `__`, or consistent strong emphasis. Consistent mode follows the first span; ordinary emphasis belongs to [Markdown/EmphasisStyle](emphasis_style.md).
+
+Autocorrection preserves content. Intraword asterisks are not changed to underscores when that would remove the formatting.
+
+## Configuration
+
+```yaml
+Markdown/StrongStyle:
+  Enabled: true
+  Style: consistent # consistent, asterisk or underscore.
+```
+
+## Example
+
+For this configuration:
+
+```yaml
+Markdown/StrongStyle:
+  Style: underscore
+```
+
+### Bad
+
+```markdown
+This is **important**.
+```
+
+### Good
+
+```markdown
+This is __important__.
+```

data/docs/cops/markdown/structural_line_length.md

@@ -0,0 +1,40 @@
+# Markdown/StructuralLineLength
+
+Reports long heading, code-block, and table source lines without rewriting structural content.
+
+Use [Prose/MaxLength](../prose/max_length.md) for paragraph formatting. Structural limits and paragraph formatting are configured independently.
+
+## Configuration
+
+```yaml
+Markdown/StructuralLineLength:
+  Enabled: false
+  Max: 80 # Positive character count.
+  Headings: true
+  HeadingMax: null # Inherit Max.
+  CodeBlocks: false
+  CodeBlockMax: null # Inherit Max.
+  Tables: false # Includes delimiter rows when enabled.
+```
+
+## Example
+
+For this configuration:
+
+```yaml
+Markdown/StructuralLineLength:
+  Enabled: true
+  Max: 12
+```
+
+### Bad
+
+```markdown
+# A very long heading
+```
+
+### Good
+
+```markdown
+# Short
+```

data/docs/cops/markdown/syntax.md

@@ -0,0 +1,28 @@
+# Markdown/Syntax
+
+Reports Kramdown GFM parsing warnings through RuboCop. Report-only.
+
+Reference warnings are handled by [Markdown/UndefinedReference](undefined_reference.md) and [Markdown/ReferenceDefinitions](reference_definitions.md) when enabled, avoiding duplicate reports.
+
+## Configuration
+
+```yaml
+Markdown/Syntax:
+  Enabled: true
+```
+
+## Example
+
+### Bad
+
+```markdown
+[Read the guide][missing]
+```
+
+### Good
+
+```markdown
+[Read the guide][docs]
+
+[docs]: /guide
+```