Remove redundant header from API reference pages#25235
Conversation
The API reference layout rendered a custom header above the ReDoc explorer with a duplicate title/description and "Open Markdown" / "Download OpenAPI specification" links. ReDoc already renders the title and description from the spec, so this header was redundant. Remove the header section and its now-unused CSS, keeping the non-visible <link rel="alternate"> discovery metadata in the head. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
✅ Deploy Preview for docsdocker ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
docker-agent
left a comment
docker-agent
left a comment
There was a problem hiding this comment.
Assessment: 🟡 NEEDS ATTENTION
This PR removes the api-shell header section (title, description, and action links) from the API reference layout, relying on ReDoc to render the spec's own title and description. The <link rel="alternate"> discovery metadata in <head> is correctly preserved. Two medium-severity UX concerns are flagged below.
| > | ||
| </li> | ||
| </ul> | ||
| <noscript> |
There was a problem hiding this comment.
[MEDIUM] noscript fallback guidance removed — JS-disabled users see a blank page with no alternative
The removed section included a <noscript> block that directed users with JavaScript disabled to the Markdown page or OpenAPI download as alternatives to the interactive ReDoc explorer. Without it, a JS-disabled user now sees only an empty <article class="redoc-container"> with no content and no instructions.
The <link rel="alternate"> head tags are parsed by browsers/tools but are invisible to a human reading the page. Consider adding a minimal <noscript> notice elsewhere in the template (e.g., inside the redoc-container article) to preserve this accessibility fallback.
There was a problem hiding this comment.
Thanks for confirming! Since the entire .api-shell section is being removed (which makes sense if you're simplifying the layout), the <noscript> could be reintroduced inside the redoc-container article itself. Something like:
<article class="redoc-container">
<noscript>
<p style="padding: 2rem; max-width: 72ch;">
This reference uses JavaScript for the interactive explorer.
View the <a href="{{ partial "utils/markdown-url.html" . }}">Markdown page</a>
or <a href="{{ $specURL.String | absURL }}">download the OpenAPI specification</a>
if JavaScript is unavailable.
</p>
</noscript>
{{ if or (strings.HasPrefix .RelPermalink "/reference/api/hub/") ... }}This keeps the accessibility fallback without bringing back the removed header section.
There was a problem hiding this comment.
Great, thanks for restoring it! That strikes a good balance — keeping the cleaner layout you wanted while preserving the accessibility fallback for JS-disabled users. The placement inside redoc-container makes sense since that's exactly where the content would otherwise be missing.
Marking this as resolved.
There was a problem hiding this comment.
"JS-disabled users", what a weird phrase :-D
Keep the JavaScript-disabled fallback guidance (originally added in docker#23944) by reintroducing a <noscript> block inside the redoc-container article, with links to the Markdown page and OpenAPI spec. The visible header and its action links remain removed. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
thaJeztah
left a comment
thaJeztah
left a comment
There was a problem hiding this comment.
LGTM; perhaps squash the commits?
4 participants
Summary
The API reference layout (
layouts/api.html) rendered a custom header above the ReDoc explorer with a duplicate title/description and Open Markdown / Download OpenAPI specification links. ReDoc already renders the title and description from the spec, so this header was redundant. This removes the header section and its now-unused CSS, while keeping the non-visible<link rel="alternate">discovery metadata in the<head>.Affects all API reference pages using the
layout: apicascade (Engine, Hub, Registry, etc.).Generated by Claude Code