Switch to Docusaurus

[hzoo]

EDIT: #1521

https://twitter.com/fbOpenSource/status/941370631357997056

Docusaurus was released: https://docusaurus.io/blog/2017/12/14/introducing-docusaurus.html

Used on a few FB projects like prettier, jest, react-native, etc.

I mostly am in favor because other projects are using that have transitioned to it easily (doesn't seem hard since it's markdown but also can use react for custom stuff) and it has 2 features we are missing (and leaves the two we already have which is algolia search and markdown).

We need translation + site versioning. Translation is definetely a want, and site versioning is literally an issue right now while we are developing Babel 7 but everyone getting confused at the documentation being v6 while the repo is in v7.

• Translations: Internationalization #135
• Whether to add new docs: Publish syntax and transform doc for numeric separator #1257
• Update links/repos Update download-readmes.js -> Babylon #1496

---

Also https://twitter.com/gatsbyjs which is what react is using, and what I was thinking about earlier. It does seem like the jekyll -> docusaurus doesn't seem that hard so we could switch to that later anyway?

Always looking for help for anyone that would like to make this happen!

[JoelMarcey]

@hzoo Hi. I am a member of the team that helped create Docusaurus. Definitely let us know if you have any questions. We tried to keep the initial launch simple in terms of format support.

• markdown (which gets generated to HTML)
• static assets (CSS, images, html)

We are looking at other support moving forward though.

[KyleAMathews]

Happy to answer questions about Gatsby as well + help with transition as well if that's the decision!

[maazadeeb]

Just took a very quick look at Docusaurus. I think it'd be a fun experience to give it a spin using the Babel docs.

@hzoo can I give it a shot? If yes, anything specific you'd like me to check while attempting the migration?

[hzoo]

Nothing in particular I guess we just need to check the REPL still can work, etc. I'm ok if we have to change styles too if it's more structured. Maybe want to land in another branch so can iterate too

[QC-L]

I think switch is necessary. I'm the maintainer of babeljs.cn.

[xtuc]

@QC-L Ideally we should have a way to translate it easily in this repo (like a en and cn folder).

But we have our READMEs in the main babel repo, I don't know what's the best way to do it.

[hzoo]

We'll I'd be happy to see a PR for it, for sure it's necessary ^ we really need versioning + translation as mentioned

[QC-L]

I think we can refer to the practice of several sites. The first way, like nodejs.org. The second way, like vuejs.org.

[Daniel15]

Ideally we should have a way to translate it easily in this repo

Crowdin can do that (although the translations are stored on Crowdin, not in the repo). We use Crowdin for the Yarn website.

[Daniel15]

Now that the site is on Netlify, we have much more flexibility compared to if we were still using Github Pages. Go for it 😄

The Netlify build runs make bootstrap && make build, so any site builder should work fine as long as you add any required build steps to the build section of the Makefile. Note that it publishes the _site directory. If you want to play around with different configuration options (eg. different build commands or publishing a directory other than _site), you should likely create a separate Netlify site for testing purposes.

[hzoo]

I was going to switch us to docusaurus which uses crowdin as well, but having trouble understanding all our build steps haha

edit: looks like we might be able to just do this side-by-side given it uses a website folder to run

[QC-L]

How to manage the translation using crowdin? Crowdin translation should be submitted by anyone, how to ensure quality? like this babeljs.cn

[Daniel15]

@QC-L Crowdin has an approval process, and only approved translations would appear on the site.

[QC-L]

@Daniel15 Thanks, I'll translate it in Chinese.

[hzoo]

Alright I'm just going to deploy for 3 site urls (new.babeljs.io, old.babeljs.io, and babeljs.io).

Going to merge docusaurus into master for the new site and it will deploy to new.babeljs.io
old-site branch will be for backports if someone wants and it deploys to the current site babeljs.io and old.babeljs.io until we switch.

It's not ready/done yet but I'l make a new issue with stuff we should do.

[hzoo]

Moving to #1544