docs: migration to Astro

[julien-deramond]

This PR migrates our documentation to Astro based on previous work at #38319.

🌟 Netlify preview

Note

Last commit gathered: 53171ad (March 9, 2025)

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)
• Fix linting
  • Add && astro check --root site && tsc -p site --noEmit to the astro-lint script
• Bump Astro dependencies (see c49f234)
  • Migrate to modern way of handling Astro websites (check migration guides)? Or could wait for another PR?
• Re-enable progressively .github/workflows/*
  • .github/workflows/docs.yml
  • .github/workflows/lint.yml
• Move from site-new to site
• Change scripts names to use old ones OR migrate the entire documentation to build and deploy the website
• 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
• Double-check the rendering of all pages
  • Special check for the migration page (including the diff rendering)
• Check more in detail 1729bcc compared to the new Code.astro file
• 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.)
• Check 688d7e3 so that we maybe add the aria-label if not present by default in Astro
• 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 45fe28c); do we need that with Astro?
• Handle correctly the sitemap (see 9480a3d + 72d3b6e)
• Render image hook? (see 2ba7dae#diff-14181aac55c6feb7b2a6e08c61d78e3f31be6f31b6e206a365cdcc3e9d0b5934)
• Check all TODO(Astro migration) comments
• eslint must work with .md AND .mdx files to check the JS that is contained in the code snippets (Markdown code)
• Check Mark's feedback (March, 8) -> "One thing I've noticed is I think I need to kill server often when rebuilding Bootstrap CSS"
• Missing search bar in the homepage (compared to https://twbs-bootstrap.netlify.app/)
• Fix docs-vnu issues
  • "docs-lint": "npm-run-all docs-prettier-check" -> "docs-lint": "npm-run-all docs-prettier-check docs-vnu",
  • Uncomment Validate HTML from .github/workflows/docs.yml
• Duplicate sw.js and CNAME? (and other 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

• Do we switch, and now, to Shiki?

• Clean up the _syntax.scss file that probably still have things related to Chroma.

• 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 $ 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:

  

• At docs/5.3/docsref, there are extra spaces (that should be automatically removed by reindenting the content of <ScssDocs> and <JsDocs>)

  

• Identation issues when we use stuff like:

  <Example code={`<div class="accordion" id="accordionExample">
  <div class="accordion-item">
    <h2 class="accordion-header">

  that renders

  

Deployment

• Impacts analysis in [Experimental] Try out Astro docs deployment #41279

Optional

• /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.

[julien-deramond]

&& rm -rf _site && cp -r site/dist _site is temporary to make Netlify works as it checks the built content in _site

[julien-deramond]

Workaround for withastro/astro#13400

[julien-deramond]

Check whether we keep it or not. Might be maybe problematic for major versions.