Skip to content

[Experimental] Try out Astro docs deployment#41279

Closed
julien-deramond wants to merge 1 commit intogh-pagesfrom
gh-pages-jd-docs-astro
Closed

[Experimental] Try out Astro docs deployment#41279
julien-deramond wants to merge 1 commit intogh-pagesfrom
gh-pages-jd-docs-astro

Conversation

@julien-deramond
Copy link
Copy Markdown
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