Skip to content
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.

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

docs: migration to Astro #41251

Draft
wants to merge 1 commit into
base: main
Choose a base branch
from
Draft

docs: migration to Astro #41251

wants to merge 1 commit into from

Conversation

julien-deramond
Copy link
Member

@julien-deramond julien-deramond commented Feb 26, 2025

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

🌟 Netlify preview

Sub-tasks

Screenshot 2025-02-27 at 22 34 53

becomes

Screenshot 2025-02-27 at 22 36 25

  • Migrate to modern way of handling Astro websites (check migration guides)
  • Re-enable progressively .github/workflows/*
  • Move from site-new to site
    • Astro shouldn't use site/data/docs-versions.yml
  • Change scripts names to use old ones OR migrate the entire documentation to build and deploy the website
  • Delete all Hugo references
  • 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)
  • Check duplicates between ./site-new/public/docs/5.3/assets/img/examples/*.png and ./site-new/static/docs/[version]/assets/img/examples/*.png
  • 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.)
  • /docs/5.3/examples/dashboard-rtl/ and /docs/5.3/examples/dashboard-rtl might give different results (load or won't load the CSS + JS)
  • Check for duplicate images/paths like ./site-new/public/docs/5.3/assets/img/guides/parcel-dev-server.png versus ./site-new/static/docs/[version]/assets/img/guides/parcel-dev-server.png
  • 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
  • Fix Stackblitz JavaScript part (file integrated into Stackblitz but doesn't do anything)
  • 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

"watch-js-docs": "nodemon --watch site/assets/js/ --ext js --exec \"npm run js-lint\""
"watch-js-docs": "nodemon --watch site/assets/js/ --ext js --exec \"npm run js-lint\"",
"astro-dev": "astro dev --root site-new",
"astro-build": "astro build --root site-new && rm -rf _site && cp -r site-new/dist _site",
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

@julien-deramond julien-deramond force-pushed the main-jd-docs-astro branch 22 times, most recently from 1341bde to 8551496 Compare March 2, 2025 19:19
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

1 participant