Skip to content

Conversation

@bbatsov
Copy link
Contributor

@bbatsov bbatsov commented Feb 10, 2026

I promised a while back that I'd take care of the remaining lint issues across the site, and here it is — this PR brings us from 938 markdownlint errors down to 0.

Most of the errors (840) were MD013 (line-length), which I've simply disabled — enforcing a line length limit on content-heavy markdown files creates more churn than value. I also disabled MD001 (heading-increment), since our Jekyll layouts provide the h1 and content pages intentionally start at h2/h3.

On the config side I also standardized on atx headings (no closing #) and fenced code blocks (instead of indented), which are the modern defaults most people expect.

The actual content fixes across ~15 files are all minor and non-breaking:

  • Escaped trailing # in headings — headings ending in F# were misdetected as atx_closed style (e.g. ### Low risk ways to use F#### Low risk ways to use F\#)
  • Converted indented code blocks to fenced in the install guides and README
  • Normalized list marker spacing (1. 1. ) in the install guides
  • Added missing alt text to a handful of <img> tags
  • Replaced generic link text like [here] and [(link)] with something descriptive (e.g. [on GitHub], [entire analysis])
  • A few other small things: trailing whitespace, a missing final newline, emphasis used as a heading, and a couple of broken link fragments in teaching/research.md

The linter now reports 0 errors across all 150 markdown files:

markdownlint-cli2 v0.20.0 (markdownlint v0.40.0)
Linting: 150 file(s)
Summary: 0 error(s)

Update the linter config to disable line-length (MD013) and
heading-increment (MD001), and standardize on atx headings and
fenced code blocks.

Fix the remaining content issues in ~15 files: escape trailing #
in headings so they aren't misdetected as atx_closed, convert
indented code blocks to fenced, normalize list marker spacing,
add missing image alt text, replace generic link text like
"[here]" and "[(link)]" with descriptive alternatives, and a
handful of other small cleanups (trailing whitespace, missing
final newline, emphasis-as-heading).

The linter now reports 0 errors across all 150 markdown files.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant