Migrate Website to Docusaurus 2 Alpha

[lex111]

Hi there (@@joeldenning and others)! 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 your 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 your POC in helping you throughout the migration process. Let me know what you think!

cc @yangshun @endiliey @wgao19

[frehner]

Cool, thanks for the heads up. Would be interesting to try it and see how it goes.

[edit] also the correct person to tag in this case would be @joeldenning :)

[filoxo]

I'm looking forward to this, awesome!

[yangshun]

Ref: facebook/docusaurus#1834

[frehner]

Ref: facebook/docusaurus#1834

Ah, I didn't realize that @lex111 would be doing the work of the migration - I thought this was just a notification that the v2 alpha was available and that we should do it.

In that case, I approve the effort of creating a PR with v2 and going forward with it. Let me know if there's anything that we can do to help.

Thanks!

[lex111]

Quick question: can we refuse the GitHub star button in the footer or not? Is it really needed?

[frehner]

Is it needed? probably not.

Is it nice? in some ways, yes. I see github stars as a way for lesser-known projects that don't have the name recognition of bigger players to show that there is a community and support for this project, and that it's not just being used by 1 or 2 people.

that's just my thoughts though. anyone else feel free to chime in as well.

[lex111]

As the new version will have a dark theme, I propose changing syntax highlighting to dark colors. (Since dynamically we cannot change the code blocks highlighting scheme). Any objections?

If not, please pick up a theme - https://github.com/PrismJS/prism-themes#available-themes and write me the theme name.

Is it needed? probably not.

I did it :) I would like to have less differences compared to the current version.

[frehner]

As the new version will have a dark theme, I propose changing syntax highlighting to dark colors. (Since dynamically we cannot change the code blocks highlighting scheme). Any objections?

nope!

I did it :)

thanks!

[lex111]

If not, please pick up a theme - PrismJS/prism-themes#available-themes and write me the theme name.

So what theme are we using?

The only problem is still in the URLs. Currently, they comes with the html extension at the end, whereas in the second version URLs without this extension only, and this behavior can't be changed (as in v1) :(

And there are no any redirects, this is bad for SEO, and I don’t know yet how to fix it 😿

[frehner]

So what theme are we using?

I assume it would be easy to change? Anyway, let's start with Atom Dark.

And there are no any redirects, this is bad for SEO, and I don’t know yet how to fix it 😿

oh interesting. has there been any discussion in docusaurus about this change?

[lex111]

I assume it would be easy to change? Anyway, let's start with Atom Dark.

This is a piece of cake (Just still CSS styles need to be tweaked).

oh interesting. has there been any discussion in docusaurus about this change?

Docusaurus devs don’t care... at least for now. 🤷‍♂️

[frehner]

Docusaurus devs don’t care... at least for now. 🤷‍♂

haha. Wonder if they'll care if we say we don't want to move forward with the alpha until it's solved? not sure a small website like ours can afford to take an SEO hit.

[lex111]

Unfortunately, I found out about it at the last moment, when almost finished migrating to v2, it's very disappointing, because it seems to me self-evident that it is necessary to provide for such a thing as redirects..

[endiliey]

Docusaurus devs don’t care... at least for now.

Hi there, just wanted to clear things up. I think it can be slightly misleading to say that "we don't care". We do care. @lex111 mentioned this on Discord channel just yesterday and its definitely in our radar. I know it can be disappointing since lex111 has put some effort on the migration and we're sorry for that.

We are still in alpha period and created the 😎 Get swag for migrating websites to Docusaurus 2! issue exactly to find this kind of migration issue so that we can address it during this period. Way before that, we also have migrated some fb's own docs site. Its just a coincident that all of them had cleanUrl set to true.

There are still times to address things up, and we appreciate your effort here.
Docusaurus v2 is essentially a server side rendered app. During the build, we render the corresponding HTML by virtually visiting each route. After page is loaded, the client side routing takes over and it became a SPA.

