Skip to content

Update rumdl to 0.3.3 and drop the MyST target workarounds #1390

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
laughingman7743 wants to merge 4 commits into
base: master
Choose a base branch
from
+8 −10
Open

Update rumdl to 0.3.3 and drop the MyST target workarounds #1390

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
7b96b70
Update rumdl to 0.3.3 and drop the MyST target workarounds
laughingman7743 Nov 11, 2026
dd79c0f
Match markdownlint's MD041 front matter title matching
laughingman7743 Nov 11, 2026
dffac0d
Narrow the MD041 preamble note to inline images and badges
laughingman7743 Nov 11, 2026
5b33d71
Do not overstate the MD041 preamble note
laughingman7743 Nov 11, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .mise.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,4 +10,4 @@ python = "3.12"
just = "latest"
shellcheck = "0.11.0"
actionlint = "1.7.12"
rumdl = "0.3.2"
rumdl = "0.3.3"

@laughingman7743 laughingman7743 Nov 11, 2026

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Self-review round one (behavior and implementation) — CLEAN

Base edfafcf59d4382c9af6d2111816ac1209c46dba7, head 7b96b703800d50bf37ba754d8c55dec28336101e.
Covered: .mise.toml pin, .rumdl.toml enable list and comments, the three removed disable comments in docs/index.md, docs/polars.md, docs/sqlalchemy.md.

  • CI installs rumdl through jdx/mise-action from .mise.toml (.github/workflows/docs-lint.yaml:28,37), and the workflow path filter includes .mise.toml, so CI runs the bumped version.
  • With 0.3.3, rumdl check reports no issues in 30 files; 0.3.2 on the same tree reports the 3 MD044 target issues, so the removed comments were the only suppression needed.
  • MD041 is active under this config (a root-level canary starting with prose is flagged) and reports nothing on 0.3.3, versus 16 docs/*.md hits on 0.3.2.
  • No remaining rumdl-disable comments or references to MyST flavor: targets ((label)=) are checked as text (MD044, MD041) rvben/rumdl#983 in the tree.
  • Sphinx build (-E) shows no new warnings; removing HTML comments before the (label)= targets does not change rendering.

13 changes: 7 additions & 6 deletions .rumdl.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,14 +25,12 @@ enable = [
"MD012", "MD018", "MD019", "MD020", "MD021", "MD022", "MD023", "MD024",
"MD025", "MD026", "MD027", "MD028", "MD029", "MD030", "MD031", "MD032",
"MD033", "MD034", "MD035", "MD036", "MD037", "MD038", "MD039", "MD040",
"MD042", "MD044", "MD045", "MD046", "MD047", "MD048", "MD049",
"MD041", "MD042", "MD044", "MD045", "MD046", "MD047", "MD048", "MD049",

@laughingman7743 laughingman7743 Nov 11, 2026

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Self-review round two (claims and compatibility) — CLEAN

Base edfafcf59d4382c9af6d2111816ac1209c46dba7, head 7b96b703800d50bf37ba754d8c55dec28336101e.
Claims checked:

@laughingman7743 laughingman7743 Nov 11, 2026

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Independent review (relayed) — FINDINGS

Reviewer: Codex CLI 0.166.0 (gpt-6-astra), codex exec -s read-only, session 01a1caa6-61e1-7902-85c2-f59e0e253645. Static review plus read-only rumdl check / stdin probes on a detached snapshot; no PR description or author conclusions supplied.
Base edfafcf59d4382c9af6d2111816ac1209c46dba7, head 7b96b703800d50bf37ba754d8c55dec28336101e.
Covered: exact diff, mise/CI/just wiring, configured file sets, rule inventory, MyST labels, MD044 enforcement, MD041 behavior and skill front matter, 0.3.2→0.3.3 defaults. Cache-disabled lint passes all 30 files; all 49 intended rules are active (omissions only MD013, MD014, MD043); no other changed defaults need pins.

  1. P2 .rumdl.toml:28 — MD041 permits image preambles outside MyST: README.md with only ![Logo](logo.png), or an image followed by # Title, passes; markdownlint 0.38 reports both. rumdl skips image/badge lines even with allow-preamble = false. Keep a strict check or record the compatibility exception.
  2. P2 .rumdl.toml:28 — front matter title matching: ---\nTitle: Example\n---\n\n## Section is reported by rumdl but accepted by markdownlint 0.38 (case-insensitive). Set MD041.front-matter-title-pattern = '(?i)^\s*"?title"?\s*[:=]'.

Author verification: both reproduced with stdin probes and confirmed against markdownlint 0.38.0 lib/md041.mjs (non-heading content errors when allow_preamble is false) and helpers.cjs frontMatterHasTitle (new RegExp(..., "i")). rumdl flags <div>, <img>, and image-plus-text lines; only image/badge-only lines are skipped, with no option to disable that.

@laughingman7743 laughingman7743 Nov 11, 2026

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Repaired in dd79c0f.

  1. Accepted as a recorded compatibility exception: rumdl 0.3.3 has no option to stop skipping image/badge-only lines, and no linted file relies on it (README.md starts with # PyAthena after its license comment). .rumdl.toml now states the difference next to the MD041 options. Before this PR MD041 was off entirely, so every other preamble markdownlint reports is now caught.
  2. Fixed: [MD041] front-matter-title-pattern = '(?i)^\s*"?title"?\s*[:=]'. Probes: Title:, title:, "title":, TITLE = accepted; name: and subtitle: without an H1 reported.

Self-review of the repair (behavior and claims): rumdl check --no-cache clean on 30 files, just docs lint and just lint pass; the new comment's claims are the probe results above. MD025 has the same case-sensitive title lookup but no pattern option in rumdl 0.3.3 (Unknown option for rule MD025: front-matter-title-pattern); that is the MD025 difference already accepted in #1360 and stays out of scope.

@laughingman7743 laughingman7743 Nov 11, 2026

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Independent follow-up (relayed) — Codex CLI 0.166.0 (gpt-6-astra), codex exec -s read-only, session 01a1caae-98c7-7941-b3f5-be2fef59a297; range-diff edfafcf59d4382c9af6d2111816ac1209c46dba7..7b96b703800d50bf37ba754d8c55dec28336101e → edfafcf59d4382c9af6d2111816ac1209c46dba7..dd79c0f9eedac6a16e2ba6d914c721c83bb7de27. Result: FINDINGS.

Finding 2 resolved: YAML/TOML/JSON title cases match markdownlint 0.38 without over-acceptance. Finding 1's exception is accurate (no rumdl 0.3.3 option; allow-preamble = false still permits them).
P3 .rumdl.toml:76: "always lets Markdown images and badges precede" is too broad — reference-style images (![Logo][logo]) and badges still trigger MD041.

Verified (reference image and reference-link badge reported; inline image and inline-linked badge pass) and repaired in dffac0d: the note now says "lines of only inline images or inline-linked badges"; PR body updated to match. just docs lint passes. Comment-only repair; round-one/two check: the narrowed claim equals the probe results, no behavior change.

@laughingman7743 laughingman7743 Nov 11, 2026

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Independent follow-ups (relayed)

  • Codex session 01a1cab6-dd4d-7343-9b03-b08e220f3e2e on dffac0d: FINDINGS P3 — "always" is still too broad; ![Logo](logo(1).svg) before # Title is reported. Verified locally and repaired in 5b33d71 ("always lets" → "can let"; PR body updated). Comment-only; just docs lint passes.
  • Codex session 01a1cab9-6bbe-7383-a9eb-cf4110dd4c6a on 5b33d71: CLEAN — simple inline images and linked badges pass MD041 even with allow-preamble = false, the parenthesized URL case is reported, and "can let" captures this.

Independent review complete for head 5b33d71 (static review with read-only rumdl probes).

"MD050", "MD051", "MD052", "MD053", "MD054", "MD055", "MD056", "MD058",
"MD059",
# Not enabled:
# MD013: docs have long URLs and code lines that would be awkward to wrap
# MD014: `$ command` style is intentional in docs/testing.md and README shell snippets
# MD041: MyST `(label)=` ref targets must come before the first heading, so the
# first line of many docs/*.md files is not an H1
# MD043: the docs share no single heading structure to require
]

Expand Down Expand Up @@ -74,6 +72,12 @@ list-items = true
[MD036]
punctuation = ".,;:!?。，；：！？"

# markdownlint matches a front matter title key case-insensitively. Unlike
# markdownlint, rumdl can let lines of only inline images or inline-linked
# badges precede the first heading; it has no option to disallow them.
[MD041]
front-matter-title-pattern = '(?i)^\s*"?title"?\s*[:=]'

[MD051]
ignore-case = false

Expand All @@ -84,9 +88,6 @@ ignore = ["x"]
ignored-definitions = ["//"]

# Spell project and library names consistently in prose; code is exempt.
# rumdl also checks MyST `(label)=` targets, so the labels that contain one of
# these names disable MD044 for their line; remove those comments once the
# pinned rumdl skips targets (https://github.com/rvben/rumdl/issues/983).
[MD044]
names = ["PyAthena", "Athena", "SQLAlchemy", "fsspec", "Polars", "PyArrow", "pandas"]
code-blocks = false
Expand Down
1 change: 0 additions & 1 deletion docs/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,6 @@ See LICENSE or https://opensource.org/licenses/MIT.
SPDX-License-Identifier: MIT
-->

<!-- rumdl-disable-next-line MD044 -->
(pyathena)=

![PyAthena](_static/header.png)
Expand Down
1 change: 0 additions & 1 deletion docs/polars.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,3 @@
<!-- rumdl-disable-next-line MD044 -->
(polars)=

# Polars
Expand Down
1 change: 0 additions & 1 deletion docs/sqlalchemy.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,3 @@
<!-- rumdl-disable-next-line MD044 -->
(sqlalchemy)=

# SQLAlchemy
Expand Down
Loading