Skip to content

Rework reading order and small improvements#270

Merged
DTTerastar merged 15 commits intoESPresense:mainfrom
CoMPaTech:ct1
Mar 16, 2026
Merged

Rework reading order and small improvements#270
DTTerastar merged 15 commits intoESPresense:mainfrom
CoMPaTech:ct1

Conversation

@CoMPaTech
Copy link
Copy Markdown
Contributor

@CoMPaTech CoMPaTech commented Feb 20, 2026

  • Rework 'new user' reading order and sidebar sections
  • Re-introduce former hardware section
  • Fix add to home-assistant links in Companion/Installation
  • Rename add-on to apps following HA

Sidebar from local generation:
reworked sitebar order

Summary by CodeRabbit

  • Documentation
    • Reorganized sidebar into “Getting started” and a new “Nodes” section
    • Added guidance comparing two presence-tracking approaches (mqtt_room vs Companion)
    • Overhauled installation docs to include App-based and containerized deployment paths
    • Improved formatting with tip/note/admonition blocks across pages
    • Clarified MQTT examples and related links; adjusted command examples
    • Updated Homebridge description and renamed “Devices” → “Trackable Devices”
    • Added brief enclosures intro and a firmware-installer browser compatibility tip

@coderabbitai
Copy link
Copy Markdown
Contributor

coderabbitai bot commented Feb 20, 2026

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

  • @coderabbitai resume to resume automatic reviews.
  • @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

  • ▶️ Resume reviews
  • 🔍 Trigger review

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: 1f3b215d-87b8-4ce3-a09e-5748338713ba

📥 Commits

Reviewing files that changed from the base of the PR and between 38474e6 and 100b9d2.

📒 Files selected for processing (2)
  • src/content/docs/companion/installation.md
  • src/content/docs/companion/troubleshooting.md
🚧 Files skipped from review as they are similar to previous changes (2)
  • src/content/docs/companion/troubleshooting.md
  • src/content/docs/companion/installation.md

Walkthrough

Reorders and renames site navigation groups and sidebar entries, consolidates approach guidance into dedicated pages, updates Companion installation from add-on to App/Container workflows, reformats help prompts as admonitions, and tweaks MQTT command examples and minor docs text across multiple pages.

Changes

Cohort / File(s) Summary
Navigation / Front-matter
astro.config.mjs, src/content/docs/devices.md, src/content/docs/firmware.mdx, src/content/docs/nodes.md
Renamed and reorganized navigation groups (e.g., Devices → Getting started, MQTT → Trackable Devices), adjusted sidebar order values, and updated document titles to reflect nav changes.
Approach & Landing Content
src/content/docs/approach.mdx, src/content/docs/index.mdx
Added a detailed comparison of mqtt_room vs Companion approaches and replaced per-approach content on the index with a consolidated note and approach-agnostic requirements.
Companion — Installation & Docs formatting
src/content/docs/companion/installation.md, src/content/docs/companion/configuration.md, src/content/docs/companion/optimization.md, src/content/docs/companion/troubleshooting.md
Converted add-on instructions to App and Container deployment paths, updated terminology (add-on → app), and replaced manual help headers with tip/note admonitions; linked troubleshooting to installation.
MQTT & Diagnostics
src/content/docs/configuration/mqtt.md, src/content/docs/troubleshooting/logs.md
Removed the -i client-id flag from example mosquitto commands, added inline code formatting and an MQTT Explorer hyperlink, and added a note linking to Companion MQTT configuration.
Integrations & Enclosures
src/content/docs/integrations/homebridge.md, src/content/docs/enclosures.md
Expanded Homebridge plugin description to explain occupancy sensor usage; inserted an introductory line for enclosure examples.

Possibly related PRs

