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 #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: 99a0dc6 (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 f52d4a3

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

• Fix Netlify deployment
• From the previous work, updated this branch with commits from 1fe9067; the previous PR stopped around March 2023 so I started to gather commits from begining of March 2023.
• Double-check the content of what comes from site/assets (must be the latest versions at the end)
• Bump Astro dependencies
• Re-enable all .github/workflows/*
• Move from site-new to site
• Get rid of all Hugo references (files, mentions, etc.), or adapt them in the documentation
• The documentation generated/built must work within the gh-pages with the same process as before at first
• Check /docsref page
• Check Placeholder component precisely (see for instance f52d4a3)
• Handle this change precisely: f8a56da
• For all <ScssDocs where file="site" -> find the site-new reference so that npm run astro-build builds correctly
• Missing : in :root at /docs/5.3/customize/css-variables
• Double-check the rendering of all pages
  • Homepage
  • Versions
  • Docs
    • Getting Started
    • Customize
    • Layout
    • Content
    • Forms
    • Components
    • Helpers
    • Utilities
    • Extend
    • About
    • Migration
  • Examples page
  • All examples
• Check more in detail 1729bcc compared to the new Code.astro file -> it's apparently not needed as already handled
• Double-check the rendering of <JsDocs> from 06f7c3b + 34c2725 + e2854b9 (compared to main branch)
• Double-check 74c6f2b has been correctly reintegrated
• Check if there's anything to do with e468daa#diff-90090845e271c47d4fb564334a22156612e18b9bbc61397ed6dcc29bb6ddb20a (site/layouts/_default/examples.html with integrity values etc.)
• In index.astro examples, double-check that the external scripts use the right versions and sha384, compared to main branch
• Handle correctly the sitemap (see 9480a3d + 72d3b6e)
• Check all TODO(Astro migration) comments
• Missing search bar in the homepage (compared to https://twbs-bootstrap.netlify.app/)
• Fix docs-vnu issues and reuse it everywhere like it was the case in main branch
• There are duplicate sw.js, CNAME, and mayb other "external" files

Stackblitz

• Basic HTML/CSS examples
• Basic components like Accordions
• 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

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

Deployment

• Take into account the comments and Impacts analysis in [Experimental] Try out Astro docs deployment #41279

---

⚠️ Before merging

• Remove the TODO(Astro migration) part from our .gitignore file

---

Postponed tasks

• <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...
• <ScssDocs> renders // scss-docs-start vr-variables (and // scss-docs-end) in /docs/5.3/content/typography and shouldn't
• /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 react 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)
  • Check Expressive Code for an accessible rendering of syntax highlighting
• Add some Typescript checks such as astro check --root site, tsc -p site --noEmit
• Improve ResponsiveImage.astro component to implement the equivalent of Hugo's imageConfig and calculate the width and height of the image automatically
• Accessibility: find a way to add an aria-label to the anchor links in the docs (see 688d7e3). Could be suggested upstream as difficult to implement from our own code.
• Check whether we need to use defer like in 45fe28c, or we keep the using scripts in site/assets/*
• Add a render image hook? (see 2ba7dae#diff-14181aac55c6feb7b2a6e08c61d78e3f31be6f31b6e206a365cdcc3e9d0b5934)
• && rm -rf _site && cp -r site/dist _site was temporary to make Netlify works as it checks the built content in _site. It would need a live coding session with access to the Netlify account to change that.