There are many ways to solve this that I can think of, however any thoughts/opinions on how to solve this best will be appreciated

• Client side routing redirect. Use react-router Redirect if 404
• Create a .html redirect file for each stale route on static. Of course can be done programatically

[frehner]

I know it can be disappointing since lex111 has put some effort on the migration and we're sorry for that.

oh, no worries for my part. Thank you for coming in and clarifying. :)

There are many ways to solve this that I can think of, however any thoughts/opinions on how to solve this best will be appreciated

Hm, yeah, that is an interesting challenge. For clarity's sake, is the "cleanUrl" setting the recommended (or only possible?) setting starting with v2?

It's been a long time since I've gone into google webmaster tools, but was there a way in there to also submit a... CSV list of url mappings as well? It wouldn't actually redirect, but it may help with the SEO side of things. 🤷‍♀

But yeah, I think either of the solutions you suggested are fine by me. I haven't dug enough into the internals of docusaurus to really provide any additional insights, sorry.

[lex111]

Hi there, just wanted to clear things up. I think it can be slightly misleading to say that "we don't care".

Yes.. I'm a little rude, sorry for that, but I still don't understand why you removed many useful features (eg docsSideNavCollapsible), and for such features like cleanUrls didn’t do something that, which will help to facilitate migration to v2.
I really don't understand this, even considering that these are not such popular features, and v2 is alpha version. Breaking changes - I got this, but then you have to make the migration minimally painless.

It's been a long time since I've gone into google webmaster tools, but was there a way in there to also submit a... CSV list of url mappings as well?

I don't know yet, I would prefer the solution that was used in the v1. I need time to do this, it's not so easy for me :(

[lex111]

Please take a look at #109.

[frehner]

We should probably check out the auto-deployment script -- doesn't appear that single-spa.js.org has been updated to the latest changes.

[frehner]

closed by #115

[frehner]

looks like we're having redirect issues. see #116

[frehner]

another one I found is if you go to this url https://single-spa.js.org/docs

[endiliey]

@lex111 try to use normalizeUrls function from @docusaurus/utils maybe instead of string concatenation like that https://github.com/facebook/docusaurus/blob/639d8d3eace5ee59535b3879de54da640a57e0cf/packages/docusaurus-utils/src/index.ts#L191

Thanks for the help btw

[lex111]

@endiliey thanks for the tip, but this function does not do what is needed in this situation - it does not solve the issue with the trailing slash. https://github.com/facebook/docusaurus/blob/639d8d3eace5ee59535b3879de54da640a57e0cf/packages/docusaurus-utils/src/__tests__/index.test.ts#L222
I mean, in case GH Pages it should always be at the end of the URL. Although, for example, in the case of a deployment via ZEIT Now, redirects work fine.

[joeldenning]

Some more links not working: clicking on the four links shown here https://github.com/CanopyTax/single-spa.js.org/blob/c9620827fe7749ff423a607721e4d95cfbc62938/website/src/data/docs.js#L22

[frehner]

@endiliey while using dark mode, I'm seeing a flash of the white theme and then going back to the dark them while navigating around. Any thoughts on that?

[endiliey]

Thats interesting (?)

Mind to send ascreencast ? I cant reproduce it, we have dogfooded it for quite a while and so far nobody complained that.

I am suspecting the redirect plugin override the generated html with static html and that causes page refresh and not utilizing the client side routing/SPA

[endiliey]

I will take a look later. I am not within reach of my pc

[endiliey]

The issue is this https://github.com/CanopyTax/single-spa.js.org/blob/c9620827fe7749ff423a607721e4d95cfbc62938/website/src/data/docs.js#L22

It should not end with / at the end. Edit that file

https://github.com/CanopyTax/single-spa.js.org/blob/master/docs/examples.md is mapped to /docs/examples and not /docs/examples/.

Going to https://single-spa.js.org/docs/examples/ will actually go to https://github.com/CanopyTax/single-spa.js.org/blob/gh-pages/docs/examples.html (a redirect) instead of https://github.com/CanopyTax/single-spa.js.org/blob/gh-pages/docs/examples/index.html
causing a full page refresh. and not utilizing client-side routing at all (including docusaurus feature such as prefetching and preloading).

[lex111]

Oh, I’m already confused about all this, the fact is that without a slash a redirect occurs and this is strange behavior, and I can’t understand why this happens. In the end, I decided that it was because of GH Pages, since there is no such issue when deploying via ZEIT Now 🤷‍♂️
Redirects it's big headache, as it turned out :(

[endiliey]

Yeah different hosting resolves differently.

Anyway, on the first hand the link shouldnt be '/docs/getting-started-overview/' because docs/getting-started-overview.md will resolve to /docs/getting-started-overview in react-router.
Notice that there is no trailing slash

[lex111]

@frehner can we use Netlify instead of GH Pages?

[joeldenning]

I would rather not switch off of github pages to zeit/netlify. That seems like an unreasonable requirement of using docusaurus.

[lex111]

I agree, but this is not a Docusaurus requirement. In this case, the problem with the processing of redirects, this is not directly related to Docusaurus. You can easily switch to Zeit (Netlify alas has the same behavior as GH Pages), but if you don't want to, it is fine for me. Any way, redirects are temporary, and after a while you can remove their functionality, I think.

[endiliey]

Shouldn't we like close this issue. We have solved the dark mode problem few releases ago too..

[joeldenning]

Yeah it seems to be working fine. I don't remember why there was discussion about switching off of github pages to zeit/netlify, something about redirects/routing maybe. But we've been using the new version of docusaurus for the live site for a while now, so we can close this.

[joeldenning]

FYI docusaurus@2.0.0-alpha.39 breaks things for us. I upgraded to alpha 37 for versioned documentation support, but had to pin to alpha 37 because alpha 39 breaks things. See related #131

[endiliey]

@joeldenning its because of mdx parsing bug. But anyway it will be fixed in next release. See facebook/docusaurus#2105

[joeldenning]

👍 thanks I'll follow that issue

Another thing - I have a new page whose route makes use of query parameters. The routes.js file is confusing to me since all my modifications to it are overwritten by docusaurus. My preferred route is /error (without a trailing slash) because we have other code and websites linking to the route without the slash. However, there seems to be no way to accomplish this. I couldn't find good documentation for routes.js (I'm much more used to vanilla react router) and stuck.

