chores: fix Markdown documentation issues

[dima-safin-2025]

Overview

This PR addresses multiple issues in our Markdown documentation that could potentially affect the readability and correct parsing of our docs. Specifically, it corrects file extensions and improper HTML comment nesting.

Changes

• Fix incorrect file extensions for Markdown documents
  • Added the .md extension to files previously missing it, ensuring they are recognized and rendered correctly across various tools and environments.
• Fix improperly nested HTML comments in Markdown files and remove redundant typos
  • Corrected instances where HTML comments were nested, which could lead to parsing errors and unintended content display. Comments are now separated into distinct blocks.
  • Removed redundant typos which could lead to unclear or incorrect information being presented in the documentation. This ensures that all text is accurate and professional.

Impact

• Ensures all Markdown files are recognized and handled correctly by editors and version control systems.
• Prevents parsing errors in documentation due to improperly nested comments, improving document stability and readability.

Testing

• All changes have been visually inspected in several Markdown editors (e.g., VSCode) to ensure proper rendering.
• Links and comment blocks have been tested to confirm they do not produce any unintended effects.

Conclusion

Merging these fixes will significantly improve the maintenance and clarity of our documentation, making it easier for developers to work with and for tools to process our docs accurately.

[dima-safin-2025]

@vitsalis @gitferry @SebastianElvis @KonradStaniec