feat(docs-next): migrate legacy docs serving to native mdsvex#2239
Draft
dancormier wants to merge 105 commits intomainfrom
Draft
feat(docs-next): migrate legacy docs serving to native mdsvex#2239dancormier wants to merge 105 commits intomainfrom
dancormier wants to merge 105 commits intomainfrom
Conversation
Legacy fragments each start with a page-header div (d-flex ai-start jc-space-between) containing the description paragraph and action badges (Svelte, Figma). This div was built for the old docs template, which expected it as part of the fragment. The new template provides its own header, causing the description (and action links) to appear inside the content area rather than in the header. Add extractLegacyHeader() which: - Finds the opening header div and locates its matching closing tag via a depth-counting walk (handles nested divs robustly) - Extracts description text from the .docs-copy <p> - Extracts Svelte and Figma action URLs from the badge <a> hrefs - Returns the fragment HTML with the header div removed The extracted values are returned as metadata so the new template renders description and action buttons consistently with MD-sourced pages. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
|
👷 Deploy Preview for stacks processing.
|
Collaborator
|
@dancormier you could potentially simplify this by getting 11ty to output in an easier to work with format like using |
The Figma badge on some pages (e.g. color-fundamentals) is hosted on svelte.stackoverflow.design (/figma/colors) rather than figma.com. URL-domain matching would incorrectly classify those links as Svelte. Replace domain-based regexes with per-badge <a>...</a> matching: iterate each badge element and identify it by the text label that follows the SVG icon (Svelte or Figma), not by the URL. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
8 legacy fragments have Figma badges linking to svelte.stackoverflow.design/figma/* aliases instead of actual figma.com URLs (e.g. color-fundamentals, typography, buttons). Filter extraction to only accept figma.com URLs for the Figma button. Those 8 pages will show no Figma button until correct figma.com URLs are added to their fragments or to structure.yaml. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
…ages Root cause: the stacks-docs page.html Eleventy template was rendering the page description twice — once inside the header flex div and once as a standalone paragraph below it. When fragments were (re)built, both occurrences appeared in the HTML, causing two descriptions to show. Changes: - stacks-docs: remove the duplicate standalone description paragraph from page.html (the description inside the flex div is sufficient; the new template extracts it as metadata and renders it in the header) - stacks-docs-next: add a belt-and-suspenders strip in extractLegacyHeader to also remove any standalone description paragraph left over in already-built fragments - stacks-docs: replace 7 wrong Figma badge URLs that pointed to svelte.stackoverflow.design/figma/* aliases with correct figma.com project links (color-fundamentals, icons, typography, spots, buttons, tags, editor) - stacks-docs: remove figma: field from box-shadow (no Figma link intended) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
stacks-docs-next was built on top of stacks-docs, copying pre-built HTML fragments, compiled assets, and a JS bundle from stacks-docs/_site at build/dev time via scripts/copy-legacy.mjs. Since stacks-docs-next is intended to replace stacks-docs, this removes the runtime coupling: - Commit static/legacy/ directly — the 98 legacy fragment HTML files, compiled assets (docs.css, entry bundles, images), docs.js, and llms.txt are now committed as static content rather than being generated by copying from stacks-docs - Remove scripts/copy-legacy.mjs — no longer needed - Remove predev script — was only used to invoke copy-legacy.mjs - Remove stacks-docs build step from prebuild — prebuild now only builds stacks and stacks-svelte, which stacks-docs-next directly depends on - Remove unused $data alias from svelte.config.js — pointed to ../stacks-docs/_data but was never imported anywhere The static/legacy/ content is now a committed snapshot of the legacy docs. Individual fragment files can be deleted as their pages are migrated to stacks-docs-next; assets and docs.js can be cleaned up once all legacy pages have been replaced. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
These changes (page.html template fix, frontmatter Figma URL updates) belong in a separate stacks-docs PR. This branch covers stacks-docs-next only. The duplicate-description and Figma URL concerns are handled in stacks-docs-next via extractLegacyHeader and the committed fragment files. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Removes 88 files (~10 MB) from static/legacy/ that are not referenced by stacks-docs-next or the fragment HTML files: - assets/dist/ (entire directory, ~8.1 MB) - docs.css — not loaded by stacks-docs-next or any fragment - docs.js.LICENSE.txt — build artifact, not served - entry.stacks-editor.js — 6 MB bundle, not loaded - all other entry.*.js files — not loaded by stacks-docs-next - assets/img/ (76 unreferenced images, ~2 MB) - logos/ — entire brand logos directory (56 files) - icons/ — logo glyph SVGs (6 files) - favicons/ — favicon files (3 files) - various root-level images not referenced by any fragment Remaining in assets/img/: the 10 images actually used by fragments (avatar and email preview assets). Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Replaces 38 static legacy HTML fragments with mdsvex Markdown files in src/docs/public/system/, served natively by the SvelteKit page server. Converted pages (base/ and components/ and foundation/): - base/height, margin, padding, width - components/activity-indicator, avatars, badges, bling, breadcrumbs, button-groups, cards, code-blocks, empty-states, expandable, inputs, labels, link-previews, links, loader, menus, page-titles, pagination, post-summary, progress-bars, radio, select, tables, tags, textarea, toggle-switch, topbar, uploader, user-cards, vote - foundation/accessibility, color-fundamentals, colors, typography Each MD file has YAML frontmatter (title, description, svelte URL, figma URL where available) extracted from the legacy fragment header, with the content HTML following. Also removed the `legacy:` field from structure.yaml for all 67 pages (38 newly converted + 29 that already had MD files but were being bypassed by the legacy-first serving order). 10 pages remain as legacy fragments because they contain inline <script> demos that require manual conversion to Svelte components: banners, buttons (already has full index.md), checkbox, editor, modals, navigation, notices, popovers, prose, sidebar-widgets, theming. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
…r to mdsvex Establishes the pattern for converting legacy HTML docs pages to clean, maintainable mdsvex. **ClassTable.svelte** — generic CSS class documentation table: - Auto-detects which columns to show based on the data (no config needed) - Supports both component pages (modifies/description) and base utility pages (output/define/responsive) with the same component - Exports ClassTableRow type for use in page script blocks **activity-indicator.md** — prototype of the new page format: - 588 lines → 92 lines - Uses the actual ActivityIndicator Svelte component for live demos instead of pre-rendered HTML - Uses ClassTable with typed class data - Uses standard markdown headings (processed by rehype-slug + rehype-autolink-headings — no custom heading component needed) - Uses fenced code blocks for HTML usage examples The same pattern applies to all other converted pages: 1. Import ClassTable + the relevant stacks-svelte component 2. Define class data as a typed array in the script block 3. Use markdown headings + prose 4. Render live demos with Svelte components 5. Show HTML class usage in fenced code blocks Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
…a11y
- Prop was named 'rows' but usage passes '{classes}', causing rows to be
undefined on render
- Added role="region" + aria-label to the scrollable wrapper so tabindex
on a non-interactive element is valid
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
… order
- Code block first, then live example (matching original layout)
- Restore all compound examples:
- Standalone indicators (empty, numbers, text)
- Activity indicator on avatar (ActivityIndicator + Icon + raw s-avatar HTML)
- Activity indicator on notification icon (Icon + ActivityIndicator with positioning classes)
- Activity indicator count pill on notification icon
- Use {#each} over variants to eliminate repetition in the Variations section
- Replace @svg.* C# syntax in code blocks with commented HTML equivalents
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
…kage Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Example.svelte wraps live demos in a light gray bordered container with padding, keeping examples visually distinct from prose and code blocks. Used in activity-indicator.md as the pattern to follow. Also adds TODO comments in both the script block and the two avatar examples noting where IconShieldXSm should be added once the icon is published in @stackoverflow/stacks-icons. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Changes rehype-autolink-headings from behavior:"wrap" (which made the heading text itself a silent link) to behavior:"append" (which appends the IconLink SVG after the heading text). Pairs with CSS in app.css that makes h2/h3/h4 flex containers so the icon is pushed to the right edge, matching the original legacy layout. The anchor is aria-hidden so screen readers aren't confused by the duplicate link — the heading id is the accessible anchor. This is a site-wide fix that works automatically for all mdsvex pages without needing a custom heading component. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
…in breadcrumb Removes the "Copy" button from the page actions row and adds a small link icon button (s-btn__xs s-btn__clear s-btn__icon) inline at the end of the breadcrumb nav. Clicking it copies the current page URL to the clipboard using the existing copyToClipboard action. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
…button Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
…b copy link - Replace raw <button> with <Button link icon> using the link prop - Handle clipboard write with an inline async onclick instead of the use:copyToClipboard action (actions can't be applied to components) - Size icon with w16 h16 Stacks atomic classes — removes the custom CSS rule and the .breadcrumb-copy-link class - Remove unused copyToClipboard import and copysuccess window listener Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- Remove flex--item from nav; nav is already a flex child via the outer div - Make nav itself d-flex ai-center g6 so items are evenly spaced and vertically aligned, including the copy link button - Remove pr6/mr6 from individual items — gap handles all spacing - Move separator before each item (index !== 0) instead of after, which is cleaner with a flex gap layout - Remove ml4 from Button — gap handles the spacing Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Adds @stackoverflow/stacks-icons-legacy as a dependency (workspace *). IconShieldXSm lives there rather than in the main stacks-icons package. Restores the shield badge icon to both the Default and Variations avatar examples in activity-indicator.md. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
… reordering to top Replaces md:order-first (which moved the TOC to the top of the page in column layout) with md:d-none (hides it entirely). Also removes the now- unused collapsible toggle button, isOpen state, and related Icon imports. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
The code-blocks page contains syntax-highlighted HTML <pre><code> blocks
with raw { and } characters (CSS rules, JSON, Java/C# class bodies, etc.)
that Svelte treats as template expression syntax, causing a 500 error.
Replaced all { and } in text nodes inside <pre> blocks with { and
} HTML entities — they render identically in the browser but are
not interpreted as Svelte expressions.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
408 → 328 lines. All content preserved. - ClassTable for the three classes (.s-code-block, .linenums, .linenums:<n>) - Markdown headings replace the legacy HTML heading+anchor pattern - All 13 language example sections use markdown fenced code blocks — the mdsvex highlighter applies hljs + s-code-block classes, matching the legacy output without needing pre-rendered HTML or brace escaping - Each rendered example wrapped in an Example container - Line numbers section keeps pre-rendered HTML (Default + Offset) since line number columns require baked-in HTML elements not producible by markdown code fences; braces remain escaped as {/} Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- Search button now always renders; disabled when Algolia env vars are absent rather than conditionally hidden — keeps the header layout intact - Add figma: URL to code-blocks frontmatter - Wrap highlight.js in backticks in language examples prose Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Use weight='clear' size='xs' for correct styling. Remove disabled prop — the button is always clickable; openSearch() is a graceful no-op when Algolia credentials are not configured. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
…geless pages - Search: switch from Button to Link component - Page template: make breadcrumb row bottom margin conditional — mb128 only when the page has a hero image, mb24 otherwise Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- Logo/search bar: py12 px16 (was pt16 px24) for better proportions - Navigation container: add pt16 above the nav items Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- Add @stackoverflow/stacks-editor to package.json dependencies - StacksEditorDemo.svelte: dynamically imports the library on mount (client-side only) via Promise.all to load both the module and its CSS, then initialises StacksEditor on a bound container div - editor.md: Installation (NPM/modules/script tag), Configuration stub, and two Examples (empty, tables enabled) each rendered via StacksEditorDemo inside an Example container - Remove legacy: from structure.yaml so the page serves from the MD file Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
…ader Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
266 → 80 lines. Uses EmptyState Svelte component with Svelte 5 snippet syntax for description and actions props. All prose kept verbatim. Code blocks kept verbatim. Button component for the actionable example. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
…ual docs-* classes All document styles are now standalone BEM-style classes applied directly to the generated elements via the new addDocClasses rehype plugin — no style rule relies on a parent .doc wrapper. New classes (applied by the rehype pipeline at compile time): docs-heading h2/h3/h4 — flex layout for heading + anchor icon docs-h2/h3/h4 per-heading overrides (font-size, color) docs-heading-anchor the anchor icon element (renamed from heading-anchor) docs-section sections from rehype-sectionize docs-p paragraph elements docs-ul / docs-li list elements docs-nav nav elements docs-link content anchor elements docs-img images docs-iframe iframes svelte.config.js: - heading-anchor → docs-heading-anchor in rehypeAutolinkHeadings properties - addDocClasses plugin added after addTableClasses app.css: - All .doc X selectors replaced with the individual class equivalents - .doc container class kept as an unstyled identifier on the content div Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
… classes The bg-brand-* and fc-brand-* utility classes are already provided by Stacks CSS — no need to redefine them. The --brand-color-* custom properties however are NOT in Stacks and are referenced by brand docs components (ColorHeadlines, ColorBackgrounds, ColorLabels, LogoColors, etc.) so those must stay. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Extracts the full 8KB textarea content from the original editor fragment into a separate editor-example-content.ts file and imports it into editor.md, passing it to StacksEditorDemo as the content prop. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
765 → 130 lines. Uses Link Svelte component for all 8 single-link variants (Default/Grayscale/Muted/Danger/Inherit/Underlined/Button/Dropdown). Two ClassTables: link classes (7 rows) and anchor classes (7 rows). Anchor examples kept as raw HTML since s-anchors is a CSS container pattern with no Svelte component equivalent. All prose and code blocks kept verbatim. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
…ch code block classes - docs-card had no styles in the new system; s-card provides the card styling used in the code block examples - First anchor container: remove s-anchors__default to match the code block which shows plain s-anchors for the first entry Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
…mples s-card no longer exists in Stacks. Add .docs-card to app.css: ba bc-black-225 bar-sm p16 — the bordered card context used in examples. Replace all s-card with docs-card in links.md including the code blocks, anchor container examples, and the nested/override examples. The s-anchors__danger/default classes on the containers now correctly produce the red/blue link colors shown in the screenshots. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Code blocks now show the pure s-anchors pattern without the docs-specific docs-card class. The rendered Examples still use docs-card for visual card framing, with s-anchors s-anchors__danger on the outer and s-anchors s-anchors__default on the inner. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
…html, not markdown) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Uses Loader Svelte component with size prop. ExampleTable for the sizes section (sm/default/lg). All prose and code block kept verbatim. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
ClassTableRow now has an optional parent field, rendered between Class and Modifies. Column is auto-detected like all others — only shown when at least one row has a parent value. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
…bles -- child elements get parent=<parent class>, modifies=N/A __ modifier classes get parent=N/A, modifies=<target class> Base classes get both as N/A Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
…ell5 Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Values starting with '.' (CSS class names) in parent, modifies, output, and any other column are now wrapped in <code> elements automatically. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
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.
Summary
This PR completes the migration of
stacks-docs-nextaway from its dependency onstacks-docs, replacing the legacy HTML fragment serving pipeline with native mdsvex pages, reusable documentation components, and a suite of UX improvements.Key changes
Dependency removal
static/legacy/) directly into the repo — removes the requirement to buildstacks-docsbefore runningstacks-docs-nextscripts/copy-legacy.mjsand thepredev/prebuildhooks that invoked it$dataalias pointing to../stacks-docs/_dataLegacy content audit & cleanup
static/legacy/assets/dist/(docs.css, 6 MB stacks-editor bundle, all entry scripts) — none were loaded by the new templatestatic/legacy/assets/img/@stackoverflow/stacks-icons-legacyas a dependency for icons not in the public packageFragment-to-mdsvex conversion
.mdfiles<script>demos remain as legacy fragments pending manual conversionlegacy:fromstructure.yamlfor all 67 pages that now have MD files (38 newly converted + 29 that already had MD files but were being bypassed)stacks-docspage.htmlEleventy template duplicate description bug viaextractLegacyHeader()in+page.server.tsNew reusable documentation components
ClassTable.svelte— data-driven CSS class table with auto-detected columns (modifies/output/description/define/responsive), collapsible "Show All Classes" button (opt-in viaexpandableprop), and customisable headingsExample.svelte— styled example container (ba bc-black-225 bar-sm p16 overflow-visible) for wrapping live demosBannerDemo.svelte— interactive banner demo with style/important/pinned controls and "Show example" buttonHand-converted component pages (mdsvex)
ActivityIndicatorSvelte component,{#each}over variantsAvatarcomponent,{#each sizes}for size tables,team-avatar.pngfor custom avatar columnBadgecomponent covering all types/states/awards/userTypes/sizes with{#each states}.s-bannerHTML (no Svelte component),ps-relativepattern from stacks-docs for inline examples,BannerDemointeractive examplePage template improvements
+page.server.tswalksstructure.yamlto the first leaf page instead of 404ing on section URLs_redirects(now handled dynamically)rehype-autolink-headingsbehavior: "append"withIconLinkSVG — works automatically on all mdsvex pagesIntersectionObserverwith a passive scroll listener (last heading above 120px threshold)wmx9on.doccontent column to prevent overly wide content on large screensflex--item*classes throughout, replace withfl-grow1,w50,w25, etc.Linkcomponent,g16 fs-captioncontainer/systempages, retained on brand/copy/handbook/resourcesFonts & colours
ff-stack-sans-headlineapplied to the left nav<header>and TOC sidebar — content body uses the system sans-seriffc-theme-primary/var(--theme-primary)throughout UI (nav hover, TOC numbers, logo link)body.theme-custom.themedCSS block with teal primary / purple secondary (ported from stacks-docsdocs.css)stacks-docs fixes (in
stacks-docspackage, not this PR)Related Issue
STACKS-843
Testing
/system/components/activity-indicator— live Svelte demos, ClassTable, Example containers, heading anchors, TOC scroll highlight/system/components/avatars— Avatar size tables withteam-avatar.png/system/components/badges— all Badge variants using{#each}/system/components/banners— inline examples withps-relative, interactive BannerDemo/system/develop— section URL redirects to first child pagemd, content column respectswmx9Changeset
No changeset needed —
stacks-docs-nextis not a versioned package.