[docs] Document MDX component reuse and Markdown preferences

[bharvey88]

Description

Proposal — adding three MDX-style sections and four "Before Submitting" checklist items to CONTRIBUTING.md, triggered by feedback on #6692.

In #6692 I wrote about 300 lines of inline <style> and duplicated HTML tables in MDX rather than extracting an Astro component, and used <table> HTML where native Markdown tables would have rendered the same. @jesserockz refactored both in a follow-up commit on the PR. The patterns aren't covered in CONTRIBUTING.md today, so this PR proposes language to capture them.

Changes:

• New "Reusable Components for Repeated Patterns" subsection that cites LightEffectPreview as the example, defers new-component decisions to maintainers, and discourages large inline <style> blocks
• New "Prefer Markdown over Raw HTML" subsection covering tables, links, and emphasis
• New "Prefer small, focused pull requests" bullet under Branch Strategy
• Four new "Before Submitting" checklist items: Title Case headings, backticked variable names, Markdown over HTML, no large inline <style> blocks

This is a proposal, not a finished change. Open to wording changes, scope cuts, or rephrasing — if maintainers prefer to leave new-component decisions implicit (and just refactor in review like #6692 went), that subsection can be cut. Submitting per the "prefer small, focused PRs" guidance this PR adds, so AGENTS.md is in a separate PR.

Related issue (if applicable): n/a

Pull request in esphome with YAML changes (if applicable): n/a

Checklist

• I am merging into next because this is new documentation that has a matching pull-request in esphome as linked above.
  or

• I am merging into current because this is a fix, change and/or adjustment in the current documentation and is not for a new component or feature.

• Link added in /src/content/docs/components/index.mdx when creating new documents for new components or cookbook.

New Component Images

If you are adding a new component to ESPHome, you can automatically generate a standardized black and white component name image for the documentation.

To generate a component image:

1. Comment on this pull request with the following command, replacing component_name with your component name in lower_case format with underscores (e.g., bme280, sht3x, dallas_temp):

   @esphomebot generate image component_name
   

2. The ESPHome bot will respond with a downloadable ZIP file containing the SVG image.

3. Extract the SVG file and place it in the /public/images/ folder of this repository.

4. Use the image in your component's index table entry in /src/content/docs/components/index.mdx.

Example: For a component called "DHT22 Temperature Sensor", use:

@esphomebot generate image dht22

Note: All images used in ImgTable components must be placed in /public/images/ as the component resolves them to absolute paths.

[netlify]

✅ Deploy Preview for esphome ready!

Name	Link
🔨 Latest commit	631b6be
🔍 Latest deploy log	https://app.netlify.com/projects/esphome/deploys/6a15dfe554d4b5000890f95c
😎 Deploy Preview	https://deploy-preview-6695--esphome.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
🤖 Make changes	Run an agent on this branch

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: f3fbc410-4c03-47fd-9357-e40538f56dcb

📥 Commits

Reviewing files that changed from the base of the PR and between 5a457a8 and 631b6be.

📒 Files selected for processing (1)

• CONTRIBUTING.md

---

Walkthrough

This pull request updates CONTRIBUTING.md with expanded documentation-writing guidance. Two new sections advise when to create reusable Astro components and when to prefer Markdown over raw HTML/JSX. The "Before Submitting" checklist is extended with four new formatting rules covering Title Case headings, backtick wrapping for code terms, Markdown preference, and style block constraints in MDX files.

Changes

Contributing Guide Enhancements

Layer / File(s)	Summary
New guidance sections on components and Markdown preference CONTRIBUTING.md	Two new advisory sections are added: one recommending reusable Astro components for repeated UI patterns, and another advocating for Markdown syntax over equivalent raw HTML or JSX in documentation.
Extended submission checklist with MDX and style rules CONTRIBUTING.md	The "Before Submitting" checklist is extended with four new conformance items: Title Case for section headings, single-backtick wrapping for variable/parameter names and short code snippets, preferring Markdown equivalents over HTML/JSX, and avoiding large inline style blocks in MDX.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~5 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately describes the main changes: adding documentation about MDX component reuse patterns and Markdown preferences to CONTRIBUTING.md.
Description check	✅ Passed	The description is directly related to the changeset, providing clear context about the motivation, specific additions to CONTRIBUTING.md, and acknowledging it as a proposal.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}