docs: migration to Astro

[julien-deramond]

This PR is the result of a long process of migration from Hugo to Astro. It's based on a previous work made with @hiDeoo a long time ago at https://github.com/twbs/bootstrap/pull/38319. I've restarted from there and spent quite some time gathering all the commits from the main branch, and adapting everything so that the rendering is exactly the same as the one from https://twbs-bootstrap.netlify.app. Shoutout also to @mdo for the helpful commits and reviews!

🌟 Netlify preview

[!NOTE]
Last commit gathered: 99a0dc628adc2fbe6ab1a60b0a4241073a4b5e4d (April 11, 2025)

Placeholder Documentation Component

The placeholder documentation component (previously a shortcode) is slightly different for only one use case at https://deploy-preview-41251--twbs-bootstrap.netlify.app/docs/5.3/utilities/object-fit/#examples where the colors are different from https://twbs-bootstrap.netlify.app/docs/5.3/utilities/object-fit/#examples. IMHO, this is an acceptable modification that avoids to have this specificity https://github.com/twbs/bootstrap/commit/f52d4a35b3332c34615880c6f6e8a026363ca390

ESLint Support - JS in MDX

Right now, it doesn't seem possible to handle things like {/* <!-- eslint-disable whatever --> */} in a MDX file. So, I haven't added the JS check in MDX files.

Sub-tasks

