Skip to content

[docs] Add MDX style checklist to AGENTS.md#6696

Closed
bharvey88 wants to merge 1 commit into
esphome:currentfrom
bharvey88:docs-agents-checklist
Closed

[docs] Add MDX style checklist to AGENTS.md#6696
bharvey88 wants to merge 1 commit into
esphome:currentfrom
bharvey88:docs-agents-checklist

Conversation

@bharvey88
Copy link
Copy Markdown
Contributor

Description

Proposal — adding a short "Verifying Style Before Submitting" section to AGENTS.md. Companion to #6695 (CONTRIBUTING.md MDX-style additions).

Depends on #6695. This PR links to the CONTRIBUTING.md#before-submitting checklist with items added in that PR; merging this before #6695 means the linked items don't exist yet.

In #6692 review @jesserockz pointed out style and pattern issues despite both CONTRIBUTING.md and AGENTS.md being available to read. The CONTRIBUTING.md additions in #6695 cover the underlying conventions; this PR adds a brief reminder in AGENTS.md that points back to the checklist and calls out the items easiest for an agent to overlook.

Changes:

  • New "Verifying Style Before Submitting" section right after the existing @CONTRIBUTING.md pointer
  • Four short bullets covering the items most easily overlooked: Title Case headings, backticked variable names, Markdown over HTML, and repeated structure as a component candidate

This is a proposal, not a finished change. Happy to fold this into #6695 if maintainers prefer it bundled, or cut it entirely.

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.

@esphome esphome Bot added the current label May 26, 2026
@netlify
Copy link
Copy Markdown

netlify Bot commented May 26, 2026

Deploy Preview for esphome ready!

Name Link
🔨 Latest commit c087708
🔍 Latest deploy log https://app.netlify.com/projects/esphome/deploys/6a15dfff3ee7220008f06669
😎 Deploy Preview https://deploy-preview-6696--esphome.netlify.app
📱 Preview on mobile
Toggle QR Code...

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
Copy link
Copy Markdown
Contributor

coderabbitai Bot commented May 26, 2026

Review Change Stack

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: d28d37ac-921c-46ea-9ba0-b35bc74ee36d

📥 Commits

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

📒 Files selected for processing (1)
  • AGENTS.md

Walkthrough

AGENTS.md receives a new "Verifying Style Before Submitting" section that provides a pre-submission checklist for AI agents to verify style compliance with repository standards, including title case, backtick usage for code elements, and preferring Markdown over HTML.

Changes

Documentation and Style Guidance

Layer / File(s) Summary
Style verification checklist for AI agents
AGENTS.md
Added a pre-submission checklist section that references CONTRIBUTING.md and lists specific style items to verify: title case for headings, backtick wrapping for variables and code snippets, and use of Markdown instead of HTML equivalents.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

🚥 Pre-merge checks | ✅ 5
✅ Passed checks (5 passed)
Check name Status Explanation
Title check ✅ Passed The title clearly and specifically describes the main change: adding an MDX style checklist to AGENTS.md, which aligns with the actual file modification shown in the summary.
Description check ✅ Passed The description is directly related to the changeset, providing context about the new section being added to AGENTS.md, its purpose, and relationship to PR #6695.
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

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

@bharvey88
Copy link
Copy Markdown
Contributor Author

closing as not needed since CONTRIBUTING.md is already being pointed to in AGENTS.md

@bharvey88 bharvey88 closed this May 26, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant