Migrate website to Docusaurus 2

[smorimoto]

Context: #3584

[smorimoto]

Preview: https://build-c69e7nasw.now.sh

[smorimoto]

Build directory structure

website/build
├── 01cc46ec.962094fa.js
├── 01df2f6c.8c880afd.js
├── 0493d762.4c3344a4.js
├── 0a591867.676e1f23.js
├── 0b3b7869.0afd12ce.js
├── 0d156841.e349a6b7.js
├── 12f2a276.f9939410.js
├── 14287c7c.6ecf2d30.js
├── 150.ad68e165.js
├── 150.ad68e165.js.LICENSE
├── 151.28f62ef0.js
├── 151.28f62ef0.js.LICENSE
├── 15a9da1f.299ae3d8.js
├── 17896441.81425820.js
├── 18831e12.f41a2421.js
├── 1c6c55f5.5510f8fe.js
├── 233720a4.7c91316d.js
├── 24e6d34c.8a55dd62.js
├── 250c05b6.b2a5a6b0.js
├── 28b27c5c.768def8d.js
├── 299a89dd.43bca322.js
├── 2c0299e1.974d1580.js
├── 2cd8a001.484557ea.js
├── 2cf90c7a.4d368276.js
├── 2f82a9ae.5e350170.js
├── 320a8fac.6ec322f2.js
├── 34669190.183388f1.js
├── 34f0070a.e2dbae5e.js
├── 354f66a6.8be1b3d0.js
├── 360501b7.0f27bde7.js
├── 397febd3.0e32eda4.js
├── 3be23004.46424dd7.js
├── 3cbb3f67.c0724338.js
├── 3d11fba6.63038038.js
├── 3f6bb3ae.2f89e904.js
├── 404.html
├── 415b6d8f.dd4d89d0.js
├── 4256d0c4.58771920.js
├── 431ca13d.af8023bd.js
├── 443bcee7.f85e2c55.js
├── 456310ee.8147c1b5.js
├── 463e2006.37cdf9ac.js
├── 47764677.9563fea2.js
├── 498fd5d8.f2a8283f.js
├── 4a07792f.bd89d5cb.js
├── 4a577960.b99c641e.js
├── 4a9a7eb8.42eb8e4f.js
├── 4eebaf7c.6848c2dc.js
├── 5132062f.d6c2ac93.js
├── 5153b664.68fdb9af.js
├── 51cf90b6.c0c1e5f0.js
├── 576c83a8.e72becea.js
├── 585b0e7c.c586fe8d.js
├── 5887689c.346d0ce1.js
├── 5b39a2b4.f2ea0df1.js
├── 5d0f8b6e.620e42c3.js
├── 5eff44a4.ca27e116.js
├── 6023b0f8.c69489df.js
├── 635623e7.4dc81f7b.js
├── 6386a9b1.e0ff691a.js
├── 652a7b6a.059e82bf.js
├── 66d322ee.6868ca34.js
├── 66fd82ad.e28e1dd6.js
├── 6bfa6211.0b90046f.js
├── 6f7296ba.536dbb8c.js
├── 6fbfa3c4.f8556c49.js
├── 744bf567.8ae0fa00.js
├── 77e3567f.d227b79b.js
├── 79605fd1.99ad3564.js
├── 7af1e5ba.972162db.js
├── 7bb39c23.cd080b0a.js
├── 7c3e7131.3d72911f.js
├── 7e998b72.018c730b.js
├── 7f05d695.b9945758.js
├── 7f8e84f4.4c6b182c.js
├── 81d52464.48e81349.js
├── 8216fd1f.09a10490.js
├── 83aca383.ad747ea0.js
├── 855bb413.81f4f36b.js
├── 85d95226.232ce89e.js
├── 860e4674.fdbea6df.js
├── 8c5ba71f.148b04c4.js
├── 8c9d2fa7.b9a216ae.js
├── 8d56eeb8.93ac08f8.js
├── 8de82df5.50ec5694.js
├── 90aa6603.903e33fd.js
├── 91e79301.fc2ddde6.js
├── 94f27863.d27ef893.js
├── 95903fe3.4f7ddedd.js
├── 982ac012.9d8223d4.js
├── 99557706.edcd920e.js
├── 9b1aaa7c.521611db.js
├── 9c9e4252.63184ce2.js
├── 9d28c83f.61729287.js
├── 9d8d5de3.2ca38bf0.js
├── 9fea413d.14bff5d3.js
├── a1bc804c.50fe02fc.js
├── a80d6cf5.fa91078c.js
├── a8fdca1f.b369870e.js
├── a943a4d0.b090ef26.js
├── aa306176.656dbe95.js
├── ab38bf17.28055a58.js
├── ac9474af.a4540908.js
├── ac9ff2e6.f563b574.js
├── ad895e75.2a853764.js
├── b063263c.a9eef126.js
├── b15ba208.563db2ca.js
├── b44cc5f1.6b2450b8.js
├── b5a2d834.82cc5743.js
├── b5ac8799.d89cbaa1.js
├── b5f9df15.cc4567ed.js
├── b7bfff81.1ec7a0ea.js
├── b7e4df0f.8837bd63.js
├── b884a8dc.2e16f7a2.js
├── b8997c4a.705419ec.js
├── c0b01ba1.33b40b66.js
├── c1b7e11f.dcf69c0d.js
├── c2f61ec8.c41dbfd7.js
├── c4500a0b.78021840.js
├── c4b4d404.9cdc0a13.js
├── c4f5d8e4.c4bea27d.js
├── c4f5d8e4.c4bea27d.js.LICENSE
├── c7ebf903.86375307.js
├── ca812f23.b8b729fc.js
├── cb0395b1.38f2cf41.js
├── cb7c6d3d.b77d7ff5.js
├── ccef9d9b.8a5e0a0a.js
├── chunk-map.json
├── client-manifest.json
├── d072c52e.3d4159f2.js
├── d203cf46.544dc266.js
├── d24e76fe.dd716176.js
├── d343b8d0.185f59c5.js
├── d3479d2c.c8501ebf.js
├── d7f2fb82.3eec8d43.js
├── daca1c1c.5efe922d.js
├── de6ac5eb.33536c89.js
├── df1b17a6.f41268f5.js
├── docs
├── e099e0b2.458f7dbd.js
├── e1659205.6b8282f4.js
├── e3e6d067.784da039.js
├── e5d27461.966e44c4.js
├── e62e0256.a0a987c0.js
├── e77cf743.d84d9071.js
├── e944c03a.ef4bcae3.js
├── ebffd568.aa5100ee.js
├── ed020432.a7c579c5.js
├── ee30f098.9436f4a0.js
├── f0feed73.9177a54f.js
├── f5e4307d.cf1e9de5.js
├── f732e4bf.8f3bbdfb.js
├── f7dc5c79.274f5417.js
├── fa3d0d18.598f40a1.js
├── fb84e0f4.dd7cfc67.js
├── fd36eec4.47286e75.js
├── img
├── index.html
├── main.5339b5ac.js
├── main.5339b5ac.js.LICENSE
├── runtime~main.6d0c5153.js
├── sitemap.xml
├── styles.0017e7ed.css
└── styles.379578f6.js

