Fix components.json and api ref urls for beta/next#5348
Conversation
There was a problem hiding this comment.
Pull Request Overview
Fixes configuration issues for components.json generation and API reference URLs across different deployment environments (beta/next). The changes ensure proper URL handling for different build contexts by switching from generic environment variables to Hugo-specific ones.
- Updates environment variable naming in netlify.toml to use Hugo-prefixed variables
- Creates components.json layout template to generate component data with proper base URLs
- Configures Hugo to output components.json format and minor formatting fixes
Reviewed Changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.
| File | Description |
|---|---|
| themes/esphome-theme/layouts/index.componentsjson | New template for generating components.json with proper URL handling |
| netlify.toml | Updates environment variables to Hugo-specific format and removes unused context |
| hugo.yaml | Adds ComponentsJSON output format and fixes formatting |
| {{- $components := dict -}} | ||
| {{- $baseURL := .Site.BaseURL -}} | ||
| {{- if eq $baseURL "" -}} | ||
| {{- $baseURL = "https://esphome.io" -}} |
There was a problem hiding this comment.
The hardcoded fallback URL 'https://esphome.io' should be configurable or use a site parameter to avoid maintenance issues when the default domain changes.
| {{- $baseURL = "https://esphome.io" -}} | |
| {{- if .Site.Params.fallbackBaseURL -}} | |
| {{- $baseURL = .Site.Params.fallbackBaseURL -}} | |
| {{- else -}} | |
| {{- $baseURL = "https://esphome.io" -}} | |
| {{- end -}} |
| {{- end -}} | ||
|
|
||
| {{- with .Params.seo.image -}} | ||
| {{- $image = printf "%simages/%s" $baseURL . -}} |
There was a problem hiding this comment.
The image URL construction assumes $baseURL doesn't end with a slash. This could create malformed URLs like 'https://example.com//images/file.png' if $baseURL includes a trailing slash.
✅ Deploy Preview for esphome ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
|
Note Other AI code review bot(s) detectedCodeRabbit has detected other AI code review bot(s) in this pull request and will avoid duplicating their findings in the review comments. This may lead to a less comprehensive review. WalkthroughAdds a ComponentsJSON Hugo output format and enables it on the home output, adds a template that emits a pretty-printed components.json from pages under /components, and updates Netlify config: renames build/context env vars, removes one context, and generalizes several redirect-from patterns to wildcards. Changes
Sequence Diagram(s)sequenceDiagram
autonumber
participant Hugo as Hugo Build
participant Tmpl as index.componentsjson
participant FS as Public Dir
rect rgba(200,220,255,0.25)
Hugo->>Tmpl: Render ComponentsJSON output (outputs.home)
Tmpl->>Tmpl: Iterate .Site.Pages filtering "/components/"
Tmpl->>Tmpl: Compute key, path, optional image, merge into map
Tmpl-->>Hugo: Return components.json (pretty JSON)
Hugo->>FS: Write /components.json to public root
end
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Suggested reviewers
Pre-merge checks (2 passed, 1 inconclusive)❌ Failed checks (1 inconclusive)
✅ Passed checks (2 passed)
Tip 👮 Agentic pre-merge checks are now available in preview!Pro plan users can now enable pre-merge checks in their settings to enforce checklists before merging PRs.
Please see the documentation for more information. Example: reviews:
pre_merge_checks:
custom_checks:
- name: "Undocumented Breaking Changes"
mode: "warning"
instructions: |
Pass/fail criteria: All breaking changes to public APIs, CLI flags, environment variables, configuration keys, database schemas, or HTTP/GraphQL endpoints must be documented in the "Breaking Change" section of the PR description and in CHANGELOG.md. Exclude purely internal or private changes (e.g., code not exported from package entry points or explicitly marked as internal).Please share your feedback with us on this Discord post. ✨ Finishing Touches🧪 Generate unit tests
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}
There was a problem hiding this comment.
Actionable comments posted: 1
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
netlify.toml (1)
47-49: Fix broken /api/ redirect — placeholder not populated*Verified: no sed in Makefile replaces {{API_DOCS_URL}}; netlify.toml still has
to = "{{API_DOCS_URL}}/:splat"(line 48); env blocks defineHUGOxPARAMSxAPI_DOCS_URLbut notAPI_DOCS_URL(lines 4,7,10,13). Redirects will fail.Two minimal fixes — pick one:
- Replace the redirect to use the existing var: change line 48 to
to = "{{HUGOxPARAMSxAPI_DOCS_URL}}/:splat".- Or reintroduce
API_DOCS_URLin the Netlify env blocks (addAPI_DOCS_URL = "<matching URL>"in [build], [context.beta], [context.next], [context.production]) so the current placeholder resolves.
🧹 Nitpick comments (3)
themes/esphome-theme/layouts/index.componentsjson (3)
7-8: Limit to regular content pages under the components sectionUsing .Site.Pages + substring match can include non-regular pages. Prefer RegularPages and the Section filter; it naturally excludes sections/_index.
-{{- range .Site.Pages -}} - {{- if and (in .RelPermalink "/components/") (ne .Kind "section") (ne .File.BaseFileName "_index") -}} +{{- range where .Site.RegularPages "Section" "components" -}} + {{- /* RegularPages excludes sections and _index automatically */ -}}
9-11: Remove unused variable$relPath is computed but never used. Safe to drop.
- {{- $relPath := strings.TrimPrefix "/components/" .RelPermalink -}} - {{- $relPath = strings.TrimSuffix "/" $relPath -}}
16-27: Guard against missing .Parent.File on section parentsSome section parents may not have a File; accessing .Parent.File.BaseFileName can be empty. Add a defensive with to avoid surprises.
- {{- if .Parent -}} - {{- if ne .Parent.File.BaseFileName "_index" -}} - {{- $key = printf "%s_%s" .Parent.File.BaseFileName .File.BaseFileName -}} - {{- $path = printf "components/%s" .Parent.File.BaseFileName -}} - {{- else -}} + {{- if .Parent -}} + {{- with .Parent.File -}} + {{- if ne .BaseFileName "_index" -}} + {{- $key = printf "%s_%s" .BaseFileName $.File.BaseFileName -}} + {{- $path = printf "components/%s" .BaseFileName -}} + {{- else -}} + {{- $key = $.File.BaseFileName -}} + {{- $path = printf "components/%s" $.File.BaseFileName -}} + {{- end -}} + {{- else -}} {{- $key = .File.BaseFileName -}} {{- $path = printf "components/%s" .File.BaseFileName -}} - {{- end -}} + {{- end -}}
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (3)
hugo.yaml(2 hunks)netlify.toml(3 hunks)themes/esphome-theme/layouts/index.componentsjson(1 hunks)
🧰 Additional context used
📓 Path-based instructions (1)
**
⚙️ CodeRabbit configuration file
- Do not generate or add any sequence diagrams
Files:
hugo.yamlnetlify.tomlthemes/esphome-theme/layouts/index.componentsjson
🧠 Learnings (1)
📓 Common learnings
Learnt from: CR
PR: esphome/esphome-docs#0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-08-24T00:13:13.459Z
Learning: Open pull requests against the correct base branch: use `current` for documentation-only revisions and `next` for changes tied to new features in esphome/esphome
🔇 Additional comments (7)
hugo.yaml (3)
149-154: Registering ComponentsJSON on home output looks goodThis will emit /components.json from the home node as intended, given the matching index.componentsjson template.
156-158: No functional change in staticDirWhitespace-only tweak; nothing to do.
169-175: Output format definition is correct; keep name in sync with template suffixThe format name ComponentsJSON matches the template suffix index.componentsjson, mediaType is JSON, and path "" targets site root. All good.
netlify.toml (4)
4-4: Env rename aligns with Hugo conventionsHUGO_BASEURL and HUGOxPARAMSxAPI_DOCS_URL look good; versions unchanged.
6-14: Context env renames look consistentbeta/next/production now set the new keys; values look correct.
96-109: Wildcard “from” patterns are a useful broadeningCovers both .html and extension-less variants; destinations look correct.
77-78: Whitespace-only changeNo action needed.
There was a problem hiding this comment.
Actionable comments posted: 2
♻️ Duplicate comments (2)
themes/esphome-theme/layouts/index.componentsjson (2)
2-5: Drop manual BaseURL fallback; rely on absURL instead.Hardcoding a fallback and concatenating strings is brittle across environments;
absURL(withurls.JoinPathwhen needed) handles slashes and base changes.-{{- $baseURL := .Site.BaseURL -}} -{{- if eq $baseURL "" -}} - {{- $baseURL = "https://esphome.io" -}} -{{- end -}}
37-39: Fix image URL construction (double “images” and slash issues).Use
absURLandurls.JoinPath; handle already-absolute values.- {{- with .Params.seo.image -}} - {{- $image = printf "%simages/%s" $baseURL . -}} - {{- end -}} + {{- with .Params.seo.image -}} + {{- $img := . -}} + {{- if and (not (hasPrefix $img "/")) (not (hasPrefix $img "http")) -}} + {{- $img = (urls.JoinPath "images" $img) -}} + {{- end -}} + {{- $image = ($img | absURL) -}} + {{- end -}}
🧹 Nitpick comments (3)
themes/esphome-theme/layouts/index.componentsjson (3)
7-8: Filter pages by section instead of substring match.More precise and faster; also removes the extra
ifblock.-{{- range .Site.Pages -}} - {{- if (in .RelPermalink "/components/") -}} +{{- range where .Site.RegularPages "Section" "components" -}} @@ - {{- end -}}Also applies to: 49-49
41-45: Avoid emitting empty “image” keys.Only add the field when present to keep JSON clean.
- {{- $component := dict - "title" .Title - "url" .Permalink - "path" $path - "image" $image -}} + {{- $component := dict "title" .Title "url" .Permalink "path" $path -}} + {{- with $image -}} + {{- $component = merge $component (dict "image" .) -}} + {{- end -}}
9-11: Derive path parts from file metadata, not URL strings (optional).Using
.File.Dir/.File.BaseFileNameavoids edge cases with.RelPermalinkformatting.Example (for reference, not a full patch):
{{- $dir := trim (replace .File.Dir "components/" "" 1) "/" -}} {{- $pathParts := split $dir "/" -}}Also applies to: 17-17
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
themes/esphome-theme/layouts/index.componentsjson(1 hunks)
🧰 Additional context used
📓 Path-based instructions (1)
**
⚙️ CodeRabbit configuration file
- Do not generate or add any sequence diagrams
Files:
themes/esphome-theme/layouts/index.componentsjson
🧠 Learnings (1)
📓 Common learnings
Learnt from: CR
PR: esphome/esphome-docs#0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-08-24T00:13:13.459Z
Learning: Open pull requests against the correct base branch: use `current` for documentation-only revisions and `next` for changes tied to new features in esphome/esphome
Learnt from: jesserockz
PR: esphome/esphome-docs#4865
File: .github/workflows/needs-docs.yml:0-0
Timestamp: 2025-05-01T03:29:47.922Z
Learning: In the esphome-docs repository, the "current" label is automatically added by a bot to pull requests, making it a reliable indicator for the target branch.
Description:
Related issue (if applicable): fixes
Pull request in esphome with YAML changes (if applicable):
Checklist:
I am merging into
nextbecause this is new documentation that has a matching pull-request in esphome as linked above.or
I am merging into
currentbecause this is a fix, change and/or adjustment in the current documentation and is not for a new component or feature.Link added in
/components/index.rstwhen creating new documents for new components or cookbook.New Component Images
If you are adding a new component to ESPHome, you can automatically generate a standardized black and white component name image for the documentation.
To generate a component image:
Comment on this pull request with the following command, replacing
COMPONENT_NAMEwith your component name in UPPER_CASE format with underscores (e.g.,BME280,SHT3X,DALLAS_TEMP):The ESPHome bot will respond with a downloadable ZIP file containing the SVG image.
Extract the SVG file and place it in the
images/folder of this repository.Use the image in your component's index table entry in
/components/index.rst.Example: For a component called "DHT22 Temperature Sensor", use: