Repository navigation
Migrate the Icons documentation to Astro and BUI - #2315
Merged
Merged
Conversation
Add a Bootstrap 6 Astro site alongside Hugo with shared navigation and footer UI, an adapter for the existing icon sources, a filterable catalog, and generated detail and SVG download routes.
Visitors can now browse and filter every icon, keep searches in the URL, open complete icon detail pages, copy SVG, font, and CSS examples, and read install, usage, sprite, and accessibility guidance on any screen size. Build all public routes and package assets into _site-astro, add metadata, 404, robots, sitemap, theme, and validation support, and expose additive root scripts while leaving the Hugo deployment and npm package contract in place.
Move every Astro route onto the canonical shared docs layout and navigation, then port catalog, detail, usage, sprite, font, and error pages to Bootstrap 6 components and utilities. Compile Bootstrap 6 source through the v6 PostCSS pipeline so shared tokens, responsive behavior, typography, dialogs, menus, and themes match the docs. The published bootstrap-icons files contract remains unchanged.
The Astro site can now stand in for the Hugo deployment without dropping legacy icon aliases or root favicon routes. Generate compatibility pages from Hugo front matter and preserve local preview redirects. Add timed builds, route and asset validation, HTML checks, Hugo output comparison, and npm and release ZIP contract checks. Document the local audit and keep production cutover gated on immutable shared dependencies.
The shared navigation exposed an oversized custom hero and uneven spacing across the Icons site, especially when the layout collapsed on mobile. Restore the production Icons hero structure with Bootstrap 6 components and utilities, carry the same approach through catalog and content pages, and retain custom CSS only for icon rendering and code overflow.
Browse icon categories from the homepage or static category pages, filter within each metadata-backed set, and carry the query between category links. Restore the official Figma mark and replace the hero link pile with a focused subnav. Add a documentation landing page and validate the new route and sitemap contract.
Browse a small server-rendered icon page, then search or load more across the complete catalog without blocking footer access. Add deterministic static pagination for no-JavaScript browsing and preserve query/history state across all-icon and category views. Rebuild the documentation around the shared Bootstrap docs navigation and table of contents, with anchored sections, copyable examples, expanded usage guidance, responsive cards, and accessible category pills. Enforce HTML, card-count, search-index, route, sitemap, and output-size budgets.
Give the category sidebar less space on wide screens and simplify its navigation styling so the icon catalog has more room for content.
Route documentation snippets through @twbs/docs-ui so Icons uses the same highlighting, toolbar, clipboard feedback, and responsive overflow behavior as Bootstrap docs and the blog. Keep HTML validation active while filtering CSS diagnostics from VNU, which cannot parse Shiki's CSS Color 5 light-dark output.
Visitors can now search the Icons site from the shared navbar in both development and production, resize catalog previews, and copy the restored install command. The catalog now uses the v6 form-adorn, spacing, and card patterns across desktop and mobile. Generate and budget a focused Pagefind index, copy it into development, and preserve the 48-card progressive catalog while keeping pagination and category routes out of duplicate search results.
The icon catalog used oversized square previews, cramped its sidebar against the grid, and left the filter toolbar visually unbalanced. Use denser responsive columns and 16:9 previews, center both rendered and appended icons, and apply Bootstrap gutters across every catalog route. Bound and simplify the toolbar while preserving filtering, pagination, and semantic size-button states.
Browse the catalog with install, Figma, version, and documentation links alongside the category navigation on every catalog route. Hide the existing hero with a display utility and reuse the canonical Bootstrap docs sidebar scrolling behavior. Keep the same controls available above categories in the mobile disclosure.
The icon catalog sidebar used full-size install and resource controls, which consumed too much vertical space on desktop and mobile. Size the copy control with generic Bootstrap utilities, use the small Figma button variant, and keep resource links inline until space requires wrapping.
Sidebar visitors currently see the Figma destination as a full-width solid button beside other compact resource links. Use Bootstrap's icon-link styling and size the official logo relative to text, while keeping its default dimensions for other placements.
The icon catalog sidebar used centered install text and placed its Figma link on a separate row from the other resources. Align the install command to the start, size its copy icon through a scoped component prop, and group the shortened resource links in one wrapping flex row.
At desktop widths, the catalog grid extended through the shared container gutters instead of lining up with the navbar and footer. Long category headings could also force horizontal scrolling on mobile. Use a gutter-token CSS grid inside the shared container, preserving the sidebar-to-catalog gap without the row's negative margins. Let catalog headings wrap when space is constrained.
Align category controls, icon labels, and catalog copy with the updated docs UI styles. Size the Figma action consistently and keep appended cards visually identical to server-rendered cards.
Replace the repeated category hero with a compact breadcrumb heading inside the catalog. Narrow the desktop sidebar by 50px while preserving the shared gutter, mobile drawer, and accessible category wrapping.
Move the icon catalog, detail pages, documentation, navigation, and search to the shared BUI-powered Astro shell. Add the canonical icon taxonomy, responsive catalog navigation, redirects, and deploy-asset validation. Install BUI 0.1.1 and Bootstrap v6-dev from CI-safe sources, test and compare Astro with Hugo in CI, and publish the Astro output on releases. Prepare the generated package assets and documentation for version 1.13.2.
![github-advanced-security[bot]](https://avatars.githubusercontent.com/in/57789?s=60&v=4){kind=small}
Netlify still ran the legacy Hugo build and published `_site`, so the PR preview showed the production documentation instead of the migration. Install the Astro workspace dependencies, build the Astro site, and publish `_site-astro` with Node 24.
Make Astro the only documentation development, test, build, and deploy path. Remove the Hugo configuration, templates, assets, dependencies, comparison tooling, and stale migration guidance while retaining shared icon metadata and static assets. Also make release ZIP staging consistent across platforms and eliminate the file-system race reported by CodeQL.
The icon size picker crowds the catalog filter on narrow screens and causes the controls to overflow. Hide the picker below the medium breakpoint so the search field has enough room.
Replace the Bootstrap development branch dependency with the published Bootstrap 6 Alpha 1 npm release.
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
@twbs/bui@0.1.1and Bootstrapv6-dev1.13.2Testing
npm cinpm ci --prefix astronpm run iconsnpm testnpm run docs-testnpm run release-check