Preserve MkDocs syntax during Markdown formatting

[hugosmoreira]

Fixes #103

Summary

• Upgrade to mdformat 1.0.0 and add mdformat-mkdocs 5.3.0 in Poetry and pre-commit.
• Format and check the complete docs tree, including the previously excluded docs/api files.
• Enable MkDocs admonitions and use the issue's example in the contributor guide.
• Update the formatter documentation and regenerate the lockfile with the repository's documented Poetry 2.1.2.

Plain mdformat changes both MkDocs admonitions and configured mkdocstrings directives in ways that break their structure. With mdformat-mkdocs, the same regression fixture is byte-for-byte unchanged.

Validation

• poetry check --lock

• mdformat README.md docs --check

• Exact pinned pre-commit run mdformat --all-files

• mkdocs build --clean (existing Griffe/link warnings remain)

• Generated HTML contains the expected rendered admonition and API documentation

• git diff --check

• Full Python test suite (the locked tensorflow-io-gcs-filesystem==0.37.1 has no compatible Windows wheel; Linux CI is the authoritative run)

• Appropriate changes to documentation are included in the PR

[s2t2]

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.

[hugosmoreira]

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.