From ecdc34fa4827862612b67867ecf9d4bb4d534a8d Mon Sep 17 00:00:00 2001 From: Brandon Harvey <8107750+bharvey88@users.noreply.github.com> Date: Wed, 3 Jun 2026 14:21:25 -0500 Subject: [PATCH] docs(starter-kit): add community help CTA snippet to every page (#924) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Wrap the existing bare Discord / Community Forum buttons in a friendlier note admonition ("New to ESPHome? We're here to help.") and extend the CTA to every page under the ESPHome Starter Kit product, not just the four module pages that had the bare button row before. The admonition lives in one shared snippet so the CTA copy and buttons stay in sync as they evolve: - New: `docs/_snippets/community-help.md` (single source of truth) - 4 module pages: replace the bare Discord/Forum row with the snippet include, keeping the existing "Try it in an automation" automation buttons above it - 17 other starter-kit pages (start-here, first-steps, 3 tutorials, 5 automations, 6 learning-the-basics entries, FAQ): append the snippet include at the very bottom Convention documented in three places following the precedent set by the difficulty-pills PR (#920): - `STYLE_GUIDE.md` — new section 11 "Community CTA on starter-kit pages" (renumbers "When in doubt" to section 12) - `CONTRIBUTING.md` — one-line bullet under Doc Standards pointing at the new style-guide section - `AGENTS.md` — new bullet under "High-impact rules AI tools get wrong most often" so future AI editors don't forget the snippet on new pages --- AGENTS.md | 6 ++++ CONTRIBUTING.md | 1 + STYLE_GUIDE.md | 34 ++++++++++++++++++- docs/_snippets/community-help.md | 6 ++++ .../automations/button-controlled-leds.md | 4 ++- .../automations/motion-activated-light.md | 4 ++- .../automations/play-a-tune.md | 4 ++- .../automations/press-to-check-climate.md | 3 ++ .../automations/temp-reactive-leds.md | 3 ++ docs/products/ESPHome-Starter-Kit/faq.md | 3 ++ .../learning-the-basics/core-components.md | 3 ++ .../device-builder-tour.md | 4 ++- .../learning-the-basics/explaining-esphome.md | 3 ++ .../how-esphome-talks-to-home-assistant.md | 3 ++ .../what-is-secrets-yaml.md | 3 ++ .../learning-the-basics/what-is-yaml.md | 3 ++ .../modules/button-module.md | 3 +- .../modules/motion-module.md | 3 +- .../modules/rgb-buzzer-module.md | 3 +- .../modules/temperature-humidity-module.md | 3 +- .../ESPHome-Starter-Kit/setup/first-steps.md | 4 ++- .../ESPHome-Starter-Kit/start-here.md | 4 ++- .../tutorials/connect-to-home-assistant.md | 3 ++ .../tutorials/light-effects.md | 4 ++- .../tutorials/using-secrets.md | 4 ++- 25 files changed, 101 insertions(+), 17 deletions(-) create mode 100644 docs/_snippets/community-help.md diff --git a/AGENTS.md b/AGENTS.md index 57b6b97037..fbe5ed900a 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -42,6 +42,12 @@ Read the full style guide, but these are the ones worth checking twice: same-product stepping-stone box linking easier automations. Pill and box styles live in `docs/stylesheets/extra.css`; never inline colors. See [Automation difficulty](STYLE_GUIDE.md#10-automation-difficulty). +- Every page under the ESPHome Starter Kit product (modules, tutorials, + automations, learn-the-basics, FAQ, start-here, first-steps) must end + with the community CTA snippet: + `--8<-- "_snippets/community-help.md"`. To change the CTA copy or + buttons, edit the snippet file, never the include line on a page. + See [Community CTA on starter-kit pages](STYLE_GUIDE.md#11-community-cta-on-starter-kit-pages). ## Keep the style guide current diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8daeeff6c1..3977f2b187 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -79,6 +79,7 @@ The full writing and formatting rules live in [STYLE_GUIDE.md](STYLE_GUIDE.md). - **ESPHome** is the only correct casing. - **No em dashes** anywhere in user-facing copy. - **Automation pages** carry a difficulty pill (`Level 1 Starter` to `Level 5 Pro`) under the title; harder pages can link easier ones in a stepping-stone box. See [Automation difficulty](STYLE_GUIDE.md#10-automation-difficulty). +- **Starter-kit pages** end with the community CTA snippet (`--8<-- "_snippets/community-help.md"`). Edit the snippet, not the page, when the CTA copy changes. See [Community CTA on starter-kit pages](STYLE_GUIDE.md#11-community-cta-on-starter-kit-pages). Mechanical conventions: - MkDocs Material: see https://squidfunk.github.io/mkdocs-material/ for admonitions, tabs, and content tabs syntax diff --git a/STYLE_GUIDE.md b/STYLE_GUIDE.md index bc3ff7d641..4a444aba0f 100644 --- a/STYLE_GUIDE.md +++ b/STYLE_GUIDE.md @@ -450,7 +450,39 @@ colors on the page. --- -## 11. When in doubt +## 11. Community CTA on starter-kit pages + +Every page under the **ESPHome Starter Kit** product carries the same +community call-to-action at the bottom: a friendly note admonition titled +"New to ESPHome? We're here to help." with links to Discord and the +Community Forum. The copy and buttons live in a single snippet so the +CTA stays consistent across the product and only needs one edit to update. + +**Source of truth:** `docs/_snippets/community-help.md` + +**Where to include it:** at the very bottom of any starter-kit page (after +any existing "Try it in an automation" buttons, "Next Steps" buttons, or +closing success admonition). One blank line of separation from the +content above is enough. + +**How to include it:** + +```markdown +--8<-- "_snippets/community-help.md" +``` + +**When you add a new starter-kit page**, end it with this include before +opening the PR. **When you edit the CTA copy** (adding a new channel, +rewording the prompt, swapping button labels), edit the snippet file +itself, never the include line on a page. + +The snippet uses the standard `note` admonition flavor for visual +consistency with the kit's other admonitions ("Before you start", tips, +warnings); don't swap it for `tip` or `info` on a per-page basis. + +--- + +## 12. When in doubt If a rule above conflicts with clarity for the reader, clarity wins. Open an issue or PR proposing the rule change so the guide stays diff --git a/docs/_snippets/community-help.md b/docs/_snippets/community-help.md new file mode 100644 index 0000000000..14f2aa7a0f --- /dev/null +++ b/docs/_snippets/community-help.md @@ -0,0 +1,6 @@ +!!! note "New to ESPHome? We're here to help." + + Stuck on a step or want to show off what you built? Ask questions and share projects with the Apollo community. + + [Join our Discord :simple-discord:](https://link.apolloautomation.com/discord){ .md-button .md-button--discord } + [Community Forum :material-forum:](https://forum.apolloautomation.com/){ .md-button .md-button--primary } diff --git a/docs/products/ESPHome-Starter-Kit/automations/button-controlled-leds.md b/docs/products/ESPHome-Starter-Kit/automations/button-controlled-leds.md index 40e68e5364..3277e6f815 100644 --- a/docs/products/ESPHome-Starter-Kit/automations/button-controlled-leds.md +++ b/docs/products/ESPHome-Starter-Kit/automations/button-controlled-leds.md @@ -96,4 +96,6 @@ With the device back online, press the button on the Button module. You should h #### Next Steps - Next - Light Effects \ No newline at end of file + Next - Light Effects + +--8<-- "_snippets/community-help.md" diff --git a/docs/products/ESPHome-Starter-Kit/automations/motion-activated-light.md b/docs/products/ESPHome-Starter-Kit/automations/motion-activated-light.md index 61375af4e6..4b4b51ca2f 100644 --- a/docs/products/ESPHome-Starter-Kit/automations/motion-activated-light.md +++ b/docs/products/ESPHome-Starter-Kit/automations/motion-activated-light.md @@ -127,4 +127,6 @@ Right now the light turns on with motion but never turns off. Add a second trigg !!! success "You've built a motion-activated light!" - Same trigger-then-action pattern, new trigger. Swap the action (play a buzzer tune, dim the light, send a notification) or the trigger (a button, a temperature threshold, a schedule) and you have a new automation. \ No newline at end of file + Same trigger-then-action pattern, new trigger. Swap the action (play a buzzer tune, dim the light, send a notification) or the trigger (a button, a temperature threshold, a schedule) and you have a new automation. + +--8<-- "_snippets/community-help.md" diff --git a/docs/products/ESPHome-Starter-Kit/automations/play-a-tune.md b/docs/products/ESPHome-Starter-Kit/automations/play-a-tune.md index 0e70f126e2..1d9a43f214 100644 --- a/docs/products/ESPHome-Starter-Kit/automations/play-a-tune.md +++ b/docs/products/ESPHome-Starter-Kit/automations/play-a-tune.md @@ -140,4 +140,6 @@ Want more? Next - Connect to Home Assistant + + +--8<-- "_snippets/community-help.md" diff --git a/docs/products/ESPHome-Starter-Kit/automations/temp-reactive-leds.md b/docs/products/ESPHome-Starter-Kit/automations/temp-reactive-leds.md index 9e87f43559..bbb20e7f4a 100644 --- a/docs/products/ESPHome-Starter-Kit/automations/temp-reactive-leds.md +++ b/docs/products/ESPHome-Starter-Kit/automations/temp-reactive-leds.md @@ -163,3 +163,6 @@ Open the Comfortable and Hot triggers in the GUI and edit the **Above** / **Belo #### Next Steps Next - Connect to Home Assistant + + +--8<-- "_snippets/community-help.md" diff --git a/docs/products/ESPHome-Starter-Kit/faq.md b/docs/products/ESPHome-Starter-Kit/faq.md index 3eec82c6dd..f2125cdce9 100644 --- a/docs/products/ESPHome-Starter-Kit/faq.md +++ b/docs/products/ESPHome-Starter-Kit/faq.md @@ -67,3 +67,6 @@ description: Frequently asked questions about the ESPHome Starter Kit, ESPHome D * The ESP32-C6 is a modern microcontroller from Espressif that brings Wi-Fi, Bluetooth LE, and Thread support to a single chip. It is the same family of silicon used in commercially certified smart home products, and gives learners a future-ready platform that supports the same open standards used in production smart home devices. [Click here to join our Discord for fast support! :simple-discord:](https://link.apolloautomation.com/discord){ .md-button .md-button--primary } + + +--8<-- "_snippets/community-help.md" diff --git a/docs/products/ESPHome-Starter-Kit/learning-the-basics/core-components.md b/docs/products/ESPHome-Starter-Kit/learning-the-basics/core-components.md index 963108a139..790d444af1 100644 --- a/docs/products/ESPHome-Starter-Kit/learning-the-basics/core-components.md +++ b/docs/products/ESPHome-Starter-Kit/learning-the-basics/core-components.md @@ -68,3 +68,6 @@ If you remove the rail, **the Onboard RGB LED and any plugged-in modules will st 3. Click **Add** once more to confirm. ESPHome GPIO Switch docs + + +--8<-- "_snippets/community-help.md" diff --git a/docs/products/ESPHome-Starter-Kit/learning-the-basics/device-builder-tour.md b/docs/products/ESPHome-Starter-Kit/learning-the-basics/device-builder-tour.md index bc8fd1f06b..a6c9a40fc2 100644 --- a/docs/products/ESPHome-Starter-Kit/learning-the-basics/device-builder-tour.md +++ b/docs/products/ESPHome-Starter-Kit/learning-the-basics/device-builder-tour.md @@ -80,4 +80,6 @@ Pop them open when something looks off, or just to watch sensor readings come in * Read [What is secrets.yaml?](what-is-secrets-yaml.md) to understand how Wi-Fi and encryption keys are stored. * Bookmark the [official ESPHome documentation](https://esphome.io) for component reference whenever you click a **Docs** link. - Back - Explaining ESPHome Next - What is YAML? \ No newline at end of file + Back - Explaining ESPHome Next - What is YAML? + +--8<-- "_snippets/community-help.md" diff --git a/docs/products/ESPHome-Starter-Kit/learning-the-basics/explaining-esphome.md b/docs/products/ESPHome-Starter-Kit/learning-the-basics/explaining-esphome.md index ff37dc751b..063e213ecf 100644 --- a/docs/products/ESPHome-Starter-Kit/learning-the-basics/explaining-esphome.md +++ b/docs/products/ESPHome-Starter-Kit/learning-the-basics/explaining-esphome.md @@ -48,3 +48,6 @@ You get wireless updates, a built-in web page for controlling your device, and d The official ESPHome documentation covers every component, configuration option, and advanced topic in detail. Next - Device Builder Tour Visit esphome.io + + +--8<-- "_snippets/community-help.md" diff --git a/docs/products/ESPHome-Starter-Kit/learning-the-basics/how-esphome-talks-to-home-assistant.md b/docs/products/ESPHome-Starter-Kit/learning-the-basics/how-esphome-talks-to-home-assistant.md index fbd070a697..b29d0e3bc4 100644 --- a/docs/products/ESPHome-Starter-Kit/learning-the-basics/how-esphome-talks-to-home-assistant.md +++ b/docs/products/ESPHome-Starter-Kit/learning-the-basics/how-esphome-talks-to-home-assistant.md @@ -55,3 +55,6 @@ For a single device, the on-device web page is often enough. For anything that t For UniFi networks specifically, see our [UniFi mDNS troubleshooting guide](../../../general/troubleshooting/ubiquiti-unifi-mdns-auto-discover-issue/). Back - What is secrets.yaml? Tutorial - Connect to Home Assistant + + +--8<-- "_snippets/community-help.md" diff --git a/docs/products/ESPHome-Starter-Kit/learning-the-basics/what-is-secrets-yaml.md b/docs/products/ESPHome-Starter-Kit/learning-the-basics/what-is-secrets-yaml.md index 915bc27cd9..ad4fe5f67a 100644 --- a/docs/products/ESPHome-Starter-Kit/learning-the-basics/what-is-secrets-yaml.md +++ b/docs/products/ESPHome-Starter-Kit/learning-the-basics/what-is-secrets-yaml.md @@ -38,3 +38,6 @@ Treat secrets.yaml like a password manager entry: Ready to put this into practice? The Using Secrets tutorial walks through opening secrets.yaml in the Device Builder, the `!secret` syntax, and what to store for every common case (Wi-Fi, Home Assistant API, OTA, web server auth, MQTT). Using Secrets tutorial + + +--8<-- "_snippets/community-help.md" diff --git a/docs/products/ESPHome-Starter-Kit/learning-the-basics/what-is-yaml.md b/docs/products/ESPHome-Starter-Kit/learning-the-basics/what-is-yaml.md index 6640ebba07..51a1b33076 100644 --- a/docs/products/ESPHome-Starter-Kit/learning-the-basics/what-is-yaml.md +++ b/docs/products/ESPHome-Starter-Kit/learning-the-basics/what-is-yaml.md @@ -118,3 +118,6 @@ You did not type any of that. The Builder wrote it when you clicked **Add**. Onc The official YAML site has the full specification, and the ESPHome docs walk through YAML in the context of ESPHome specifically. YAML official site ESPHome YAML guide + + +--8<-- "_snippets/community-help.md" diff --git a/docs/products/ESPHome-Starter-Kit/modules/button-module.md b/docs/products/ESPHome-Starter-Kit/modules/button-module.md index 589d7cbd2b..26407224d8 100644 --- a/docs/products/ESPHome-Starter-Kit/modules/button-module.md +++ b/docs/products/ESPHome-Starter-Kit/modules/button-module.md @@ -128,5 +128,4 @@ Your button is live. Now make it trigger something: Play a Tune Press to Check Climate -[Join our Discord :simple-discord:](https://link.apolloautomation.com/discord){ .md-button .md-button--discord } -[Community Forum :material-forum:](https://forum.apolloautomation.com/){ .md-button .md-button--primary } \ No newline at end of file +--8<-- "_snippets/community-help.md" \ No newline at end of file diff --git a/docs/products/ESPHome-Starter-Kit/modules/motion-module.md b/docs/products/ESPHome-Starter-Kit/modules/motion-module.md index bcdc25fd85..5564ee3e8b 100755 --- a/docs/products/ESPHome-Starter-Kit/modules/motion-module.md +++ b/docs/products/ESPHome-Starter-Kit/modules/motion-module.md @@ -125,5 +125,4 @@ Your motion sensor is live. Put it to work: Motion-Activated Light -[Join our Discord :simple-discord:](https://link.apolloautomation.com/discord){ .md-button .md-button--discord } -[Community Forum :material-forum:](https://forum.apolloautomation.com/){ .md-button .md-button--primary } \ No newline at end of file +--8<-- "_snippets/community-help.md" \ No newline at end of file diff --git a/docs/products/ESPHome-Starter-Kit/modules/rgb-buzzer-module.md b/docs/products/ESPHome-Starter-Kit/modules/rgb-buzzer-module.md index 970c9cdd4d..26deefa67a 100755 --- a/docs/products/ESPHome-Starter-Kit/modules/rgb-buzzer-module.md +++ b/docs/products/ESPHome-Starter-Kit/modules/rgb-buzzer-module.md @@ -138,5 +138,4 @@ Your notification module is ready. Drive it from any of these automations: Temp-Reactive LEDs Motion-Activated Light -[Join our Discord :simple-discord:](https://link.apolloautomation.com/discord){ .md-button .md-button--discord } -[Community Forum :material-forum:](https://forum.apolloautomation.com/){ .md-button .md-button--primary } \ No newline at end of file +--8<-- "_snippets/community-help.md" \ No newline at end of file diff --git a/docs/products/ESPHome-Starter-Kit/modules/temperature-humidity-module.md b/docs/products/ESPHome-Starter-Kit/modules/temperature-humidity-module.md index 031dee766a..642fcee2b2 100755 --- a/docs/products/ESPHome-Starter-Kit/modules/temperature-humidity-module.md +++ b/docs/products/ESPHome-Starter-Kit/modules/temperature-humidity-module.md @@ -134,5 +134,4 @@ Your sensor is reporting. Now make it drive something: Temp-Reactive LEDs Press to Check Climate -[Join our Discord :simple-discord:](https://link.apolloautomation.com/discord){ .md-button .md-button--discord } -[Community Forum :material-forum:](https://forum.apolloautomation.com/){ .md-button .md-button--primary } \ No newline at end of file +--8<-- "_snippets/community-help.md" \ No newline at end of file diff --git a/docs/products/ESPHome-Starter-Kit/setup/first-steps.md b/docs/products/ESPHome-Starter-Kit/setup/first-steps.md index 167f9448f1..7649d9c1a1 100755 --- a/docs/products/ESPHome-Starter-Kit/setup/first-steps.md +++ b/docs/products/ESPHome-Starter-Kit/setup/first-steps.md @@ -219,4 +219,6 @@ Example of the light changing colors below! ![](../../../assets/esphome-starter-kit-onboard-rgb-led-light-up.webp) - Back - Start Here Add More Modules Connect to Home Assistant \ No newline at end of file + Back - Start Here Add More Modules Connect to Home Assistant + +--8<-- "_snippets/community-help.md" diff --git a/docs/products/ESPHome-Starter-Kit/start-here.md b/docs/products/ESPHome-Starter-Kit/start-here.md index 23b5523e83..b122cc998c 100755 --- a/docs/products/ESPHome-Starter-Kit/start-here.md +++ b/docs/products/ESPHome-Starter-Kit/start-here.md @@ -84,4 +84,6 @@ Each module is connected to the panel by small breakaway tabs. Follow the steps Once you've identified your modules and snapped them off the panel, the next step is to connect the main board to your computer and walk through your first ESPHome configuration. - Next - First Steps \ No newline at end of file + Next - First Steps + +--8<-- "_snippets/community-help.md" diff --git a/docs/products/ESPHome-Starter-Kit/tutorials/connect-to-home-assistant.md b/docs/products/ESPHome-Starter-Kit/tutorials/connect-to-home-assistant.md index 1e5aaff714..7ce1c4af3e 100644 --- a/docs/products/ESPHome-Starter-Kit/tutorials/connect-to-home-assistant.md +++ b/docs/products/ESPHome-Starter-Kit/tutorials/connect-to-home-assistant.md @@ -48,3 +48,6 @@ Open `secrets.yaml` in Device Builder, copy the `api_encryption_key` value, and Want to understand what just happened under the hood? Read [the Home Assistant integration](../learning-the-basics/how-esphome-talks-to-home-assistant.md). Back - First Steps + + +--8<-- "_snippets/community-help.md" diff --git a/docs/products/ESPHome-Starter-Kit/tutorials/light-effects.md b/docs/products/ESPHome-Starter-Kit/tutorials/light-effects.md index 576d4b628b..2696ea5ddd 100644 --- a/docs/products/ESPHome-Starter-Kit/tutorials/light-effects.md +++ b/docs/products/ESPHome-Starter-Kit/tutorials/light-effects.md @@ -61,4 +61,6 @@ If you've already followed [Connect to Home Assistant](/products/ESPHome-Starter !!! success "You just edited YAML!" - Every component you add to your device has a set of advanced fields like this one. Pasting a few lines into the right field is all it takes to unlock more behavior, and the YAML pane on the right of the editor will show you exactly what changed. \ No newline at end of file + Every component you add to your device has a set of advanced fields like this one. Pasting a few lines into the right field is all it takes to unlock more behavior, and the YAML pane on the right of the editor will show you exactly what changed. + +--8<-- "_snippets/community-help.md" diff --git a/docs/products/ESPHome-Starter-Kit/tutorials/using-secrets.md b/docs/products/ESPHome-Starter-Kit/tutorials/using-secrets.md index 412691ad5f..2a49a2b822 100644 --- a/docs/products/ESPHome-Starter-Kit/tutorials/using-secrets.md +++ b/docs/products/ESPHome-Starter-Kit/tutorials/using-secrets.md @@ -212,4 +212,6 @@ You don't have to include every entry. If a device doesn't use MQTT, leave those * Don't share or post the file. Share device YAMLs instead, the `!secret` references are safe. * Keep a backup somewhere safe (a password manager works well). If you reinstall ESPHome Device Builder you'll need to recreate it. - * Rotating a credential is a one-line edit here, then re-flash anything that uses it. \ No newline at end of file + * Rotating a credential is a one-line edit here, then re-flash anything that uses it. + +--8<-- "_snippets/community-help.md"