2 directories, 162 files

[markerikson]

Wow, that was fast!

Immediate observations:

Setup

• The Netlify build is failing. Might need to add a netlify.toml file on this branch to fix the build path?

3:03:37 AM: Error running command: Build script returned non-zero exit code: 1
3:03:37 AM: Failing build: Failed to build site
3:03:37 AM: failed during stage 'building site': Build script returned non-zero exit code: 1

• URLs are wrong - need to drop the /docs/ portion of URLs like https://build-c69e7nasw.now.sh/docs/introduction/getting-started
• WOW, switching pages is fast!

Styling

• Looking at both the Redux and RTK docs, I'd kinda like us to go back to having the purple top bar and keeping the main landing area white
• The RTK top bar has the nav buttons split to the right, but the Redux site has them all on the left
• Missing the search input in the nav bar
• Same "too much whitespace between the left nav and main content areas" complaint as RTK
• Style guide is missing the custom styling I added: <details> tags have no styling, and the category emphasis :after labels are missing
• General observation for both RTK and Redux: I don't like that closed sidebar categories have a down chevron. I'd prefer a right chevron instead.
• It would be nice if nested sub-categories like the "Recipes > Structuring Reducers" category had some different styling to highlight them, beyond the expander chevron

All that said, this is a pretty good start!

