Strapi Docs "v7" full redesign#3281
Draft
pwizla wants to merge 201 commits into
Draft
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
github-actions
Bot
added
internal
PR #3275 normalised the example documentId values (24 chars) in document-service.md and use-document-id.md on main. document-service.md was reconstructed into <Endpoint kind="js"> on this branch, so the values are ported manually; use-document-id.md is taken verbatim from main.
PR #3275 normalised all example documentId values to 24 chars but left the discardDraft() request codeTab at 23. Aligns it to the canonical a1b2c3d4e5f6g7h8i9j0klmn so the whole page is consistent.
Teach <Endpoint> (kind http/js) instead of the legacy <ApiCall>/<Request>/<Response> trio across the API guide, template, and drafter prompt; add endpoint/step-details/next-steps component guides; add a known-pitfalls guardrail; fix dead templates/INDEX.md references.
<Endpoint> and <StepDetails> are registered as global MDX components, so the explicit import lines on these API and quick-start pages were redundant. The component usage is unchanged.
ApiDocLayout was the first-draft 2-column API wrapper, replaced by <Endpoint> and never used in any docs page. Removes the component and its global MDX registration.
Removed the <NotV5/> 'not up-to-date with Strapi 5 yet' callout (and its now-unused import) from the Understanding populate guide.
The 11 endpoints on the Understanding populate guide have long JSON responses (46-143 lines). Added an opt-in collapsibleResponse prop to <Endpoint> (passed to ResponsePanel): when set and the response exceeds 10 lines, the response is clipped to ~220px behind a fade with a Show more / Show less toggle. Enabled it on all 11 endpoints of this page only; the prop defaults to off, so other API pages are unchanged. Verified responses collapse to 220px and expand on click.
All backend-customization/examples pages used the deprecated Entity Service API. Migrated every call to the Document Service API following the official migration guide (from-entity-service-to-document-service): findOne(uid, id) -> documents(uid).findOne({documentId}), findMany(uid, params) -> documents(uid).findMany(params), create(uid, {data}) -> documents(uid).create({data}). The Email single type lookup (findOne(uid, 1)) became documents(uid).findFirst() per the single-type guidance, and a related-entry link now uses documentId instead of id. Updated all 'Entity Service API' prose and links to 'Document Service API'. 6 calls migrated across 3 files; build passes.
Navbar breadcrumbs rendered plain anchor links, triggering full page reloads that reset the view mode (notably losing AI mode, which is not persisted in localStorage by design). Intercept same-origin breadcrumb clicks and navigate through the SPA router instead, keeping React state and the current view mode intact.
On <Endpoint> pages, _base.scss caps prose at 50% width (70% wide, 100% max) and left-flushes it to align with the left column of the 2-column endpoint layout. Markdown mode linearizes that layout to a single full-width column, so the half-width cap had nothing to align with: prose and admonitions (which keep margin:auto) were squeezed into the left half of the column and visually misaligned. Restore normal centered content-width behavior for these pages in Markdown mode only, scoped to [data-view-mode=markdown] main:has(.api-endpoint-block), so elegant and AI modes are unaffected.
…wn mode The previous alignment fix targeted '> details', but Markdown mode flattens <details> with 'display: contents', so the element has no box and the constraint was a no-op. Its summary and content wrapper become direct flow children and spilled to the full column width instead of the selected content width. Constrain those children directly so the collapsible block (e.g. 'Plural API ID vs. Singular API ID' under Endpoints on /cms/api/rest) respects narrow/wide/max like the rest of the page.
… width The params-left/code-right layout on <Endpoint> pages (rest, document-service) only reads well when there is horizontal room for it. At the narrow content width the two columns were too cramped, and the surrounding prose stayed flush-left at half-width while the endpoints sat in two columns, looking misaligned. In AI mode the endpoints were forced into two columns inside a ~half-viewport area, which was barely legible. Now: - Narrow width (elegant): endpoints collapse to one column (params above code) and all prose is centered to the content width, like a normal doc page. - Wide / max width (elegant): the 2-column layout is restored and prose returns to its flush-left reduced width to align with the left column. - AI mode: endpoints are always single-column regardless of the stored width, with prose following the full content width. Scoped to .api-endpoint-block--columns, so code-only Endpoint pages and legacy <ApiCall> (GraphQL, upload) pages are unaffected.
…aphQL
The next/prev pagination buttons used the short sidebar labels
('Documentation', 'GraphQL'), which were ambiguous out of context. Add a
pagination_label to each page's frontmatter so the buttons read
'Documentation plugin' / 'GraphQL plugin' while the sidebar keeps the
short labels.
- Give the 'Strapi plugins' sidebar category a generated-index link at /cms/plugins, so the 'plugins' breadcrumb segment resolves to a real listing page instead of a 404. - Append 'Click on any item to explore the topic.' to the intro sentence on every generated-index page (swizzled DocCategoryGeneratedIndexPage), so the auto-generated listing pages invite navigation.
The flush-left reduced-width prose at wide/max looked like awkwardly off-center content next to the full-width endpoint blocks. Center it instead (equal margins) at a comfortable reading width, so prose and endpoints share the same centerline while endpoints still break out to the full column width.
On API pages the article is full-width, so the page chrome outside the markdown body (feedback widget, tags footer, previous/next pagination) spanned the full width while the content was centered, looking misaligned. Constrain all three to the content width, centered. The pagination lives in the unpadded container outside <article>, so its cap subtracts the article's 16px horizontal padding to line up with the feedback/tags. Applies to both <Endpoint> and <ApiCall> pages (rest, document-service, graphql, etc.) across narrow/wide/max.
Point the OpenAPI page's pagination to its natural sidebar neighbors: previous -> Strapi Client, next -> GraphQL API (was previous -> Document, next -> REST API).
… pages Make the 2-column <Endpoint> blocks share the exact same width as the surrounding text at every content width, instead of always breaking out to the full column: - narrow: both at the readable width, centered (unchanged) - wide: both at the 70% reading measure, centered (endpoints no longer spill wider than the text) - max: both fill the full column width (dropped the 960px prose cap that left text cramped next to full-width endpoints on large screens) Verified prose and endpoints are identical width/offset at all three widths on rest and document-service; chrome, markdown and AI modes unaffected.
…lbar Jumping to a #hash (e.g. the homepage API Explorer 'Read the REST API docs' link, which points at the GET section via #get-all / #get) landed the target heading flush under the navbar, hidden behind the sticky view-mode toolbar. Add scroll-margin-top: 110px (navbar 64 + toolbar 34 + breathing room) to heading anchors and endpoint blocks so the correct header comes to rest just below both bars, fully visible — on API pages and regular doc pages alike.
On the Document Service API page (~11 <Endpoint> blocks), the async components rendered and grew AFTER Docusaurus' initial anchor scroll, so the target heading shifted hundreds of pixels upward and landed hidden above the navbar — despite scroll-margin-top being set. REST/GraphQL settle before the jump and were unaffected. Add a small HashScrollFix component (mounted in Root) that re-runs the hash scroll a few times as the layout stabilizes and once the document height stops changing. scroll-margin-top still owns the offset; this just re-triggers the scroll against the final layout.
- Stop the page from scrolling sideways on mobile: the mobile nav drawer is hidden off-screen to the right via translateX(100%) and extended the scrollable area. Clip horizontal overflow on .navbar (the drawer's containing block, thanks to its backdrop-filter) and on #__docusaurus, containing both the closed drawer and the off-screen reCAPTCHA badge. The drawer still slides fully into view when opened. - API Explorer on mobile: let the tabs and endpoint list scroll horizontally inside the card (min-width:0 + overflow-x:auto) instead of stretching the card past the viewport; wrap the URL bar. Verified overflow = 0 on homepage, REST API and quick-start at 390px; the AI panel already goes full-screen on mobile (confirmed).
- Mode switcher (elegant/markdown/AI) on mobile in Markdown mode: the desktop -13px top margin glued the bar to the 'On this page' TOC above it. Restore a small positive gap at medium-down so it isn't stuck to the TOC. Desktop spacing unchanged. - AI panel hint: on mobile the panel closes via the 'Back' button (top left); the ✕ is hidden there. Show a mobile-specific hint pointing at Back instead of the non-existent ✕, keeping the ✕ wording on desktop. - API Explorer on mobile: wrap the JSON response (pre-wrap) instead of scrolling it horizontally inside the card.
On mobile the footer links were 13px with only 4px between them and a ~20px tall hit area, so they looked tiny, crowded against the left edge, and were hard to tap (felt unclickable). At small-down, bump the link size to 15px, render each as a full-width block with 8px vertical padding (~39px tap target) and add spacing between category groups. Desktop is unchanged.
…pacing - 'What's new?' (and the left half of the top links) was unclickable: the decorative footer logo (::after, absolutely positioned) overlapped them and intercepted taps. Set pointer-events: none on the logo so it never swallows clicks. - Align link columns and category titles with the logo: the Infima grid .row -8px gutter pushed columns to left:8px while the logo sits at 16px (visible misalignment on Firefox). Cancel the gutter and .col padding on mobile so logo, titles and links share the same 16px left edge. - Reduce vertical spacing between links (link padding 8px -> 4px). Desktop footer unchanged.
40 pages under cms/api had no <Tldr>, so AI mode showed 'No summary available for this page.' Add a concise 1-2 sentence summary to each (REST, GraphQL, Document Service, Entity Service, Query Engine, OpenAPI, Strapi Client), placed right after the H1. Summaries are factual to each page, use inline code for API names/operators, and match the existing Tldr style.
Every doc page now has a <Tldr>, so AI mode no longer shows 'No summary available for this page.' anywhere. Covers migration/upgrade guides (with the version/breaking change named), configurations and SSO/providers, plugins development, backend-customization examples, cloud getting-started, admin-panel customization, typescript, data-management, AI, and the remaining root pages. Summaries are factual per page, use inline code for APIs/flags/operators, match the existing Tldr style, and sit right after the H1 (or after the frontmatter on the two pages without an H1).
In the 2-column endpoint layout the code/response cell was sticky with a viewport max-height and its own scrollbar, so long responses scrolled inside the cell instead of being fully visible. Only in the actual 2-column layout (wide/max content width, non-AI), let the cell grow to its full height (position:static, max-height:none, overflow visible). The 1-column layouts (narrow content width and mobile) keep the sticky behavior untouched.
This reverts commit 6014c61.
Retry of the reverted fix, now with the missing piece: the code/response cell holds a <pre> with long lines (overflow-x: auto), so once it is no longer height-constrained its min-content width pushed the grid column past its 1fr share and crushed the params column (the broken layout from the first attempt). Add min-width: 0 to the grid cells so the 1fr 1fr split holds while the <pre> scrolls horizontally in its own box; then drop the cell's sticky max-height/overflow so the whole response is visible. Scoped to wide/max content width, non-AI. Verified on rest and document-service: grid stays balanced (492/492 at max, 344/344 at wide), no inner scroll at wide/max, narrow (1-column) and mobile unchanged, no page overflow.
…ner scroll Three fixes for the REST API / Document Service endpoint pages: - Remove the hover highlight on parameter rows: the rows are not interactive (clicking does nothing), so the highlight wrongly implied they were clickable. - Remove the background tint on the code/response column in both light and dark mode: the contrast added visual noise without purpose; the column now blends with the page. - AI mode: the code/response cell kept its sticky viewport max-height and inner scrollbar even though endpoints are single-column there, so long responses scrolled inside the cell. Let it grow to full height like the rest of the page (matches the earlier wide/max fix, which excluded AI). Verified: code column transparent (light+dark), no param hover bg, no inner scroll in AI mode, and the wide/max 2-column layout stays balanced with no inner scroll (no regression).
… background - Fix the inner scroll that reappeared on the code/response cell at the narrow content width (single column): the sticky max-height/overflow was only neutralized for wide/max/AI, leaving narrow with a leftover inner scrollbar. Make the cell grow to full height there too. - Apply min-width: 0 to the endpoint grid cells at every content width (not just wide/max): without it, the code <pre> long lines pushed the cell past the viewport and overflowed the page horizontally in narrow. - Remove the white/tinted background on the .codePanel code & response blocks in both light and dark mode; keep only the border to delimit them. Verified on rest and document-service: no inner scroll and no page overflow at narrow (large + small viewport), wide and max; 2-column grid stays balanced; codePanel background transparent in light and dark.
…blocks The previous change cleared .codePanel's background, but the white block that remained came from the inner <code> element itself: Prism/Infima give it a solid white background (rgb 255,255,255), which my earlier check missed because it only walked the ancestor chain, not the <code> node. Set background: transparent on .codePanel__pre code so the request and response code blocks blend with the now-transparent panel in both light and dark. Verified directly on the <code> element: transparent in light and dark.
…white/dark The 'Show more' fade gradient faded to pure white (light) and rgb(33,33,52) (dark), but the page background is #fafafa / #09090b, so the fade ended on a visibly different tone and read as a band. Fade to var(--strapi-surface-0) instead so it blends into the page in both themes; drop the now-redundant dark-specific gradient (the variable is already theme-aware). Verified: gradient bottom stop matches body background in light and dark.
Two issues seen on hard reload of a collapsed 'Show more' block: - Flash: the wrapper had a max-height transition, so on load the collapse animated from the full content height, briefly showing the whole block open. Disable the transition by default and enable it only after the first user toggle (component sets data-interacted), so clicks still animate but reload does not. - Width: the block could span the full viewport before the page-level :has() width rules applied. Give .expandable-content max-width:100% + border-box so it stays within its content column on its own. Verified: static (no-JS) render is collapsed at column width with no transition; after a click the transition is on and it expands.
In Markdown mode the linearized parameter rows ran together with only 2px padding and no divider, making it hard to tell where one parameter's info ended. Add bottom spacing and a bottom border to each parameter row (and drop it on the last row of each group) so parameters are clearly separated. Scoped to markdown mode; elegant mode rows are unchanged.
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
1 participant
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.
This PR is the work-in-progress cutover branch for the Strapi Docs "v7" full redesign, porting the new design onto current
maincontent.nextkind="js") of the 2-column<Endpoint>component so Document Service pages no longer show a misleading HTTP verb or200 OKmainNote: "v7" refers to the documentation package version, not to Strapi itself, which remains v5. This redesign does not change any Strapi product version.
Not ready to merge: remaining API/Cloud pages, full visual QA, and a final
mainre-sync are still pending.Direct preview link 👉 here (docs homepage)