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