[timdorr]

Looking at both the Redux and RTK docs, I'd kinda like us to go back to having the purple top bar and keeping the main landing area white

That was my initial observation too, BUT it's started to grow on me that the purple should be used more sparingly as an accent, not a base color. In particular, this lets the logo be its natural color, instead of a contrasting, "cut out" style.

Missing the search input in the nav bar

It's also missing versioning.

It would be nice if nested sub-categories like the "Recipes > Structuring Reducers" category had some different styling to highlight them, beyond the expander chevron

Actually, the bigger problem there is the chevron is quite visually similar to the one below it, despite them being a different levels:

So, whatever styling is done there should also apply to the expandability indicator.

On that point, the only thing I have big issue with is the font weights on the left hand menu. It's odd having everything of equal weight and size when their action is not the same. That's probably the weakest part of the design right now, IMHO.

[markerikson]

We don't have any versioning on the Redux core site, just React-Redux.

Also definitely agree that the categories need better contrast in styles.

(As a side note, the versioning for React-Redux's site was frustrating me yesterday. In order to get a new page to show up in the "current" version of 7.1, you have to actually add it to the versioned_docs/7.1 folder. Adding stuff to /docs doesn't do anything, which was confusing. Had a discussion with @endiliey about that in their Discord later.)

[markerikson]

I think the failure from the logs is:

4:56:45 PM: Success! Generated static files in build.
4:56:46 PM: cp: cannot create regular file ‘./build/redux/’: Not a directory

DS v2 changed the build output folder, didn't it?

[smorimoto]

Yes, website/build is the build directory now.

[markerikson]

Right, and if you look at the RTK repo, I think we've got a netlify.toml in the root of the repo, that says the output is website/build:

https://github.com/reduxjs/redux-toolkit/blob/master/netlify.toml

[build]
  base    = "website"
  publish = "website/build"
  command = "yarn build"

Try copying that over?

[smorimoto]

Missing the search input in the nav bar

It's strange that the search input does not exist, the configuration is correct.

[smorimoto]

Updated netlify.toml

[smorimoto]

I'm fixing some styling now!

[smorimoto]

Looking at both the Redux and RTK docs, I'd kinda like us to go back to having the purple top bar and keeping the main landing area white

This can be a bit complicated and I prefer to keep it for future maintainability. What do you think?

[markerikson]

Okay, now the build is failing because:

5:23:57 PM: /usr/local/bin/build: line 34: yarn: command not found

[markerikson]

Oh, another problem: the page titles are getting duplicated. All of our existing Markdown files should have the "don't show the title" attribute or something, but I'm seeing both the title from the front matter and the explicit header tag showing.

[netlify]

Deploy preview for redux-docs ready!

Built with commit 3010ed8

https://deploy-preview-3635--redux-docs.netlify.com

[smorimoto]

Netlify has started to work correctly, thanks for your quick advice!

[smorimoto]

I changed the style of <details> a little. If you don't like it, I will Revert this.

Before	After

[smorimoto]

@markerikson @timdorr I changed the font color and font weight, what do you think?

[markerikson]

Yeah, I like the padding + round corners for the details, and the sidebar looks better. (Maybe drop the padding at the top of the details a bit?)

I'll take another look through the preview and see what sticks out.

[smorimoto]

Before	After

[smorimoto]

In my opinion, the padding was too much at the bottom than at the top, so I fixed it. What do you think?

[markerikson]

Sure, looks better, and we can always tweak the CSS later if needed.

[smorimoto]

Yeah, I will rebase and fix conflict.

[smorimoto]

Rebased!

[smorimoto]

Start researching search input issue.

[smorimoto]

I'm sorry! The config was wrong! Search input are now visible!

[smorimoto]

Travis test should pass now.

[smorimoto]

Okay, all tests and deploy passed.

[smorimoto]

The faq link of footer was incorrect and fixed now.

[markerikson]

Actually, on the topic of styling: I'd like to bring back the current colors for quote blocks in general, and the <details> section specifically. It's a light blue, rather those grays.

[smorimoto]

If there is no problem with the current style, I will rebase this.

