Context
Currently, our documentation frequently uses a "tab set" pattern to display examples, separating "Output" from "Markdown" source. While effective for presentation, this approach doesn't inherently facilitate the testing of our Markdown rendering.
Proposal: Introduce a "Markdown Example Testing" Component
I propose we develop a dedicated component that not only renders Markdown content for documentation but can also be leveraged as a robust Markdown test runner.
Imagine a system where:
- This new component takes Markdown content as input.
- It renders this Markdown, just as it would appear in our documentation.
- The rendered output is then compared against a snapshot.
- Crucially, this system would include the familiar capabilities of snapshot testing, such as the ability to easily update snapshots when changes to the Markdown rendering are intentional.
This component would effectively merge our documentation examples with our testing infrastructure.
Why This Matters: Efficiency & Quality
Implementing this "Markdown Example Testing" component offers significant benefits:
- 📈 Increased Efficiency: We would combine the efforts of documenting and testing Markdown syntax into a single, cohesive workflow. This eliminates redundant manual checks and ensures our examples are always accurate.
- 🛡️ Enhanced Test Coverage: This approach would dramatically increase our test coverage for Markdown rendering, catching regressions and inconsistencies proactively.
- 💡 Improved Developer Experience: Developers could write Markdown examples with the confidence that they are automatically tested, leading to a more streamlined and less error-prone documentation process.
This initiative represents a significant step towards a more robust, efficient, and reliable documentation and development workflow.
Context
Currently, our documentation frequently uses a "tab set" pattern to display examples, separating "Output" from "Markdown" source. While effective for presentation, this approach doesn't inherently facilitate the testing of our Markdown rendering.
Proposal: Introduce a "Markdown Example Testing" Component
I propose we develop a dedicated component that not only renders Markdown content for documentation but can also be leveraged as a robust Markdown test runner.
Imagine a system where:
This component would effectively merge our documentation examples with our testing infrastructure.
Why This Matters: Efficiency & Quality
Implementing this "Markdown Example Testing" component offers significant benefits:
This initiative represents a significant step towards a more robust, efficient, and reliable documentation and development workflow.