The reason why the trailing slash is problematic is because when I go to https://single-spa.js.org/error?code=1 it does a redirect to /error/ and loses the query parameters entirely, which breaks the functionality. The redirect is occurring with the docusaurus-plugin-redirect that @lex111 added as a backwards compatibility layer for requests made with .html in the extension.

You can take a look at the four most recent commits on master branch to see what I'm referring to. Do you have any tips on how I can get the route to not have a trailing slash?

[endiliey]

/src/pages/foo/test.js → /foo/test
/src/pages/foo/index.js → /foo/

[joeldenning]

I understand how Docusaurus makes magic routes out of file paths. What I'm saying is that I don't like the magic routes and want to change them. There are two things that would help me:

1. Instead of a route path of /foo/, I want /foo.
2. Make the redirects plugin carry over the query parameters.

[endiliey]

You'll have to write your own plugin to add route then :|

It's basically just this for /src/pages
https://github.com/facebook/docusaurus/blob/master/packages/docusaurus-plugin-content-pages/src/index.ts

https://v2.docusaurus.io/docs/lifecycle-apis/#async-contentloadedcontent-actions

[joeldenning]

👍 thanks for the info

[joeldenning]

FYI I got the redirects to preserve query strings with some document.write() magic - https://github.com/CanopyTax/single-spa.js.org/blob/master/website/src/plugins/docusaurus-plugin-redirects/src/index.js#L35

[endiliey]

Well, i guess you can always do that 😆

[joeldenning]

Plus I created single-spa/single-spa#406 which changes over most of the links to the page to have a trailing slash.