Shorten Learn the Basics sidebar headings

[bharvey88]

What does this implement/fix?

Trims the within-page H2 headings on Explaining ESPHome and What is YAML? so the left sidebar entries are shorter and don't wrap.

• ESPHome vs ESPHome Device Builder -> ESPHome vs Device Builder
• How you talk to your device -> Controlling your device
• Why the Starter Kit is built on ESPHome -> Why ESPHome
• What this looks like in ESPHome -> ESPHome example

Body content is unchanged. Holding this PR open for more changes before merge.

Types of changes

• Typo / wording fix
• Content update (correcting outdated info, adding missing steps, clarifications)
• New page or new product section
• Page move / rename (redirect added in mkdocs.yml)
• Image / screenshot update
• Nav / structure change
• Site config or theme change
• CI / workflows / dependencies — Does not publish

Checklist:

• This PR targets the dev branch (not main)
• Changes previewed locally with mkdocs serve
• If pages were moved or renamed, redirects were added to mkdocs.yml
• If new pages were added, nav was updated in mkdocs.yml

Summary by CodeRabbit

• Documentation
  • Revised ESPHome learning guides with clearer section headings and improved content structure for better comprehension
  • Expanded YAML documentation with practical spacing rules, code examples, and indentation best practices to prevent common errors
  • Enhanced guidance on device interaction and control with improved terminology
  • Optimized tutorial navigation across learning materials

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 8c431744-10a4-43ba-bd4c-1df52c18dccd

📥 Commits

Reviewing files that changed from the base of the PR and between 5c381da and 5caa3c0.

📒 Files selected for processing (3)

• docs/products/ESPHome-Starter-Kit/learning-the-basics/explaining-esphome.md
• docs/products/ESPHome-Starter-Kit/learning-the-basics/what-is-secrets-yaml.md
• docs/products/ESPHome-Starter-Kit/learning-the-basics/what-is-yaml.md

---

Walkthrough

Three ESPHome Starter Kit learning documentation pages are cleaned up with simplified heading names, improved YAML guidance, and consistent removal of redundant "Back to First Steps" navigation buttons to streamline the learning experience.

Changes

Documentation Structure and Navigation Updates

Layer / File(s)	Summary
Explaining ESPHome documentation refresh docs/products/ESPHome-Starter-Kit/learning-the-basics/explaining-esphome.md	Headings are simplified ("ESPHome vs Device Builder," "Controlling your device," "Why ESPHome") and the section on why ESPHome is used is rewritten for clarity. The redundant "Back to First Steps" button is removed while preserving the primary "Visit esphome.io" link.
YAML and secrets learning documentation docs/products/ESPHome-Starter-Kit/learning-the-basics/what-is-yaml.md, docs/products/ESPHome-Starter-Kit/learning-the-basics/what-is-secrets-yaml.md	YAML documentation gains a new "Spacing matters" subsection with three practical indentation rules and code examples, replacing older gotchas content. Both files remove their "Back to First Steps" button to align navigation across the learning section.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

• ApolloAutomation/docs#778: Related documentation navigation cleanup that removes "Back to First Steps" buttons from getting-started materials.
• ApolloAutomation/docs#820: Concurrent updates to the same ESPHome Starter Kit learning documentation files with heading and content structure changes.

Poem

📚 The docs get a refresh, so tidy and clean,
Headings simplified, navigation serene,
YAML rules spelled out with examples so neat,
No back-step buttons, the guide is complete! 🐰✨

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch esk-learn-the-basics-headings

---

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