Migrate the Icons documentation to Astro and BUI

.github/workflows/deploy.yml

@@ -33,6 +33,9 @@ jobs:
       - name: Install npm dependencies
         run: npm ci
 
+      - name: Install Astro dependencies
+        run: npm ci --prefix astro
+
       - name: Prepare release
         run: npm run release
 

.github/workflows/test.yml

@@ -36,12 +36,18 @@ jobs:
       - name: Install npm dependencies
         run: npm ci
 
+      - name: Install Astro dependencies
+        run: npm ci --prefix astro
+
       - name: Build the icons
         run: npm run icons
 
       - name: Build and test docs
         run: npm run docs-test
 
+      - name: Validate release artifacts
+        run: npm run release-check
+
       - name: Run linkinator
         uses: JustinBeckwith/linkinator-action@36a0bfbfecd5e237e8f8531537a693616c505faf # v2.4
         with:

.gitignore

@@ -1,9 +1,8 @@
 .DS_Store
-/.hugo_build.lock
 /.cache/
 /_site/
+/docs/static/pagefind/
 /node_modules/
-/resources/
 
 # Editor folders
 /.vscode/

README.md

@@ -14,8 +14,6 @@
   <br>
   <a href="https://getbootstrap.com/">Bootstrap</a>
   ·
-  <a href="https://themes.getbootstrap.com/">Themes</a>
-  ·
   <a href="https://blog.getbootstrap.com/">Blog</a>
   <br>
 </p>
@@ -24,46 +22,152 @@
 
 ## Install
 
-Bootstrap Icons are packaged up and published to npm. We only include the processed SVGs in this package—it's up to you and your team to implement. [Read our docs](https://icons.getbootstrap.com/) for usage instructions.
+The published package includes individual SVG files, the combined SVG sprite, icon fonts, CSS, and Sass.
 
 ```shell
 npm i bootstrap-icons
 ```
 
