Rework reading order and small improvements#270
Open
CoMPaTech wants to merge 6 commits intoESPresense:mainfrom
Open
Rework reading order and small improvements#270CoMPaTech wants to merge 6 commits intoESPresense:mainfrom
CoMPaTech wants to merge 6 commits intoESPresense:mainfrom
Conversation
Contributor
WalkthroughRestructures documentation navigation and content organization, consolidates hardware-related redirect paths and sidebar sections, updates deployment terminology from add-on to app-centric approach, refactors homepage and introduction content, and fixes documentation formatting and typos. Changes
Possibly related PRs
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches
🧪 Generate unit tests (beta)
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. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 13
🧹 Nitpick comments (5)
astro.config.mjs (2)
10-11: Double-hop redirect:/base-stations→/nodes→/hardware/nodesThe pre-existing
/base-stations→/nodesredirect now chains through the new/nodes→/hardware/nodesredirect, 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 60The
{opening the "Node Configuration" group uses a tab character while all surrounding blocks use spaces. This will cause formatting inconsistencies in editors withtabSize≠ 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 betweenindex.mdxandapproach.mdx.This exact note text (lines 36-38) is repeated verbatim in
approach.mdx(lines 5-7). Consider keeping the detailed note only inapproach.mdxand 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 whileinstallation.mdswitched 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.
| .DS_Store | ||
| .omc/ | ||
| .playwright-cli/ | ||
| pnpm-lock.yaml |
Contributor
There was a problem hiding this comment.
Committing pnpm-lock.yaml is strongly recommended for an application/site.
Adding pnpm-lock.yaml to .gitignore discards the reproducibility and supply-chain integrity guarantees that lock files provide. Without it, pnpm install will resolve the latest semver-compatible versions at each point in time, meaning different developers and CI runs can silently receive different (potentially broken or vulnerable) dependency trees.
Ignoring lock files is only defensible for publishable npm libraries, where pinning transitive dependencies would conflict with consumer projects. This repository is a documentation website, so the lock file should be committed.
🛡️ Proposed fix
-pnpm-lock.yamlCommit pnpm-lock.yaml to the repository instead of ignoring it. If there are local developer-specific reasons for regenerating the lock file, those should be handled by individual .git/info/exclude entries rather than the shared .gitignore.
📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| pnpm-lock.yaml |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In @.gitignore at 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.
Author
There was a problem hiding this comment.
@DTTerastar leaving that to you if we want it or not, let me know
Contributor
There was a problem hiding this comment.
Seems like the humans are having a chat. I'll hop back into my burrow for now. If you need me again, just tag @coderabbitai in a new comment, and I'll come hopping out!
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Sidebar from local generation:
Summary by CodeRabbit
Release Notes
Documentation
Bug Fixes