Migrate Docs to Docusaurus 2 Alpha #226

aswathkk · 2019-10-24T04:09:03Z

Live Preview:
https://redux-starter-kit.netlify.com/
Here are some screenshots:

Issue
cc: @yangshun, @endiliey

endiliey

Please deploy it somewhere for easy demo.

website/docusaurus.config.js

website/package.json

website/src/pages/index.js

aswathkk · 2019-10-27T03:53:31Z

@endiliey Live preview is available at https://redux-starter-kit.netlify.com/

markerikson · 2019-10-27T04:13:22Z

As a first quick glance: looking at the Advanced Tutorial, the code block font seems smaller, and the diff-language blocks are not getting highlighted.

endiliey

I would recommend using different theme for the codeblock. eg: vsDark because the default one is palenight and the highlighting is very dependent on theme

https://v2.docusaurus.io/docs/markdown-features#syntax-highlighting

Maybe @markerikson can choose one. Or even build own theme it needed. Theme example: https://github.com/FormidableLabs/prism-react-renderer/tree/master/src/themes

endiliey · 2019-10-27T07:07:39Z

website/src/pages/404.js

+
+  function getTrackingScript() {
+    if (!siteConfig.gaTrackingId) {
+      return null


there is no such field

https://v2.docusaurus.io/docs/docusaurus.config.js

btw why do you need 404.js ? docusaurus handle it for you

Docusaurus is returning a blank content for 404. Don't know why.

Try https://v2.docusaurus.io/sdasjasad

But why https://redux-starter-kit.netlify.com/fdsafdsf is showing a blank content?
I tried removing src/pages/404.js also. But no use.

oh its because redux route basepath is empty so it routes to upper level docpage. Its equivalent to https://v2.docusaurus.io/docs

Did adding 404.js solve the issue though ?

This is fixed in next alpha release.

You can safely remove the 404.js here

Adding 404.js did not resolve the issue.

oh its because redux route basepath is empty so it routes to upper level docpage. Its equivalent to https://v2.docusaurus.io/docs

Sorry. I didn't get this part.

It's a react router concept. You can ignore it for now.

But just to share knowledge

// routes.js export default [ { path: "/docs", component: ComponentCreator("/docs"), routes: [ { path: "/docs/advanced-themes", component: ComponentCreator("/docs/advanced-themes"), exact: true }, { path: "/docs/advanced-plugins", component: ComponentCreator("/docs/advanced-plugins"), exact: true }, ] }, { path: "*", component: ComponentCreator("*") } ];

imagine above scenario. Accessing /docs/xxxx will match /docs/

For redux case, it;s not /docs but / that's why you dont have 404 even if you access /xxxx/ its rendering the parent nested route

endiliey · 2019-10-27T07:09:12Z

website/docusaurus.config.js

+      copyright: `Copyright (c) 2015-present Dan Abramov and the Redux documentation authors.`,
+    },
+    image: 'img/redux-logo-landscape.png',
+    twitterImage: 'img/redux-logo-twitter.png',


does this exist ? i dont think so

endiliey · 2019-10-27T09:30:46Z

Regarding the font size and the diff not showing any color. It's mostly due to theme. The default theme we chose: Palenight has that problem.

Here's some comparison
Palenight

Dracula

vsDark

wgao19 · 2019-10-27T09:19:09Z

website/src/pages/index.js

+      </header>
+      <main>
+        {features && features.length && (
+          <section className={[styles.features, styles.lightBackground].join(' ')}>


the lightBackground style here is breaking dark mode now

wgao19 · 2019-10-27T09:20:17Z

website/src/pages/index.js

+                  >
+                    {image && (
+                      <div className={`text--center ${styles.blockImage}`}>
+                        <img


if we use <img src="link-to-img.svg" />, they won't be able to pick up colors and therefore will not adapt to dark theme here neither. Probably will need to change the implementation here.

wgao19 · 2019-10-27T09:33:26Z

website/src/css/custom.css

+  --ifm-color-primary-light: #825AC2;
+  --ifm-color-primary-lighter: #9B7BCE;
+  --ifm-color-primary-lightest: #B49CDA;
+}


I believe you can add some more css here to address the styling issue raised by @markerikson

As a first quick glance: looking at the Advanced Tutorial, the code block font seems smaller, and the diff-language blocks are not getting highlighted.

The --ifm-font-size-base defaults to 15px from Infima, the underlying CSS framework that Docusaurus 2 uses. Where the base font size in the current RSK site is 16px.

Although, directly changing it to 16px causes some of the navbar item to wrap text. So you may need to tweak there a little bit.

Also the default --ifm-code-font-size is 85% which causes the code block to become smaller.

Meanwhile, the classes in the diff language blocks are properly picked up, but there's no styling. This also can be fixed by adding some custom styling -- just some quick thoughts, there can be plugins / themes that already pick this up.

Edit: And yah, like @endiliey already points out, the palenight theme doesn't pick up the diff code block, maybe we can use another theme?

I believe we're currently using Monokai as the syntax highlighting theme.

aswathkk · 2019-10-29T09:57:14Z

@markerikson Can we use vsDark as the syntax highlighting theme?

markerikson · 2019-11-02T19:07:23Z

@aswathkk : I'd really prefer to stick with Monokai.

So where does this PR stand overall at this point?

wgao19 · 2019-11-05T05:13:12Z

hey @markerikson seems there hasn't been much updates for a week, is it possible that we merge this PR to an intermediate branch at RSK then we (as Docusaurus maintainers) can work on top of that?

Perhaps it is because monokai is not an available theme by prism-react-renderer that Docusaurus 2 uses, but i guess we can convert this.

Looks to me we're mainly missing customized styling at this point.

markerikson · 2019-11-05T05:28:31Z

Given that there's a docs preview here, do we actually need a separate branch?

yangshun · 2019-11-05T05:39:17Z

Agree with @wgao19's approach. I think we need a separate branch so master can still keep the existing docs website and changes can be made to it.

endiliey · 2019-11-05T05:40:33Z

Given that there's a docs preview here, do we actually need a separate branch?

I think the main idea here is to let the maintainer of Docusaurus to continue @aswathkk (not a maintainer) work on the migration.

Given that this PR isn't really ready yet, its not a good idea to push this to master.
If we were to send another PR to RSK that supersedes this PR, that won't be nice to aswathkk since he has put lot of effort into this PR.
The concern here is that the migration has take a while and rounds of reviews is gonna put things more delayed

On another note deploy preview isn't working because the build directory has changed in v2. I recommend using a netlify config like CRA so that not only those who have access to RSK netlify.com setting can modify it.

Normally you had to modify it in netlify.com

But it's better to have it like this
https://github.com/facebook/create-react-app/blob/master/netlify.toml

Edit: ref https://v2.docusaurus.io/docs/migrating-from-v1-to-v2#update-references-to-the-build-directory

markerikson · 2019-11-05T05:59:42Z

Okay, just created a docusaurus-v2-integration branch.

Looks like there's conflicts from my recent changes to the tutorials. Fix those and we can merge this into the integration branch.

Can that Netlify file be added on this branch, or does it need to be in master first?

aswathkk · 2019-11-06T04:32:46Z

@markerikson I've resolved the conflicts.

markerikson · 2019-11-06T04:50:11Z

It's failing to build atm, but yeah, let's go ahead and get this into the integration branch.

Thanks for the work on this!

@endiliey

* Migrate Docs to Docusaurus 2 Alpha (#226) * Migrate to docusaurus 2 * Change docs to MDX format * Make custom 404 compatible with Docusaurus v2 * Removes unwated stuffs as suggested by @endiliey * update doc site .gitignore for Docusaurus 2 * update dependencies for Docusaurus 2 * remove lightBackground class that breaks dark mode * inline svgs to pick up colors by dark theme * make font size align with current RSK site * use monokai css for code block * remove unused files * add netlify.toml * remove unused 404 file * move monokai into custom.css * Update docusaurus, rm -rf useless file & use correct monokai prism theme instead of css" Co-authored-by: Endi <endiliey@gmail.com> * tweak css * tweak codeblock, use line highlighting * line highlight docs * readme * tweaks * tweak monokai * larger code font * workaround for highlighting toc * bold right toc * align inline code snippet style with current rsk site - border radius should be 3px - bg color should be rgba(27, 31, 35, 0.05) * align anchor color with current rsk site - anchor color should be blue - visited color should be redux purple * align pagination pill styles with current rsk site - outline and link colors should be redux purple - hover effect flips color and bg * disable dark mode

endiliey suggested changes Oct 25, 2019

View reviewed changes

endiliey suggested changes Oct 27, 2019

View reviewed changes

wgao19 suggested changes Oct 27, 2019

View reviewed changes

endiliey mentioned this pull request Oct 29, 2019

docs(v2): code block line highlighting facebook/docusaurus#1904

Merged

markerikson mentioned this pull request Oct 29, 2019

Migrate Docs to Docusaurus 2 Alpha reduxjs/redux#3584

Closed

markerikson changed the base branch from master to docusaurus-v2-integration November 5, 2019 05:59

markerikson mentioned this pull request Nov 5, 2019

Bikeshed discussion: naming and marketing, again #246

Closed

aswathkk added 4 commits November 6, 2019 09:34

Migrate to docusaurus 2

0cb9170

Change docs to MDX format

4282b69

Make custom 404 compatible with Docusaurus v2

3e7e426

Removes unwated stuffs as suggested by @endiliey

6fe3ab0

aswathkk force-pushed the docusaurus-upgrade branch from b37cdac to 6fe3ab0 Compare November 6, 2019 04:31

markerikson merged commit 160be2b into reduxjs:docusaurus-v2-integration Nov 6, 2019

wgao19 mentioned this pull request Nov 9, 2019

WiP: Integrate docusaurus 2 #247

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Migrate Docs to Docusaurus 2 Alpha #226

Migrate Docs to Docusaurus 2 Alpha #226

aswathkk commented Oct 24, 2019 •

edited

Loading

endiliey left a comment

aswathkk commented Oct 27, 2019

markerikson commented Oct 27, 2019

endiliey left a comment •

edited

Loading

endiliey Oct 27, 2019

endiliey Oct 27, 2019

aswathkk Oct 28, 2019

endiliey Oct 28, 2019

aswathkk Oct 28, 2019

endiliey Oct 28, 2019 •

edited

Loading

endiliey Oct 28, 2019

endiliey Oct 29, 2019

aswathkk Oct 29, 2019 •

edited

Loading

endiliey Oct 29, 2019 •

edited

Loading

endiliey Oct 27, 2019

endiliey commented Oct 27, 2019 •

edited

Loading

wgao19 Oct 27, 2019

wgao19 Oct 27, 2019

wgao19 Oct 27, 2019 •

edited

Loading

markerikson Oct 27, 2019

aswathkk commented Oct 29, 2019

markerikson commented Nov 2, 2019

wgao19 commented Nov 5, 2019

markerikson commented Nov 5, 2019

yangshun commented Nov 5, 2019

endiliey commented Nov 5, 2019 •

edited

Loading

markerikson commented Nov 5, 2019 •

edited

Loading

aswathkk commented Nov 6, 2019

markerikson commented Nov 6, 2019 •

edited

Loading

Migrate Docs to Docusaurus 2 Alpha #226

Migrate Docs to Docusaurus 2 Alpha #226

Conversation

aswathkk commented Oct 24, 2019 • edited Loading

endiliey left a comment

Choose a reason for hiding this comment

aswathkk commented Oct 27, 2019

markerikson commented Oct 27, 2019

endiliey left a comment • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

endiliey Oct 28, 2019 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

aswathkk Oct 29, 2019 • edited Loading

Choose a reason for hiding this comment

endiliey Oct 29, 2019 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

endiliey commented Oct 27, 2019 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

wgao19 Oct 27, 2019 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

aswathkk commented Oct 29, 2019

markerikson commented Nov 2, 2019

wgao19 commented Nov 5, 2019

markerikson commented Nov 5, 2019

yangshun commented Nov 5, 2019

endiliey commented Nov 5, 2019 • edited Loading

markerikson commented Nov 5, 2019 • edited Loading

aswathkk commented Nov 6, 2019

markerikson commented Nov 6, 2019 • edited Loading

aswathkk commented Oct 24, 2019 •

edited

Loading

endiliey left a comment •

edited

Loading

endiliey Oct 28, 2019 •

edited

Loading

aswathkk Oct 29, 2019 •

edited

Loading

endiliey Oct 29, 2019 •

edited

Loading

endiliey commented Oct 27, 2019 •

edited

Loading

wgao19 Oct 27, 2019 •

edited

Loading

endiliey commented Nov 5, 2019 •

edited

Loading

markerikson commented Nov 5, 2019 •

edited

Loading

markerikson commented Nov 6, 2019 •

edited

Loading