-For those [using Packagist](https://packagist.org/packages/twbs/bootstrap-icons), you can also install Bootstrap Icons via Composer:
+For those [using Packagist](https://packagist.org/packages/twbs/bootstrap-icons), Bootstrap Icons are also available via Composer:
 
 ```shell
 composer require twbs/bootstrap-icons
 ```
 
-[Also available in Figma](https://www.figma.com/community/file/1042482994486402696/Bootstrap-Icons).
+You can also [download the latest release archive](https://github.com/twbs/icons/releases/latest/).
+
+### CDN
+
+For the icon font, include the versioned jsDelivr stylesheet in your document head or import it from your stylesheet:
+
+```html
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/bootstrap-icons@1.13.2/font/bootstrap-icons.min.css">
+```
+
+```css
+@import url("https://cdn.jsdelivr.net/npm/bootstrap-icons@1.13.2/font/bootstrap-icons.min.css");
+```
 
 ## Usage
 
-Depending on your setup, you can include Bootstrap Icons in a handful of ways.
+Bootstrap Icons are SVGs, so they scale quickly and easily and can be styled with CSS. While they're built for Bootstrap, they'll work in any project.
+
+### Embedded SVG
+
+Embed an icon's SVG directly in your HTML. A width and height of `1em` lets the icon scale with the surrounding text.
+
+```html
+<svg xmlns="http://www.w3.org/2000/svg" width="1em" height="1em" fill="currentColor" class="bi bi-heart-fill" viewBox="0 0 16 16" aria-hidden="true">
+  <path d="M4 1c2 0 3 1.5 4 3 1-1.5 2-3 4-3 2.5 0 4 2 4 4.5 0 3-2.5 5.5-8 9.5C2.5 11 0 8.5 0 5.5 0 3 1.5 1 4 1"/>
+</svg>
+```
+
+### External image
+
+Copy an SVG into your project and reference it like any other image. Use useful alt text when the image conveys meaning and an empty `alt` when it is decorative.
+
+```html
+<img src="/icons/bootstrap.svg" alt="Bootstrap" width="32" height="32">
+```
+
+### SVG sprite
+
+The package includes `bootstrap-icons.svg`. Copy it to your own origin and use an icon filename as the fragment identifier. Cross-origin external sprites are restricted by some browsers, so serve the sprite with your application.
+
+```html
+<svg class="bi" width="32" height="32" fill="currentColor" aria-hidden="true">
+  <use href="/bootstrap-icons.svg#toggles"></use>
+</svg>
+```
+
+See the [complete sprite guide](https://icons.getbootstrap.com/sprite/) for local and external examples.
+
+### Icon font
+
+Include the icon font stylesheet, then combine the base `bi` class with an icon class based on its filename. Font icons inherit the current text size and color.
+
+```html
+<i class="bi bi-alarm" aria-hidden="true"></i>
+```
+
+When your Sass compiler cannot resolve the package's relative font URLs, set the font directory before importing the source:
+
+```scss
+$bootstrap-icons-font-dir: "bootstrap-icons/font/fonts";
+@import "bootstrap-icons/font/bootstrap-icons";
+```
+
+See the [icon font guide](https://icons.getbootstrap.com/font/) for class examples and the generated font stylesheet.
+
+### Sizing and color
+
+Embedded SVGs and the icon font use `currentColor`. Set `color` directly and set `font-size` when the icon dimensions are `1em`.
+
+```css
+.feature-icon {
+  color: cornflowerblue;
+  font-size: 2rem;
+}
+```
+
+### Accessibility
+
+Hide purely decorative icons from assistive technology with `aria-hidden="true"`. Meaningful standalone images need an appropriate text alternative. For icon-only controls, put the accessible name on the control—not on its decorative child icon.
+
+```html
+<button type="button" aria-label="Mute">
+  <svg class="bi" aria-hidden="true">
+    <use href="/bootstrap-icons.svg#volume-mute-fill"></use>
+  </svg>
+</button>
+```
+
+Prefer visible text when possible. A visible label or a `visually-hidden` label stays available to screen readers and supports users who may not recognize an icon.
+
+### Use in CSS
+
+SVG data URLs work in CSS, but URL-sensitive characters must be escaped—for example, `#` becomes `%23`. Keep the `viewBox` when resizing with `background-size`, and include the SVG namespace.
+
+```css
+.icon-example {
+  width: 1rem;
+  height: 1rem;
+  background-image: url("data:image/svg+xml,<svg viewBox='0 0 16 16' fill='%23333' xmlns='http://www.w3.org/2000/svg'>…</svg>");
+  background-repeat: no-repeat;
+  background-size: 1rem 1rem;
+}
+```
+
+## Figma
+
+The official Bootstrap Icons community file makes the icon set [available in Figma](https://www.figma.com/community/file/1042482994486402696/Bootstrap-Icons) for design work.
 
-- Copy-paste SVGs as embedded HTML
-- Reference via `<img>` element
-- Use the SVG sprite
-- Include via CSS
+## Releases and resources
 
-[See the docs for more information](https://icons.getbootstrap.com/#usage).
+- [Browse and search every icon](https://icons.getbootstrap.com/)
+- [Detailed installation and usage guide](https://icons.getbootstrap.com/usage/)
+- [SVG sprite guide](https://icons.getbootstrap.com/sprite/)
+- [Icon font guide](https://icons.getbootstrap.com/font/)
+- [Release notes and downloads](https://github.com/twbs/icons/releases)
+- [Package on npm](https://www.npmjs.com/package/bootstrap-icons)
 
 ## Development
 
 [![Build Status](https://img.shields.io/github/actions/workflow/status/twbs/icons/test.yml?branch=main&label=Tests&logo=github)](https://github.com/twbs/icons/actions/workflows/test.yml?query=workflow%3ATests+branch%3Amain)
 [![npm version](https://img.shields.io/npm/v/bootstrap-icons?logo=npm&logoColor=fff)](https://www.npmjs.com/package/bootstrap-icons)
 
-Clone the repo, install dependencies, and start the Hugo server locally.
+Clone the repo, install the root and Astro dependencies, and start the docs
+server locally.
 
 ```shell
 git clone https://github.com/twbs/icons/
 cd icons
-npm i
+npm ci
+npm ci --prefix astro
 npm start
 ```
 
-Then open `http://localhost:4000` in your browser.
+Then open `http://localhost:4321` in your browser.
 
 ### npm scripts
 
@@ -72,7 +176,9 @@ Here are some key scripts you'll use during development. Be sure to look to our
 | Script       | Description                                                                   |
 |--------------|-------------------------------------------------------------------------------|
 | `start`      | Alias for running `docs-serve`                                                |
-| `docs-serve` | Starts a local Hugo server                                                    |
+| `docs-serve` | Starts the local Astro development server                                     |
+| `docs-build` | Builds the production documentation site                                      |
+| `docs-test`  | Checks, builds, and validates the documentation site                          |
 | `pages`      | Generates permalink pages for each icon with template Markdown                |
 | `icons`      | Processes and optimizes SVGs in `icons` directory, generates fonts and sprite |
 

astro/.gitignore

@@ -0,0 +1,3 @@
+node_modules/
+.astro/
+dist/

astro/.npmrc

@@ -0,0 +1 @@
+allow-git=root

astro/README.md

@@ -0,0 +1,70 @@
+# Bootstrap Icons documentation
+
+The production Bootstrap Icons documentation site is built with Astro.
+
+## Dependencies
+
+The Astro site installs `@twbs/bui@^0.1.1` and Bootstrap 6 from npm:
+
+```sh
+cd /path/to/bootstrap-icons/astro
+npm ci
+```
+
+For local iteration across repositories, use `npm link --no-save` or install a
+packed tarball without updating the lockfile. Never commit generated links or
+an absolute `file:` path.
+
+## Commands
+
+From the Icons repository root:
+
+```sh
+npm run docs-serve -- --host 127.0.0.1 --port 4200
+npm run docs-check
+npm run docs-build
+npm run docs-test
+```
+
+The static production output is `_site/`. `docs-test` runs Astro
+type checking, generates every catalog/detail/category/asset route, and
+validates local links, fragment targets, redirects, sitemap/robots metadata,
+byte-identical icon assets, and HTML. Category routes use
+`/icons/category/<slug>/`; their labels, deterministic slugs, counts, and icon
+sets all come from the icon front matter through `src/lib/icons.ts`. Builds
+report elapsed time and enforce a 60-second budget; override it with
+`ASTRO_BUILD_BUDGET_MS` when diagnosing slower machines.
+
+### Icon taxonomy
+
+Each icon must have exactly one category from the canonical list in
+`src/lib/icons.ts` and at least one tag. Categories are broad browsing
+destinations; tags describe narrower subjects, visual variants, synonyms, and
+cross-cutting concepts such as `love`, `sort`, or `filter`. The Astro build
+rejects missing or unknown categories, missing tags, duplicate tags, and
+category labels that differ only in spelling or capitalization.
+
+The main documentation lives in the repository's root `README.md`; `/docs/`
+redirects there for compatibility. Detailed installation and SVG guidance
+remains at `/usage/`, sprite guidance at `/sprite/`, and icon font guidance at
+`/font/`.
+
+For the complete local audit, run:
+
+```sh
+npm test
+npm run docs-test
+npm run release-check
+```
+
+These commands lint and validate the project, build every documentation route,
+check local links and HTML, and verify both the npm package file list and
+release ZIP contents.
+
+Set `PUBLIC_FATHOM_SITE_ID` at build time to enable analytics. No analytics
+request is emitted when it is unset.
+
+## Production deployment
+
+CI builds and validates the Astro site and checks the release archive. Release
+deployment publishes `_site/`.

astro/astro.config.ts

@@ -0,0 +1,54 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { defineConfig } from "astro/config";
+import type { AstroIntegration } from "astro";
+
+const astroRoot = fileURLToPath(new URL(".", import.meta.url));
+const pagefindOutput = path.resolve(astroRoot, "../_site/pagefind");
+const pagefindPublic = path.resolve(astroRoot, "../docs/static/pagefind");
+
+// Match the Bootstrap docs and blog development setup: serve the index from
+// the latest production build without making Astro index thousands of pages
+// on every dev-server start.
+function pagefindDev(): AstroIntegration {
+  return {
+    name: "pagefind-dev",
+    hooks: {
+      "astro:config:setup": ({ command }) => {
+        if (command !== "dev") return;
+
+        fs.rmSync(pagefindPublic, { force: true, recursive: true });
+        if (fs.existsSync(pagefindOutput)) {
+          fs.cpSync(pagefindOutput, pagefindPublic, { recursive: true });
+        }
+      },
+    },
+  };
+}
+
+export default defineConfig({
+  output: "static",
+  site: "https://icons.getbootstrap.com",
+  outDir: "../_site",
+  publicDir: "../docs/static",
+  integrations: [pagefindDev()],
+  build: {
+    format: "directory",
+  },
+  vite: {
+    optimizeDeps: {
+      exclude: ["@twbs/bui"],
+    },
+    resolve: {
+      dedupe: ["bootstrap"],
+    },
+    css: {
+      preprocessorOptions: {
+        scss: {
+          loadPaths: ["node_modules"],
+        },
+      },
+    },
+  },
+});