Proposal for migrating to docusaurus v2
harish-sethuraman opened this issue · comments
The current docs site is running in docusaurus v1 and I would like to migrate it to docusaurus v2.
Since these involve a lot of changes I've tried to chunk out PRs as much as possible.
Prerequisites for docusaurus v2:
- The markdown has to be Markdown compatible
- There are some
img
andbr
tags that are unclosed - The front matter inside the markdowns have special characters that should be wrapped inside quotes
- There are some invalid MDX syntaxes inside markdown
- Changes in consuming translations - https://docusaurus.io/docs/migration/translated-sites
- There are some
These are some prerequisites that I've discovered when I tried to migrate to docusaurus v2 in my local (Basic functions work fine)
related issues:
I'd like to know maintainers thoughts on this 😄
After minimal migration repro:
Light mode:
Dark mode:
Hey @harish-sethuraman! We really appreciate you taking the time to report an issue. The collaborators
on this project attempt to help as many people as possible, but we're a limited number of volunteers,
so it's possible this won't be addressed swiftly.
If you need any help, or just have general Babel or JavaScript questions, we have a vibrant Slack
community that typically always has someone willing to help. You can sign-up here
for an invite.
Oh I would love this!
I'll start sending PRs then :)
Should we keep the v1 site in the website
as it is and then create a new folder for the v2 site and delete the older one after the new one is stable? Or rather modify the existing website
folder?
- Copying to a new directory and working on them might involve a lot of addition and mismatch in content when the older document is updated
- Also doing it on a separate folder will need a new netlify deploy.
How would you like to proceed on this?
Nice!! We could deploy a separate v2 url (or even doc2.babeljs.io) until it's ready and swap it, depends on how long we think it'll take (I've actually tried to migrate a few times in the past in previous beta's - partially made me want to try something else) maybe just keep a temporary branch like v2
until it's good enough. If we merge into that new branch, it doesn't really matter if you replace/new folder. Although it will cause some merge conflicts with existing PRs it should be fine since we haven't been merging too many lately
I've opened a PR with base as main
and v2
branch from my fork. Is this okay or can you guys create a v2
branch that we can maintain in this repo? I'll send PRs to v2 branch of this repo?
I created a WIP pr and moved some docs and home page to v2.
- #2622
- preview URL: https://deploy-preview-2622--babel.netlify.app/
Thank you for your work, now it's done!