mongodb / specifications

Specifications related to MongoDB
http://specifications.readthedocs.io/en/latest
Other
389 stars 242 forks source link

DRIVERS-3010 reformat specs for improved mkdocs rendering #1678

Closed mdbmes closed 1 day ago

mdbmes commented 3 days ago

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:

This change adds two new external dependencies at build time, imported via pip:

And one new JavaScript library at runtime, via jsdelivr CDN:

mdbmes commented 3 days 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.

mdbmes commented 1 day ago

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.

mdbmes commented 1 day ago

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.