🚥 Pre-merge checks | ✅ 3
✅ Passed checks (3 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title 'Rework reading order and small improvements' accurately captures the main objectives of the PR: reorganizing documentation navigation hierarchy and making various documentation updates.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

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

✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Post copyable unit tests in a comment
📝 Coding Plan
  • Generate coding plan for human review comments

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.

Tip

You can customize the tone of the review comments and chat replies.

Configure the tone_instructions setting to customize the tone of the review comments and chat replies. For example, you can set the tone to Act like a strict teacher, Act like a pirate and more.

Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 13

🧹 Nitpick comments (5)
astro.config.mjs (2)

10-11: Double-hop redirect: /base-stations/nodes/hardware/nodes

The pre-existing /base-stations/nodes redirect now chains through the new /nodes/hardware/nodes redirect, causing two round-trips for old bookmark/links. Consider updating the chain to a single hop.

♻️ Proposed fix
-    '/base-stations': '/nodes',
-    '/nodes': '/hardware/nodes',
+    '/base-stations': '/hardware/nodes',
+    '/nodes': '/hardware/nodes',
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@astro.config.mjs` around lines 10 - 11, The redirect chain causes a
double-hop: '/base-stations' currently redirects to '/nodes' which then
redirects to '/hardware/nodes'; update the redirects so '/base-stations' points
directly to '/hardware/nodes' (replace the '/base-stations': '/nodes' entry with
'/base-stations': '/hardware/nodes' or otherwise collapse the chain) and keep or
remove the intermediate '/nodes' -> '/hardware/nodes' mapping as appropriate to
avoid the two-step redirect.

60-67: Mixed tab/space indentation on line 60

The { opening the "Node Configuration" group uses a tab character while all surrounding blocks use spaces. This will cause formatting inconsistencies in editors with tabSize ≠ 8 and may trip linters.

✏️ Proposed fix
-	{
+        {
           label: 'Node Configuration',
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@astro.config.mjs` around lines 60 - 67, The "Node Configuration" object uses
a tab for the opening brace indentation which mixes tabs and spaces; locate the
block with label 'Node Configuration' (the object containing items slugs
'configuration/network', 'configuration/settings', 'configuration/hardware',
'configuration/mqtt') and replace the leading tab with the same number of spaces
used elsewhere in the file to match surrounding indentation and satisfy
linters/editor settings.
src/content/docs/companion/installation.md (1)

45-45: Inconsistent terminology: "Add-ons" vs "Apps" in the same step.

Line 45 directs users to Settings > Add-ons, which is the current Home Assistant UI path, so this is technically correct. However, it may confuse readers given the rest of the document uses "Apps" / "Apps Store" wording. Consider adding a brief parenthetical note to bridge the gap, e.g., Settings > Apps (Add-ons).

🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@src/content/docs/companion/installation.md` at line 45, Update the step text
that currently reads "Settings > Add-ons" to clarify the terminology mismatch
with the rest of the doc by using a combined label such as "Settings > Apps
(Add-ons)" or "Settings > Add-ons (Apps)"; change the literal string "Settings >
Add-ons" in installation.md to include the parenthetical "(Apps)" so readers see
both terms and avoid confusion with the document's "Apps"/"Apps Store" wording.
src/content/docs/index.mdx (1)

36-38: Duplicated note block between index.mdx and approach.mdx.

This exact note text (lines 36-38) is repeated verbatim in approach.mdx (lines 5-7). Consider keeping the detailed note only in approach.mdx and using a shorter summary here with a link, to avoid maintaining the same text in two places.

🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@src/content/docs/index.mdx` around lines 36 - 38, The note block text
duplicated in src/content/docs/index.mdx (the :::note starting at the block
"These are fundamentally different approaches...") is identical to the note in
approach.mdx; replace the full verbatim block in index.mdx with a short one-line
summary and a link to the detailed note in approach.mdx (e.g., "See Approach for
details: link to approach.mdx"), or alternatively remove the block and add a
cross-reference to the approach.mdx section so the canonical detailed note lives
only in approach.mdx.
src/content/docs/companion/troubleshooting.md (1)

14-17: "Add-on" terminology remains throughout this file while installation.md switched to "app".

Lines 14 ("Add-on Not Appearing"), 78 ("add-on logs"), 115 ("reinstall add-on"), and 120–123 still reference "add-on." The installation page now uses "app" uniformly. Consider aligning the terminology here for consistency, or at minimum in the sections that overlap with the installation guide (e.g., Line 120: "Can't see the app" was already updated in installation.md's troubleshooting but this page still says "Add-on Not Appearing").

Also applies to: 78-78, 115-115, 120-123

🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@src/content/docs/companion/troubleshooting.md` around lines 14 - 17, Update
the terminology in troubleshooting.md to match installation.md by replacing
"Add-on" occurrences with "App": rename the heading "Add-on Not Appearing" to
"App Not Appearing", change phrases "add-on logs" and "reinstall add-on" to "app
logs" and "reinstall app", and update the section currently worded like "Can't
see the app" (lines ~120–123) to use the same wording and bullets as
installation.md's troubleshooting; ensure all instances of "add-on" in the
document are normalized to "app" and adjust nearby wording for grammatical
consistency.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.

Inline comments:
In @.gitignore:
- Line 7: Remove "pnpm-lock.yaml" from the .gitignore and add/commit the
pnpm-lock.yaml file to the repository to ensure deterministic installs; locate
the ignored entry "pnpm-lock.yaml" in the .gitignore, delete that line, run pnpm
install to generate or update the lockfile if needed, and commit the resulting
pnpm-lock.yaml; if any developer needs a local-only ignore, instruct them to use
.git/info/exclude instead of the shared .gitignore.

In `@src/content/docs/approach.mdx`:
- Line 9: Change the skipped heading levels by replacing the h3 headings for the
approaches with h2: update the heading "Approach 1: mqtt_room (Simple Room
Presence)" (and the corresponding "Approach 2: ..." heading at the other
location) from "###" to "##" so the document has an h1 title followed by h2
sections; then update the anchor links in index.mdx that point to these approach
headings (the entries referencing the "Approach 1: mqtt_room (Simple Room
Presence)" and "Approach 2: ..." anchors) so they use the new slugs generated by
the h2 headings.

In `@src/content/docs/companion/configuration.md`:
- Around line 317-319: The tip block's text contains a stray space inside the
quoted phrase — find the :::tip block containing the string "Click 'Edit page '
below." and remove the trailing space inside the single quotes (change to "Click
'Edit page' below."), and apply the same fix to the identical occurrence in the
other doc (the tip in companion/optimization.md); ensure there are no trailing
spaces inside the quotes or at line end so the rendered page no longer shows the
extra gap.

In `@src/content/docs/companion/installation.md`:
- Line 47: The markdown has an unmatched backtick in the line "Click the Apps
Store` button"; fix it by making the inline code span balanced (e.g., change the
text to "Click the `Apps Store` button") or remove backticks entirely so the
phrase renders correctly; update the line in the installation.md content
accordingly.
- Line 58: The inline code token and the following word are missing a space:
change the text that currently reads `ESPresense Companion`app so that there is
a space between the inline code and "app" (i.e., `` `ESPresense Companion` app
``) to ensure correct rendering; update the line containing `ESPresense
Companion`app accordingly in the installation instructions.
- Line 27: There is a typo in the image alt text: change the string "Add
ESPresense Appn repository to Home Assistant" to "Add ESPresense App repository
to Home Assistant" by updating the alt attribute value in the Markdown/HTML
snippet (the alt="Add ESPresense Appn repository to Home Assistant" occurrence).
- Around line 84-89: The subheadings under the "## MQTT Setup" section are using
h4 (####) and should be h3 (###) to avoid skipping heading levels; update the
"#### Home Assistant MQTT App" and "#### External MQTT Broker" headings to "###
Home Assistant MQTT App" and "### External MQTT Broker" (and scan the rest of
src/content/docs/companion/installation.md for any other heading level
mismatches to keep the outline/TOC accessible and consistent).

In `@src/content/docs/companion/optimization.md`:
- Around line 118-120: The tip block contains the string "Click 'Edit page '
below." with an extra space before the closing single quote; update the text
inside the tip (the "Click 'Edit page ' below." line) to remove the stray space
so it reads "Click 'Edit page' below." and ensure the same fix is applied
consistently if the identical string appears elsewhere (e.g., the tip block or
any occurrence in companion/configuration.md).

In `@src/content/docs/companion/troubleshooting.md`:
- Line 131: The quoted text contains an unintended trailing space: replace the
string `'Edit page '` with `'Edit page'` in the documentation so the quote has
no trailing space; locate the occurrence of the exact text `'Edit page '` in the
troubleshooting.md content and remove the extra space inside the quotes.

In `@src/content/docs/configuration/mqtt.md`:
- Around line 17-19: The internal link `[Companion
MQTT](`#/companion/installation/`#mqtt-setup)` is starting with `#` so it's
treated as a same-page fragment; update the link target to a proper path or full
hashless fragment (for example replace `#/companion/installation/#mqtt-setup`
with `/companion/installation/#mqtt-setup` or the full absolute URL) so the
browser navigates to the companion installation page and its `#mqtt-setup`
fragment correctly; locate the markdown anchor by the link text `Companion MQTT`
and update only the link URL.

In `@src/content/docs/hardware/firmware.mdx`:
- Around line 15-17: Update the tip copy in the firmware documentation tip block
to fix the typo: change "the above web-based installed does not work on Firefox
or Safari." to "the above web-based installer does not work on Firefox or
Safari." Locate the tip text in src/content/docs/hardware/firmware.mdx (the
:::tip block) and replace "installed" with "installer" so the sentence reads
correctly.
- Line 7: Replace the typo in the firmware documentation: locate the sentence
containing "the above web-based installed does not work" (in the content that
references FirmwareInstaller) and change "installed" to "installer" so the
sentence reads "the above web-based installer does not work"; ensure only the
misspelled word is corrected and punctuation/spacing remains unchanged.

In `@src/content/docs/index.mdx`:
- Line 43: Fix the grammatical mismatch in the docs sentence that currently
reads "such as a supported beacons" in src/content/docs/index.mdx: replace the
phrase with either the singular "a supported beacon" (and keep "phone or watch"
singular) or remove the article and use plurals ("supported beacons, phones, or
watches") so the article/plural agrees; update the line containing that phrase
accordingly.

---

Nitpick comments:
In `@astro.config.mjs`:
- Around line 10-11: The redirect chain causes a double-hop: '/base-stations'
currently redirects to '/nodes' which then redirects to '/hardware/nodes';
update the redirects so '/base-stations' points directly to '/hardware/nodes'
(replace the '/base-stations': '/nodes' entry with '/base-stations':
'/hardware/nodes' or otherwise collapse the chain) and keep or remove the
intermediate '/nodes' -> '/hardware/nodes' mapping as appropriate to avoid the
two-step redirect.
- Around line 60-67: The "Node Configuration" object uses a tab for the opening
brace indentation which mixes tabs and spaces; locate the block with label 'Node
Configuration' (the object containing items slugs 'configuration/network',
'configuration/settings', 'configuration/hardware', 'configuration/mqtt') and
replace the leading tab with the same number of spaces used elsewhere in the
file to match surrounding indentation and satisfy linters/editor settings.

In `@src/content/docs/companion/installation.md`:
- Line 45: Update the step text that currently reads "Settings > Add-ons" to
clarify the terminology mismatch with the rest of the doc by using a combined
label such as "Settings > Apps (Add-ons)" or "Settings > Add-ons (Apps)"; change
the literal string "Settings > Add-ons" in installation.md to include the
parenthetical "(Apps)" so readers see both terms and avoid confusion with the
document's "Apps"/"Apps Store" wording.

In `@src/content/docs/companion/troubleshooting.md`:
- Around line 14-17: Update the terminology in troubleshooting.md to match
installation.md by replacing "Add-on" occurrences with "App": rename the heading
"Add-on Not Appearing" to "App Not Appearing", change phrases "add-on logs" and
"reinstall add-on" to "app logs" and "reinstall app", and update the section
currently worded like "Can't see the app" (lines ~120–123) to use the same
wording and bullets as installation.md's troubleshooting; ensure all instances
of "add-on" in the document are normalized to "app" and adjust nearby wording
for grammatical consistency.

In `@src/content/docs/index.mdx`:
- Around line 36-38: The note block text duplicated in
src/content/docs/index.mdx (the :::note starting at the block "These are
fundamentally different approaches...") is identical to the note in
approach.mdx; replace the full verbatim block in index.mdx with a short one-line
summary and a link to the detailed note in approach.mdx (e.g., "See Approach for
details: link to approach.mdx"), or alternatively remove the block and add a
cross-reference to the approach.mdx section so the canonical detailed note lives
only in approach.mdx.

@sensiebot
Copy link
Copy Markdown
Contributor

sensiebot bot commented Mar 10, 2026

@CoMPaTech and @DTTerastar This PR has changes requested. Please address the feedback and push an update.

@CoMPaTech
Copy link
Copy Markdown
Contributor Author

@sensiebot we are just waiting for @DTTerastar

Copy link
Copy Markdown
Contributor

@DTTerastar DTTerastar left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Great structural improvements overall — the new navigation hierarchy is much cleaner and the Approaches page is well done. A few things to fix before merging:

Required fixes

1. /hardware 404
The old '/hardware': '/nodes' redirect was removed without a replacement. Anything linking to /hardware now 404s. Add to astro.config.mjs:

'/hardware': '/hardware/nodes',

2. Heading level inconsistency in companion/installation.md
Under the MQTT Setup section, "Home Assistant MQTT App" is #### (h4) while "External MQTT Broker" is ### (h3) — sibling sections should be the same level. Promote "Home Assistant MQTT App" to ###.

3. Merge conflict with nodes.md
The branch is based on the pre-affiliate-link version of nodes.md (index 5f520b2). The main branch now has AliExpress links added for ESP32-C3-DevKitM-1U, Teyleten Robot, USB C charger, and USB C-to-C cable. When merging, please rebase on main and carry those changes over to hardware/nodes.md.

Minor

  • companion/troubleshooting.md still has ### Add-on Not Appearing — inconsistent with the "app" rename throughout installation.md
  • configuration/mqtt.md: fixed presenscepresense, but presense is still misspelled (should be presence)
  • astro.config.mjs: the "Node Configuration" sidebar block uses a tab character instead of spaces (line with {)

Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1

🧹 Nitpick comments (1)
src/content/docs/hardware/nodes.md (1)

47-69: Consider consistent hyphenation in USB headings.

The section headings use inconsistent hyphenation — "USB-A to Micro-B cables" (line 69) uses hyphens while other headings like "USB C chargers" and "USB A to C cables" do not.

✏️ Optional consistency fix
-## USB C chargers
+## USB-C chargers
...
-## USB C to C cables
+## USB-C to USB-C cables
...
-## USB A chargers
+## USB-A chargers
...
-## USB A to C cables
+## USB-A to USB-C cables
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@src/content/docs/hardware/nodes.md` around lines 47 - 69, Headings in this
doc use inconsistent hyphenation (e.g., "USB C chargers" and "USB A to C cables"
vs "USB-A to Micro-B cables"); pick a consistent style (either always hyphenate
USB-A/USB-C or never hyphenate) and apply it across all section titles such as
"USB C chargers", "USB C to C cables", "USB A chargers", "USB A to C cables",
and "USB-A to Micro-B cables" so the headings match; update each heading text to
the chosen convention throughout the snippet.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@astro.config.mjs`:
- Around line 10-14: The mapping for '/base-stations' creates a redirect chain
because '/base-stations' currently points to '/nodes' while '/nodes' now
redirects to '/hardware/nodes'; update the '/base-stations' entry to point
directly to '/hardware/nodes' (replace the '/base-stations': '/nodes' mapping
with '/base-stations': '/hardware/nodes') so '/base-stations' resolves to the
canonical path without an extra redirect.

---

Nitpick comments:
In `@src/content/docs/hardware/nodes.md`:
- Around line 47-69: Headings in this doc use inconsistent hyphenation (e.g.,
"USB C chargers" and "USB A to C cables" vs "USB-A to Micro-B cables"); pick a
consistent style (either always hyphenate USB-A/USB-C or never hyphenate) and
apply it across all section titles such as "USB C chargers", "USB C to C
cables", "USB A chargers", "USB A to C cables", and "USB-A to Micro-B cables" so
the headings match; update each heading text to the chosen convention throughout
the snippet.
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 3b176fee-5511-47dd-805e-d029bcf4535c

📥 Commits

Reviewing files that changed from the base of the PR and between 529f1f2 and 55ec64e.

📒 Files selected for processing (10)
  • .gitignore
  • astro.config.mjs
  • src/content/docs/approach.mdx
  • src/content/docs/companion/configuration.md
  • src/content/docs/companion/installation.md
  • src/content/docs/companion/optimization.md
  • src/content/docs/companion/troubleshooting.md
  • src/content/docs/configuration/mqtt.md
  • src/content/docs/hardware/firmware.mdx
  • src/content/docs/hardware/nodes.md
✅ Files skipped from review due to trivial changes (1)
  • src/content/docs/companion/configuration.md
🚧 Files skipped from review as they are similar to previous changes (5)
  • src/content/docs/companion/optimization.md
  • src/content/docs/companion/troubleshooting.md
  • src/content/docs/configuration/mqtt.md
  • src/content/docs/approach.mdx
  • .gitignore

CoMPaTech and others added 9 commits March 15, 2026 17:10
- Add /hardware -> /hardware/nodes redirect
- Fix tab indentation in astro.config.mjs
- Promote MQTT App heading from h4 to h3 in companion/installation.md
- Rename "Add-on Not Appearing" to "App Not Appearing" in troubleshooting.md
- Fix presense -> presence typo in mqtt.md
- Add AliExpress affiliate links to hardware/nodes.md (sync from main)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- /base-stations now redirects directly to /hardware/nodes (avoids chain via /nodes)
- Fix grammar: "a supported beacons" → "a supported beacon, phone, or watch"

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🧹 Nitpick comments (1)
src/content/docs/index.mdx (1)

42-42: Use canonical docs path for Nodes link.

Line 42 still points to /nodes; it works only through redirect (astro.config.mjs Line 12). Link directly to /hardware/nodes to avoid stale internal links and extra redirect hops.

✏️ Proposed fix
-* One or more ESP [Nodes](/nodes), depending on your approach
+* One or more ESP [Nodes](/hardware/nodes), depending on your approach
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@src/content/docs/index.mdx` at line 42, Update the internal link target in
the docs content that currently points to "/nodes" so it uses the canonical path
"/hardware/nodes"; specifically edit the line containing the link text "One or
more ESP [Nodes](/nodes)" to reference "/hardware/nodes" instead, ensuring the
visible link label "Nodes" remains unchanged so no redirect is required.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.

Nitpick comments:
In `@src/content/docs/index.mdx`:
- Line 42: Update the internal link target in the docs content that currently
points to "/nodes" so it uses the canonical path "/hardware/nodes"; specifically
edit the line containing the link text "One or more ESP [Nodes](/nodes)" to
reference "/hardware/nodes" instead, ensuring the visible link label "Nodes"
remains unchanged so no redirect is required.

ℹ️ Review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 94fcf94d-6501-4176-9dce-cd9ceae9435a

📥 Commits

Reviewing files that changed from the base of the PR and between 55ec64e and a29a64f.

📒 Files selected for processing (2)
  • astro.config.mjs
  • src/content/docs/index.mdx

DTTerastar and others added 3 commits March 15, 2026 17:17
The -i flag is optional; mosquitto auto-generates a client ID without it.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Files were moved to hardware/ by the PR but this changes URLs unnecessarily.
Moving them back preserves /nodes, /firmware, /enclosures with no redirects needed.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Avoids the redundant "Nodes > Nodes" label, consistent with Companion > Overview.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@DTTerastar
Copy link
Copy Markdown
Contributor

URL Impact

No URLs changed in this PR. All existing links continue to work:

Old URL Destination Notes
/nodes /nodes unchanged
/firmware /firmware unchanged
/enclosures /enclosures unchanged
/base-stations /nodes redirect (pre-existing)
/hardware /nodes redirect (pre-existing)
/install /firmware redirect (pre-existing)

Files were briefly reorganized into a hardware/ subdirectory during review, but reverted to preserve original URLs and avoid SEO impact.

@DTTerastar
Copy link
Copy Markdown
Contributor

Review findings:

  1. Medium: src/content/docs/companion/installation.md:11 removes the old HAOS qualifier and now recommends installing the Companion "as an App within Home Assistant" generically. Home Assistant's current docs say the Apps panel is only available on Home Assistant OS installs, so users on other install types will be sent into a dead end. Source: https://www.home-assistant.io/apps

  2. Low: src/content/docs/companion/installation.md:45 is internally contradictory: it says "Navigate to Apps" but the path is still Settings > Add-ons. On current Home Assistant the menu is Settings > Apps, so this step is wrong for the UI the rest of the page is describing. Source: https://www.home-assistant.io/apps

  3. Low: src/content/docs/companion/installation.md:63 demotes Containerized Deployment to an h3 under ## Home Assistant App. That makes the TOC and heading hierarchy present Docker as a sub-step of the HA app flow instead of a peer deployment option, which is a navigation regression.

npm run build passes, so I didn't see any build-time route or MDX failures beyond the documentation issues above.

- Clarify App install is for Home Assistant OS only
- Fix navigation path: Settings > Add-ons → Settings > Apps
- Promote Containerized Deployment to h2 (peer of HA App, not sub-step)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 2

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)
src/content/docs/companion/troubleshooting.md (1)

78-78: ⚠️ Potential issue | 🟡 Minor

Inconsistent terminology: "add-on" should be "app".

Line 78 still uses "add-on" terminology ("Check add-on logs") which contradicts the App-centric terminology update applied elsewhere in this PR. This should be updated for consistency.

✏️ Proposed fix
-- Home Assistant add-on: Check add-on logs
+- Home Assistant app: Check app logs
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@src/content/docs/companion/troubleshooting.md` at line 78, Update the
inconsistent terminology in the troubleshooting text by replacing the phrase
"Check add-on logs" with "Check app logs" (or "Check companion app logs" if that
better matches surrounding phrasing) in the string "Check add-on logs" within
the troubleshooting.md content so it uses "app" consistently with the rest of
the PR.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@src/content/docs/companion/installation.md`:
- Around line 11-12: Update the installation text in installation.md so the
"Recommended: As an [App](`#home-assistant-app`) within Home Assistant OS" line
explicitly states that the Apps panel (formerly Add-ons) is only available on
Home Assistant OS (HAOS), e.g. change the recommendation to indicate HAOS is
required to use the Apps panel; also add a short clarifying sentence near the
"Optional: As a (composed) [container](`#containerized-deployment`) elsewhere"
line explaining that users on Container, Core, or Supervised must use the
containerized deployment instead (or enable the appropriate supervisor) so they
aren’t confused when they don’t see the Apps option.

In `@src/content/docs/troubleshooting/logs.md`:
- Line 75: The mosquitto_sub example is inconsistent: one doc uses the -i
presence-information client-id while the troubleshooting example omits -i;
update the mqtt configuration doc entries that contain the '-i
presence-information' flag to match the troubleshooting example by removing the
'-i' client-id option (or alternatively add '-i presence-information' back into
the troubleshooting example)—locate occurrences of the mosquitto_sub command and
the literal '-i presence-information' and make them consistent across docs.

---

Outside diff comments:
In `@src/content/docs/companion/troubleshooting.md`:
- Line 78: Update the inconsistent terminology in the troubleshooting text by
replacing the phrase "Check add-on logs" with "Check app logs" (or "Check
companion app logs" if that better matches surrounding phrasing) in the string
"Check add-on logs" within the troubleshooting.md content so it uses "app"
consistently with the rest of the PR.
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: fbb412bf-fba8-48d3-bc0d-66b787a525a2

📥 Commits

Reviewing files that changed from the base of the PR and between a29a64f and 38474e6.

📒 Files selected for processing (14)
  • astro.config.mjs
  • src/content/docs/approach.mdx
  • src/content/docs/companion/configuration.md
  • src/content/docs/companion/installation.md
  • src/content/docs/companion/optimization.md
  • src/content/docs/companion/troubleshooting.md
  • src/content/docs/configuration/mqtt.md
  • src/content/docs/devices.md
  • src/content/docs/enclosures.md
  • src/content/docs/firmware.mdx
  • src/content/docs/index.mdx
  • src/content/docs/integrations/homebridge.md
  • src/content/docs/nodes.md
  • src/content/docs/troubleshooting/logs.md
✅ Files skipped from review due to trivial changes (3)
  • src/content/docs/nodes.md
  • src/content/docs/enclosures.md
  • src/content/docs/companion/optimization.md
🚧 Files skipped from review as they are similar to previous changes (6)
  • src/content/docs/companion/configuration.md
  • src/content/docs/approach.mdx
  • src/content/docs/integrations/homebridge.md
  • src/content/docs/devices.md
  • astro.config.mjs
  • src/content/docs/configuration/mqtt.md

@CoMPaTech
Copy link
Copy Markdown
Contributor Author

CoMPaTech commented Mar 16, 2026

  1. Medium: src/content/docs/companion/installation.md:11 removes the old HAOS qualifier and now recommends installing the Companion "as an App within Home Assistant" generically. Home Assistant's current docs say the Apps panel is only available on Home Assistant OS installs, so users on other install types will be sent into a dead end. Source: https://www.home-assistant.io/apps
  2. Low: src/content/docs/companion/installation.md:45 is internally contradictory: it says "Navigate to Apps" but the path is still Settings > Add-ons. On current Home Assistant the menu is Settings > Apps, so this step is wrong for the UI the rest of the page is describing. Source: https://www.home-assistant.io/apps
  3. Low: src/content/docs/companion/installation.md:63 demotes Containerized Deployment to an h3 under ## Home Assistant App. That makes the TOC and heading hierarchy present Docker as a sub-step of the HA app flow instead of a peer deployment option, which is a navigation regression.

I've re-demoted H3 as it's the third option. I.e. one can click the buttons, do the work manually or 'host the companion somewhere containerized'.

npm run build passes, so I didn't see any build-time route or MDX failures beyond the documentation issues above.

I use nvm + pnpm with preview to locally review :)

@DTTerastar DTTerastar merged commit b51752b into ESPresense:main Mar 16, 2026
1 check passed
@DTTerastar
Copy link
Copy Markdown
Contributor

It's live!

@CoMPaTech
Copy link
Copy Markdown
Contributor Author

Nice work, glad you liked the contribution!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants