Update to Docusaurus 2

[smorimoto]

Hi there! The Docusaurus team is currently developing Docusaurus 2 and are almost done with an MVP that doesn't include translations and versioning features, which means there's feature parity with our website's current usage of Docusaurus.

Docusaurus 2 brings about many improvements:

• Client-side rendering with prerendering (site renders without JavaScript!)
• More flexible appearance - Customizable layouts, CSS modules, etc
• Embeddable interactive React components within markdown via MDX

I will be helping you migrate and be the POC throughout the migration process. Let me know what you think!

cc @yangshun @wgao19

[ybiquitous]

Looks good idea!

[smorimoto]

The Docusaurus team will be sending Facebook Open Source stickers to contributors who successfully complete migrate a website.

[sasurau4]

I'll try to work on this issue!

[smorimoto]

Great! Thanks @sasurau4!

[smorimoto]

Hmm? This is a bit strange, why are the documents separated into two repositories?

[smorimoto]

It's probably a good idea to create a website directory in the root directory of the stylelint repository.

[ybiquitous]

@imbsky I'm not sure about the original reason for the separation, but I think it has worked well and is reasonable.

When we'd like to publish a new version of stylelint, we can just update stylelint in package.json:

stylelint.io/package.json

Line 103 in 8f6a1cd

"stylelint": "^12.0.0",

Also, the separation has an advantage which stylelint/stylelint doesn't need to have extra dependencies.

[smorimoto]

@ybiquitous The Redux documentation is probably a good example. We replaced that recently. In this case, the extra dependencies are not a problem.
https://github.com/reduxjs/redux/tree/master/website

[ybiquitous]

Yes, I think either way is reasonable and has own pros and cons. 😃

Anyway, it's a big task to move this repo to stylelint/stylelint. So if you'd like to achieve it, I think you will need to convince our community.

[smorimoto]

Certainly, I just checked all of this repository and it seems to work well. Let's migrate to alpha without moving to main repository!

[ntwb]

Sorry to do this, it's late here Friday night for me but I'm locking down this conversation, apologies for the lack of explaining the reason right now and I will follow up tomorrow with a full explanation

We will not be migrating to Docusaurus 2 Alpha

[hudochenkov]

I wouldn't migrate to alpha version of anything. It's not that stable and might have breaking changes at any point. Let's stick to stable releases.

[jeddy3]

why are the documents separated into two repositories?

They aren't. The documentation lives within the main repo:

• docs folder
• lib/rules folder

Only the code needed to transform these docs into a website lives in this repo.

I wouldn't migrate to alpha version of anything

Agreed.

[ybiquitous]

For example, Redux has migrated to Docusaurus v2 and the website seems to work well.

• Migrate website to Docusaurus 2 reduxjs/redux#3635
• https://redux.js.org

So, if we could get the help of the Docusaurus team for our complete migration well and continuously, I think it attractive personally.

However, if not a few people are concerned about using the alpha version, I will follow the community's decision.

In addition, because the stylelint/stylelint.io repository is a little different from typical documentation which Docusaurus would assume, the migration may not be able to proceed smoothly.

Here are the different points:

• The custom script transforms markdown files in stylelint/stylelint repository to fit the Docusaurus structure.
• The stylelint.io homepage is same as the stylelint README. The page has sidebars but the typical Docusaurus-generated homepage has no sidebars like the Redux homepage.

[jeddy3]

So, if we could get the help of the Docusaurus team for our complete migration well and continuously, I think it attractive personally.

The Docusaurus team have a list of who and who shouldn't use the alpha. If you or some else is willing to champion the use of the alpha, i.e. put the legwork in over the course of the alpha, then you have my vote. As you said, it'll allow us to feedback our use case to the Docusaurus team.

The stylelint.io homepage is same as the stylelint README. The page has sidebars but the typical Docusaurus-generated homepage has no sidebars like the Redux homepage.

We've never had the time nor the design resources to build a custom website homepage. That might change in the future. At the moment, the current approach works. stylelint/stylelint#4548 refines the README.md too.

[smorimoto]

All right, let's wait until the stable release.

[ybiquitous]

We've never had the time nor the design resources to build a custom website homepage.

Yes, I agree 👍
It seems good to wait a stable release.

[m-allanson]

I was curious, so I opened a draft PR updating the site to Docusaurus v2. We can leave it open until v2 is out of alpha.

If you're curious too, here's the deploy preview and the PR.

[ybiquitous]

Good news! 🎉

With the announcement of this beta, the team is even more confident that Docusaurus 2 is ready for mainstream adoption!

Announcing Docusaurus 2 Beta:
https://docusaurus.io/blog/2021/05/12/announcing-docusaurus-two-beta

---

BTW, Docusaurus v1 depends on outdated browserslist and postcss, so we cannot resolve the dependencies alerts. 😢
(try cd website && npm audit)

[jeddy3]

Excellent. I think it's time to pick up #174, if anyone fancies it.

The deploy preview looks almost functionally there. I think we need to fix the rule pages:

• assign valid and invalid classes to our examples
• fix the sidebar there
• adding previous / next navigation there

Once they are in place, we can look at tidying up some of the styles, especially around dark mode. We'll probably want to keep things as close to the default theme to make things easy for us.