[markerikson]

The links and descriptions in "Learning Resources / Ecosystem" are fixed, but the front-page bold text is still not spaced correctly.

Also, the "Help Us Improve the Redux Docs!" text on the front page should be removed, per #3635 (comment)

[smorimoto]

@markerikson Oops, I'm sorry! I forgot that! Fixed everything and bumped dependencies version to latest.

[markerikson]

Okay, getting closer :)

More notes:

• As mentioned earlier, I don't like that closed sidebar categories have a down chevron. I'd prefer a right chevron instead. (Also, v1 appears to have a nice transition animation between "right" and "down" chevrons, while v2 just flips instantly.)
• Overall, the font size for the v2 site seems just a shade smaller than the v1 site
• The border-radius appears to be getting applied to both the full-size code blocks and the inline code snippets. It's not bad, but it does make the inline snippets very rounded because they're smaller overall. Dunno if there's a way to lessen the radius for the snippets. The padding for the snippets seems just a bit large as well.
• There's some places where I have inline code snippets that are also links, such as the API reference links in the "Redux Toolkit" page: https://deploy-preview-3635--redux-docs.netlify.com/redux-toolkit/overview . There's no link-related styling for those inline snippets, whereas in the v1 page they get underlined: https://redux.js.org/redux-toolkit/overview .

Having said all that, I'm almost ready to give this a green light. @timdorr , any other feedback?

[smorimoto]

Well, it probably feels smarter to fix it in Docusaurus itself. What do you think? CC: @yangshun @endiliey

[endiliey]

Actually all of markerikson's notes is related to https://facebookincubator.github.io/infima/

Even docusaurus side can't do anything about it (unless we hack the CSS (override) which is bad), only infima can fix it. But UI is very subjective. I'm gonna cc the right guy @yangshun

[markerikson]

Awright. Let's do this!

[markerikson]

@imbsky : just to check, do you have a Twitter account? Just want to give proper credit when I let folks know the site conversion is available.

[smorimoto]

Yes, I have. @imbskyx

[smorimoto]

Thanks again for your review and additional work!

[markerikson]

And thank you for putting this together and dealing with all of my styling nitpicks :)

[smorimoto]

👍👍👍

[markerikson]

For reference, I did go ahead and tackle the last few styling issues myself, in these commits:

• 59c3514
• 3010ed8

[markerikson]

Hmm. And as soon as I say that, I'm noting that the RTK docs font size appears to be a bit bigger than the Redux docs font size (17px vs 15px).

Any idea why that is?

[yangshun]

I think it's because of https://github.com/reduxjs/redux-toolkit/blob/master/website/src/css/custom.css#L30

[markerikson]

Looks like it, yeah.

Would be nice to fix up any differences between the two sites, including the font size and the chevron behaviors. I think I'd like the 17px font size on both, unless folks have a good reason for it to stay smaller.

Anyone want to grab that?

[timdorr]

This removed the Netlify logo I added to the footer in #3656. We are now in violation of their ToS. Can we please add it back? I don't see an easy way to do that now.

I'm also really uncomfortable with using an alpha quality project for this right now. Could this have waited for a beta or final release?

[markerikson]

Good question. @imbsky , @endiliey , @yangshun , @wgao19 : how do we add some custom footer stuff now? Also, we need to add those attributions to both the RTK and React-Redux sites.

Also, I didn't realize that this PR actually moved all the Markdown content into /website/docs . RTK isn't set up like that. Any chance we can move that back?

@timdorr : RTK was converted over already, and looks good so far. This PR has been up for a few weeks, so there's been time to comment. I'm not worried about the "alpha" aspect atm, just need to tweak whatever other small issues pop up. There's also some capabilities in v2 that I want to start using as part of the docs revamp, like MDX content.

[lex111]

This removed the Netlify logo I added to the footer in #3656. We are now in violation of their ToS. Can we please add it back? I don't see an easy way to do that now.

I fixed this in the PR since I added this feature to the core of Docusaurus :D

[markerikson]

@lex111 : thanks! Can you file a PR to add this to the Redux Toolkit docs also (which are already DS v2 as well)?

[lex111]

@markerikson done ✔️ reduxjs/redux-toolkit#287