Repository navigation
Preserve MkDocs syntax during Markdown formatting - #176
Conversation
|
Hi @hugosmoreira thanks for working on this. Let me know when its ready for review. Also if there are any screenshots you can add of the locally-built docs site, that will be helpful for acceptance testing. |
|
Thanks! This is ready for review. I rebuilt the documentation site from the current PR head and confirmed that the MkDocs admonition and generated API reference render correctly. I’ve attached screenshots of both views. 
|
s2t2
left a comment
s2t2
left a comment
There was a problem hiding this comment.
@hugosmoreira thanks for taking this on!
This PR looks generally good to me.
Could you please reply to the two minor comments I left?
Then we can merge.
| steps: | ||
| - name: Checkout code | ||
| uses: actions/checkout@v4 | ||
| uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4 |
There was a problem hiding this comment.
is there a reason we are pinning to very specific versions rather than the general v4? was there an issue with v4?
There was a problem hiding this comment.
Good question. There was no functional issue with v4. The initial commit used actions/checkout@v4 and actions/setup-python@v4, but the repository security scan reported zizmor/unpinned-uses for both and stated that a full commit hash was required by its blanket policy. The pinned commits are still v4; using full SHAs makes the references immutable and allowed the mandatory scan to pass. I therefore kept the SHA pins.
| # See: https://mdformat.readthedocs.io/en/stable/users/installation_and_usage.html#usage-as-a-pre-commit-hook | ||
| - repo: https://github.com/hukkin/mdformat | ||
| rev: 0.7.22 | ||
| - repo: https://github.com/executablebooks/mdformat |
There was a problem hiding this comment.
I noticed that executablebooks owned repo redirects / resolves to the hukkin owned repo.
Is there a reason this needs to change or would we want to change back to the original hukkin repo?
There was a problem hiding this comment.
Agreed. GitHub resolves executablebooks/mdformat to the canonical hukkin/mdformat repository, and both URLs resolve tag 1.0.0 to the same commit. The URL change was unnecessary, so I restored https://github.com/hukkin/mdformat in signed commit 27dc976 while keeping rev 1.0.0 and mdformat-mkdocs==5.3.0. The exact pre-commit hook passed on all Markdown files and the MkDocs build completed successfully.
Fixes #103
Summary
mdformat1.0.0 and addmdformat-mkdocs5.3.0 in Poetry and pre-commit.docstree, including the previously excludeddocs/apifiles.Plain
mdformatchanges both MkDocs admonitions and configuredmkdocstringsdirectives in ways that break their structure. Withmdformat-mkdocs, the same regression fixture is byte-for-byte unchanged.Validation
poetry check --lockmdformat README.md docs --checkExact pinned
pre-commit run mdformat --all-filesmkdocs build --clean(existing Griffe/link warnings remain)Generated HTML contains the expected rendered admonition and API documentation
git diff --checkFull Python test suite (the locked
tensorflow-io-gcs-filesystem==0.37.1has no compatible Windows wheel; Linux CI is the authoritative run)Appropriate changes to documentation are included in the PR