Docs Style Guide: add section on links

[c0ffeeca7]

Proposed change

Type of change

• Document existing features within Home Assistant
• Document new or changing features for which there is an existing pull request elsewhere
• Spelling or grammatical corrections, or rewording for improved clarity
• Changes to the backend of this documentation
• Remove stale or deprecated documentation

Checklist

• I have read and followed the documentation guidelines.
• I have verified that my changes render correctly in the documentation.

Additional information

• This PR fixes or closes issue: fixes #
• Link to relevant existing code or pull request:

Summary by CodeRabbit

Documentation

• Updated general style guide with expanded Markdown guidance, including:
  • New instructions on using relative links
  • Recommendations to avoid affiliate and tracking links
  • Added See also reference in related sections

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

📝 Walkthrough

Walkthrough

Added a "Links" subsection under Markdown guidance in the style guide with instructions to use relative links on homeassistant.io and avoid affiliate or tracking links. Also added a "See also" reference after the Images section.

Changes

Cohort / File(s)	Summary
Documentation Updates docs/documenting/general-style-guide.md	Added "Links" subsection with guidance on relative vs. absolute link usage and restrictions on affiliate/tracking links; added "See also" reference after Images section

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Pre-merge checks

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The description is largely incomplete. The 'Proposed change' section is empty despite containing new guidance on links. The type of change is incorrectly marked as 'corrections/rewording' rather than documenting new or existing features. Critical checklist items remain unchecked.	Fill in the 'Proposed change' section explaining why links guidance is important. Correct the type of change selection. Check the documentation guidelines and verification checklist items to confirm compliance.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and specifically describes the main change: adding a new section on links to the documentation style guide.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

---

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.}

[coderabbitai]

Actionable comments posted: 0

🧹 Nitpick comments (2)

docs/documenting/general-style-guide.md (2)

50-57: Expand guidance to cover external/absolute links.

The new Links section provides clear guidance for relative links on homeassistant.io, which is valuable. However, the guidance is incomplete for external links. Consider clarifying best practices for links to external sites (e.g., should they use https://, should they specify target="_blank" in any cases, etc.).

🔎 Proposed enhancement

Consider expanding the section to cover both relative and absolute links:

 ## Links
 
 - Use relative links for links on `homeassistant.io`:
   - For example:
     - `/connect/zbt-2/` instead of `https://www.home-assistant.io/connect/zbt-2/`
+- For links to external sites, use full HTTPS URLs (e.g., `https://example.com`).
 - Do not use affiliate or tracking links.

---

50-57: Good addition to the style guide.

The new Links subsection is a valuable contribution to the style guide. It addresses important concerns about maintainability (relative links) and integrity (no tracking/affiliate links). The section is well-placed between Markdown lists and Images, and the example effectively illustrates the guidance. Consider addressing the note about external links guidance above to make this more comprehensive.

📜 Review details

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Cache: Disabled due to data retention organization setting

Knowledge base: Disabled due to data retention organization setting

📥 Commits

Reviewing files that changed from the base of the PR and between be2588c and 8f4b380.

📒 Files selected for processing (1)

• docs/documenting/general-style-guide.md