Skip to content

[Experimental] Try out Astro docs deployment #41279

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Closed
wants to merge 1 commit into from
Closed

[Experimental] Try out Astro docs deployment #41279

wants to merge 1 commit into from

Conversation

julien-deramond
Copy link
Member

@julien-deramond julien-deramond commented Mar 8, 2025 •
edited
Loading

Description

This experimental PR gathers the gh-pages possible deployment of Astro docs migration PR.

First of all, the generated website is created by running npm run docs from #41251 (done on the 12th of April). It created a _site directory like it's already the case in our main branch.

Then, likely how we're already doing the gh-pages update:

npm run docs
mv _site /tmp/
git checkout gh-pages
git checkout -b gh-pages-jd-docs-astro

mv /tmp/_site/404.html .
mv /tmp/_site/CNAME .
mv /tmp/_site/apple-touch-icon.png .
mv /tmp/_site/favicon.ico .
mv /tmp/_site/index.html .
mv /tmp/_site/robots.txt .
mv /tmp/_site/sitemap-0.xml .
mv /tmp/_site/sitemap-index.xml .
mv /tmp/_site/sw.js .
rm -rf about ; mv /tmp/_site/about .
rm -rf components ; mv /tmp/_site/components .
rm -rf docsref ; mv /tmp/_site/docsref .
rm -rf examples ; mv /tmp/_site/examples .
rm -rf getting-started ; mv /tmp/_site/getting-started .
rm -rf migration ; mv /tmp/_site/migration .
rm -rf docs/getting-started ; mv /tmp/_site/docs/getting-started docs/
rm -rf docs/versions ; mv /tmp/_site/docs/versions docs/
mv /tmp/_site/docs/index.html docs/index.html
rm -rf docs/5.3 ; mv /tmp/_site/docs/5.3 docs/

Then, you can checkout this branch locally and run http-server for instance.

Impacts analysis

Comparison of the generated /team/index.html

  • The _astro directory must be in docs/5.3/assets (changed the configuration by using https://docs.astro.build/en/reference/configuration-reference/#buildassets)
  • Astro version has <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@docsearch/css@3"> and <link rel="stylesheet" href="/_astro/_slug_.C9dNs6d9.css"> in the <head>; and current Bootstrap version has <link href="/docs/5.3/assets/css/docs.css" rel="stylesheet"><link href="/docs/5.3/assets/css/search.css" rel="stylesheet">
    • Analysis: OK because everything is in the assets directory that will be used by Astro to run everything. Files are not deferred, but handled directly by Astro as assets.
  • Fixed <meta name="twitter:site" content="getbootstrap"> and <meta name="twitter:creator" content="getbootstrap"> should have a content equal to @getbootstrap
  • Astro has a <body tabindex="0"> while our current website has a <body>.
  • Our current website has a <div class="position-fixed" aria-hidden="true"><input type="text" tabindex="-1"></div> at the end of the file for /docs URLs only. Astro doesn't have it.
  • Fixed In Astro, the <footer> is defined after the <script>s
  • Scripts in Astro
<script src="/docs/5.3/dist/js/bootstrap.bundle.min.js" integrity="sha384-k6d4wzSIapyDyv1kpU366/PK5hCdSbCRGRCMv+eplOQJWyd1fbcAu9OCUj5zNLiq"></script>
<script type="module" src="/_astro/Scripts.astro_astro_type_script_index_0_lang.BeKqXKw6.js"></script>
<script type="module" src="/_astro/Scripts.astro_astro_type_script_index_1_lang.CAqD2hc_.js"></script>
<script type="module">const p = () => { const t = document.querySelector(".bd-sidebar"), a = document.querySelector(".bd-links-nav .active"); if (!t || !a) return; const c = t.clientHeight, i = a.offsetTop, r = a.clientHeight, n = i, s = n - c + r; (t.scrollTop > n || t.scrollTop < s) && (t.scrollTop = n - c / 2 + r / 2) }, v = () => { document.querySelectorAll('[data-bs-toggle="tooltip"]').forEach(e => { new bootstrap.Tooltip(e) }), document.querySelectorAll('[data-bs-toggle="popover"]').forEach(e => { new bootstrap.Popover(e) }); const t = document.getElementById("toastPlacement"); t && document.getElementById("selectToastPlacement").addEventListener("change", function () { t.dataset.originalClass || (t.dataset.originalClass = t.className), t.className = `${t.dataset.originalClass} ${this.value}` }), document.querySelectorAll(".bd-example .toast").forEach(e => { new bootstrap.Toast(e, { autohide: !1 }).show() }); const a = document.getElementById("liveToastBtn"), c = document.getElementById("liveToast"); if (a) { const e = bootstrap.Toast.getOrCreateInstance(c); a.addEventListener("click", () => { e.show() }) } const i = document.getElementById("liveAlertPlaceholder"), r = (e, o) => { const l = document.createElement("div"); l.innerHTML = [`<div class="alert alert-${o} alert-dismissible" role="alert">`, ` <div>${e}</div>`, ' <button type="button" class="btn-close" data-bs-dismiss="alert" aria-label="Close"></button>', "</div>"].join(""), i.append(l) }, n = document.getElementById("liveAlertBtn"); n && n.addEventListener("click", () => { r("Nice, you triggered this alert message!", "success") }), document.querySelectorAll('.carousel:not([data-bs-ride="carousel"])').forEach(e => { bootstrap.Carousel.getOrCreateInstance(e) }), document.querySelectorAll('.bd-example-indeterminate [type="checkbox"]').forEach(e => { e.id.includes("Indeterminate") && (e.indeterminate = !0) }), document.querySelectorAll('.bd-content [href="#"]').forEach(e => { e.addEventListener("click", o => { o.preventDefault() }) }); const s = document.getElementById("exampleModal"); s && s.addEventListener("show.bs.modal", e => { const l = e.relatedTarget.getAttribute("data-bs-whatever"), m = s.querySelector(".modal-title"), u = s.querySelector(".modal-body input"); m.textContent = `New message to ${l}`, u.value = l }); const d = document.querySelectorAll(".bd-example-offcanvas .offcanvas"); d && d.forEach(e => { e.addEventListener("show.bs.offcanvas", o => { o.preventDefault() }, !1) }) }; p(); v();</script>

while in Bootstrap it's

 <script defer src="/docs/5.3/dist/js/bootstrap.bundle.min.js" integrity="sha384-k6d4wzSIapyDyv1kpU366/PK5hCdSbCRGRCMv+eplOQJWyd1fbcAu9OCUj5zNLiq"></script>
<script defer src="/docs/5.3/assets/js/application.js"></script>
<script defer src="/docs/5.3/assets/js/search.js"></script>
<script defer src="/docs/5.3/assets/js/stackblitz.js"></script>

Analysis: OK because everything is in the assets directory that will be used by Astro to run everything. Files are not deferred, but handled directly by Astro as assets.

Before merging

  • Drop previous files like sitemap.xml that will be unused

@julien-deramond julien-deramond mentioned this pull request Mar 8, 2025
Merged
68 tasks
@julien-deramond julien-deramond force-pushed the gh-pages-jd-docs-astro branch 3 times, most recently from 3e53e0b to 01cfcde Compare April 14, 2025 18:02
@julien-deramond julien-deramond force-pushed the gh-pages-jd-docs-astro branch from 01cfcde to 0e5c95d Compare April 14, 2025 18:26
@julien-deramond julien-deramond deleted the gh-pages-jd-docs-astro branch May 6, 2025 15:07
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers
No reviews
Assignees
No one assigned
Labels
docs v5
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
1 participant
@julien-deramond