Closed mdbmes closed 1 day ago
The pre-commit lint was working earlier but it just started failing due to an external link timeout. (Internet Archive is still having trouble) The error can be ignored for now.
The remaining pre-commit failure is an mdformat difference due to changes in master since this PR's branch point. I'll either need to rebase this PR or fix that in a followup change.
The remaining pre-commit failure is an mdformat difference due to changes in master since this PR's branch point. I'll either need to rebase this PR or fix that in a followup change.
Never mind, I didn't realize we could just merge from main back to this branch and let squash-and-merge eat the extra commit.
This patch intends to make specs more readable when rendered by the included mkdocs build system, such as when they're displayed on https://specifications.readthedocs.io
The main issue behind DRIVERS-3010 is that various Markdown implementations disagree about how much indentation is necessary for items within a list. The original Markdown spec requires 4 spaces, and mkdocs is strict about this. Other implementations, like GitHub flavored markdown, allow 2 or 3 spaces.
The main fix is to begin using the
mdformat-mkdocs
plugin for mdformat, which automatically adjusts this indentation.Existing documents have been reformatted with an override that allows the generated HTML to change (because it was incorrect before) but future automatic invocations of mdformat will check that any markdown changes don't affect rendered output.
Along the way, I've been finding semi-related formatting problems that were also causing the mkdocs output to be incorrect or hard to read, this fixes those too:
mdformat-mkdocs
plugin renumbers lists according to how they are parsed. List numbering problems will now be visible in the Markdown source.This change adds two new external dependencies at build time, imported via pip:
And one new JavaScript library at runtime, via jsdelivr CDN: