babel / website

:globe_with_meridians: The Babel documentation website
https://babeljs.io/docs/en/index.html
MIT License
749 stars 1.31k forks source link

Add remark-directive-babel8-plugin #2772

Closed JLHwung closed 1 year ago

JLHwung commented 1 year ago

In this PR we introduced a remark-directive-babel8-plugin. It is essentially a BABEL_8_BREAKING toggle (like we introduced in the main repo) working on the markdown docs:

When process.env.BABEL_8_BREAKING is 1, everything within :::babel8 and ::: will be rendered while everything within :::babel7 and ::: will be discarded. Otherwise their behaviour is swapped.

In this way we can maintain both the Babel 7 and Babel 8 docs in the same branch.

Due to the AST limit of MDX v1 (Docusaurus 3 will use MDX v2), the plugin has to hijack the paragraph AST node and manually check for :::babel8. In MDX v2 we can hook on the ContainerDirective AST type directly.

Preview link: https://deploy-preview-2772--rad-sopapillas-370b65.netlify.app/docs/babel-preset-typescript#options (both isTSX and allExtensions are removed in Babel 8)

netlify[bot] commented 1 year ago

Deploy Preview for babel-next ready!

Name Link
Latest commit 1e0d3de5d4f66815d4d9d7ff0aae0a0cc205eaeb
Latest deploy log https://app.netlify.com/sites/babel-next/deploys/645467b942ee5500085b81e2
Deploy Preview https://deploy-preview-2772--babel-next.netlify.app
Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site settings.

netlify[bot] commented 1 year ago

Deploy Preview for babel ready!

Name Link
Latest commit 1e0d3de5d4f66815d4d9d7ff0aae0a0cc205eaeb
Latest deploy log https://app.netlify.com/sites/babel/deploys/645467b9b67a2b0008ebfccd
Deploy Preview https://deploy-preview-2772--babel.netlify.app
Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site settings.

nicolo-ribaudo commented 1 year ago

I like this! We could then publish next.babeljs.io.

One alternative would be to have a client-side toggle that shows/hides the verison-specific sections.

JLHwung commented 1 year ago

One alternative would be to have a client-side toggle that shows/hides the verison-specific sections.

The current remark plugin can deal with most differences in markdown docs. But we will have more to take care, such as sidebar items, REPL settings. A client toggle will complicate the implementation when we introduced more Babel 8 changes. Therefore I lean towards the current approach, we can publish the Babel 8 changes to, like you said, next.babeljs.io.

JLHwung commented 1 year ago

The docs changes are removed in this PR. They will be fit into separate PRs so that we can link the docs PR to the actual change PR.

JLHwung commented 1 year ago

CI is failing because we hit the open collective API rate limit using two netlify builds:

The API is public and you can freely use it up to 10 request / minute without authentication.

https://graphql-docs-v2.opencollective.com/access#authentication

I will see if we can migrate to a personal token easily or we can just disable the sponsors downloading on Babel 8 netlify builds.