• [x] Fix Netlify deployment
• [x] From the previous work, updated this branch with commits from 1fe9067604c65ad61bd5685ad52965f6401e15fe; the previous PR stopped around March 2023 so I started to gather commits from begining of March 2023.
• [x] Double-check the content of what comes from site/assets (must be the latest versions at the end)
• [x] Bump Astro dependencies
• [x] Re-enable all .github/workflows/*
• [x] Move from site-new to site
• [x] Get rid of all Hugo references (files, mentions, etc.), or adapt them in the documentation
• [x] The documentation generated/built must work within the gh-pages with the same process as before at first
• [x] Check /docsref page
• [x] Check Placeholder component precisely (see for instance https://github.com/twbs/bootstrap/commit/f52d4a35b3332c34615880c6f6e8a026363ca390)
• [x] Handle this change precisely: https://github.com/twbs/bootstrap/commit/f8a56da8b04d8d29a8a8f65d50549206c429a621
• [x] For all <ScssDocs where file="site" -> find the site-new reference so that npm run astro-build builds correctly
• [ ] <ScssDocs> renders // scss-docs-start and // scss-docs-end in /customize/color-modes#sass-variables and shouldn't. It's because this is a special use case where there's a // scss-docs-start sass-dark-mode-vars wrapper that can contains several // scss-docs-start theme-*-dark-variables blocks...
• [ ] Missing : in :root at /docs/5.3/customize/css-variables
• [ ] Double-check the rendering of all pages
  • [x] Homepage
  • [x] Versions
  • [ ] Docs
    • [x] Getting Started
    • [x] Customize
    • [ ] Layout
    • [ ] Content
    • [ ] Forms
    • [ ] Components
    • [ ] Helpers
    • [ ] Utilities
    • [ ] Extend
    • [ ] About
    • [ ] Special check for the migration page (including the diff rendering)
  • [x] Examples page
  • [x] All examples
• [x] Check more in detail https://github.com/twbs/bootstrap/commit/1729bcca1b3a842829c9a64fe1f34fdd53465189 compared to the new Code.astro file -> it's apparently not needed as already handled
• [x] Double-check the rendering of <JsDocs> from https://github.com/twbs/bootstrap/commit/06f7c3b6c73580cd05b131bdab4d156a864d418c + https://github.com/twbs/bootstrap/commit/34c2725fe1c59940d775054f374d7cb6836bf80f + https://github.com/twbs/bootstrap/commit/e2854b94da6ead85753c9b9816b2ffdf3964a882 (compared to main branch)
• [x] Double-check https://github.com/twbs/bootstrap/commit/74c6f2bcfb1ca3391c2134e4e3425409b1c11939 has been correctly reintegrated
• [x] Check if there's anything to do with https://github.com/twbs/bootstrap/commit/e468daac252b9935baaa35cf22d83a3cd89bba88#diff-90090845e271c47d4fb564334a22156612e18b9bbc61397ed6dcc29bb6ddb20a (site/layouts/_default/examples.html with integrity values etc.)
• [ ] Add an aria-label to the anchor links in the docs (see https://github.com/twbs/bootstrap/commit/688d7e352a3c6370d7aa1871c0bb1d461af6a8e7)
• [ ] In index.astro examples, double-check that the external scripts and links have been set with the latest version + integrity
• [ ] We didn't use defer (see https://github.com/twbs/bootstrap/commit/45fe28c5a6ed88d1a661355349aed799a79ed0fe); do we need that with Astro?
• [x] Handle correctly the sitemap (see https://github.com/twbs/bootstrap/commit/9480a3d01d12968f8c0b06cf62d9554120ae1639 + https://github.com/twbs/bootstrap/commit/72d3b6efc4b92e83a4abca6f5bc0cd7e6fd25931)
• [ ] Render image hook? (see https://github.com/twbs/bootstrap/commit/2ba7dae3c080c5fac21f4d7f1663c8f524fefb26#diff-14181aac55c6feb7b2a6e08c61d78e3f31be6f31b6e206a365cdcc3e9d0b5934)
• [ ] Check all TODO(Astro migration) comments
• [x] Missing search bar in the homepage (compared to https://twbs-bootstrap.netlify.app/)
• [x] Fix docs-vnu issues and reuse it everywhere like it was the case in main branch
• [ ] Duplicate sw.js and CNAME? (and other files?)

Stackblitz

• [x] Basic HTML/CSS examples
• [x] Basic components like Accordions
• [x] More complex examples like Tooltips, Popovers, etc. don't work. The JS file is correctly uploaded to StackBlitz, but doesn't do anything.
• [ ] Test all use cases to be 100% sure that everything works

Syntax highlighting and code snippets

• [x] Clean up the _syntax.scss file that probably still have things related to Chroma.
• [x] Add $ or >PM prefixes for these languages
• [x] Diff code is highlighted with colors
• [x] At docs/5.3/getting-started/download#yarn, we should have a $ at each line
• [x] Handle correctly the indentation for <JsDocs>
• [x] Handle correctly the indentation for <ScssDocs>
• [x] Indentation issues when we use <Example code={}> with wrapping elements

Deployment

• [ ] Impacts analysis in https://github.com/twbs/bootstrap/pull/41279

---

Postponed tasks

• [ ] /docs/5.3/examples/dashboard-rtl/ and /docs/5.3/examples/dashboard-rtl behave differently in dev mode, depending on whether the trailing slash is present. This affects CSS and JS not loading (the local server looks for /docs/5.3/examples/dashboard.css for instance), though the issue does not occur on production, on Netlify. Please note that when you're navigating in the website by following the links, it works well.
• [ ] Check Mark's feedback (March, 8) -> "One thing I've noticed is I think I need to kill server often when rebuilding Bootstrap CSS".
• [ ] Possibly replace <div class="bd-example">...</div> by <Example showMarkup={false} code={...} />
• [ ] Migrate to modern way of handling Astro websites (check migration guides and new features)
• [ ] Use more advanced components: for instance replace our Markdown "tree" by something like https://starlight.astro.build/components/file-tree/ (if Starlight components can't work, re-develop them or find some in community libs)
• [ ] Switch from Prism to Shiki OR improve the syntax highlighting rendering (the colors are reactive to light/dark mode, but aren't exactly the same as Bootstrap. It might be re-plugged or handled differently to have the same rendering)
• [ ] Add some Typescript checks such as astro check --root site, tsc -p site --noEmit

[mdo]

• Check Mark's feedback (March, 8) -> "One thing I've noticed is I think I need to kill server often when rebuilding Bootstrap CSS"

Don't sweat this one—in v6, I'm going to most likely just import Bootstrap into the docs Sass can go from there haha. It's what I'm doing in v6-dev at least.

Possibly replace <div class="bd-example">...</div> by <Example showMarkup={false} code={...} />

Save for another time if needed I assume?

[mdo]

Handle correctly the sitemap (see 9480a3d + 72d3b6e)

Sitemap looks good to me. Compared the implementations and the sitemapExcludes list, and looked at the generated sitemap.xml and didn't see anything new.

[mdo]

Holy crap you did it! Woooo 🎉