upgrade to docusaurus-v2 #233

slorber · 2020-05-28T15:57:38Z

WIP #234

slorber · 2020-05-29T16:31:39Z

Hi @sw-yx @yangshun @wgao19, I think it's not far to be complete.

Will look to find the last details.

=> https://deploy-preview-233--react-typescript-cheatsheet.netlify.app/

There are probably a few choices to be made regarding the new features of v2, like:

dark mode default?
sidebar: collapse categories by default?
... probably others

I think the user showcase page is quite useless for this project, do you plan to use it?

Also, there was a "star" button in the footer before, it used a script inserted in the body using data-attributes. I wasn't able to migrate it easily as React overrides the star button on hydration.

Putting it back would probably require to override the default Docusaurus Footer.
Is it something you absolutely want to keep?

slorber · 2020-05-29T17:22:58Z

So far I think everything seems to works fine, I just noticed this annoying interleaving MDX behavior for some details/summary blocks in 3 places:

while it should be:

yangshun · 2020-05-30T04:05:50Z

dark mode default?

We could add this do D2.

sidebar: collapse categories by default?

Not sure exactly what you mean here. We collapse non-active categories by default on initial load. We recently added a feature to allow expanded categories by default so the UX of the sidebar changes. We no longer collapse categories which have been expanded while browsing the docs

Also, there was a "star" button in the footer before

Plenty of Docusaurus v1 sites do this. It's possible to still achieve this via the HTML option in the footer. But our recommendation would be to move it into the hero of the landing page and keeping the footer simple.

yangshun

Thank you for this @slorber! Looks great in general!

docs/advanced/types-react-ap.md

website/docusaurus.config.js

yangshun · 2020-05-30T04:10:12Z

website/docusaurus.config.js

+            /*
+            {
+              label: "Star",
+              class: "footer__link-item github-button",


We didn't document the footer well, but you could do this for the GitHub star button instead - https://github.com/facebook/docusaurus/blob/master/website/docusaurus.config.js#L194-L197

this would be nice! not sure where to pull it from but can investigate later

website/src/css/custom.css

website/src/pages/help.js

website/src/pages/index.js

swyxio · 2020-05-31T16:59:35Z

@slorber looks great so far! @ me if you need anything from me in particular! yes showing the star would be nice but it can be a separate issue if we cant figure it out easily

slorber · 2020-05-31T17:07:16Z

will handle the review tomorrow :)

@yangshun there is a way to setup dark mode by default in D2 (i think I saw it), was just wondering what @sw-yx would like as D2 settings since we have new config options

slorber · 2020-06-01T17:03:48Z

Hey @sw-yx , the workaround suggested by @yangshun worked to add the star button in the footer. It only works in prod mode though, I don't think it's a big deal.

I tried to put this button in the body, using the react wrapper the lib suggested (https://buttons.github.io/), but encountered an issue with the theme not properly applied, and wasn't sure exactly where to put this button on the home page, so for now let's keep it in the footer.

More details: buttons/react-github-btn#7 (comment)

So, I think everything works fine except the inline code blocks in MDX / JSX fragments here:

#233 (comment)

Don't know yet how to solve this :/

yangshun · 2020-06-01T17:21:52Z

So, I think everything works fine except the inline code blocks in MDX / JSX fragments here:

We map to <CodeBlock> in one of the MDX Providers, that's why this happens. Not sure if we should still stick with doing that. Typically I'd recommend changing to markdown syntax and splitting up the lines:


<details>
  <summary><b>No need for 

`readonly`

</b></summary>
...

so that readonly doesn't get mapped to <CodeBlock>, but because of the newline, the result is

I'd recommend doing
<details>
  <summary><b>No need for `readonly`</b></summary>
...

so that it appears fine in the web GitHub README and also somewhat readable on the website.
The ideal situation would be to address this in Docusaurus 2 core though.

slorber · 2020-06-01T17:42:16Z

@yangshun unfortunately I tried both options and it didn't work.

I don't see any way to solve this in userland. Will try to come up with a solution. Not sure I could support `` but I'll try to find a solution.

yangshun · 2020-06-01T17:52:40Z

Yeah that's what I meant by "somewhat readable". I think it's still better than the current one.

slorber · 2020-06-01T18:05:44Z

@yangshun I'm able to make the <code> tag work in the <summary> with the following MDX component override:

const InlineCodeBlock = (props) => <code>{props.children}</code>;

export default {
  code: (props) => {
    const { children } = props;
    if (typeof children === 'string') {
      return <CodeBlock {...props} />;
    }
    return children;
  },
  summary: (props) => (
    <MDXProvider components={{ code: InlineCodeBlock }}>
      <summary>{props.children}</summary>
    </MDXProvider>
  ),
  ...otherComps,
};

Do you think we should add that?

That wouldn't allow the markdown syntax in summary (asked about it here: mdx-js/mdx#628 (comment))

But at least, we can add inline code blocks in a summary

Another option could to have <code inline>state</code>, but requires the user to be aware of the api.

export default {
  code: (props) => {
    const {children, inline} = props;
    if (typeof children === 'string') {
      if ( inline ) {
        return <code>{children}</code>
      }
      else {
        return <CodeBlock {...props} />;
      }
    }
    return children;
  },
};

I think we could document the details / summary in the markdown features anyway, even if it's just basic html, I'm pretty sure this is a quite unknown html feature that's useful for documentation and worth mentioning.

…lock instead of the prism editor context: typescript-cheatsheets/react#233 (comment)

slorber · 2020-06-02T17:58:35Z

Hi @sw-yx

I've made a PR so that it's possible to use inline code tags in summaries: facebook/docusaurus#2868

As this is a temporary feature until MDX 2 supports proper markdown interleaving, not sure this will be approved.

As this code in summary thing is only used in 3 places, does it matter to you to remove it?
In case we decide to not merge this PR, you could still implement this support in userland by using the swizzle feature and writing your own MDX components.

This code in summary appears in 2 docs:

edit: actually likely to be merged here: facebook/docusaurus#2857

Do you see other things I should change, or is this the last item to fix?

swyxio · 2020-06-02T22:42:41Z

@slorber of course we are going to merge this PR! 😅

I glanced through and I'm fine to remove it. Still feel like Docusaurus should do its best to honor Github Flavored Markdown though.

The footer looks a bit weird... did we decide what to do here?

apart from that everything is looking really good here! site feels fast and is well structured and I am LOVING the dark mode.

slorber · 2020-06-03T11:09:40Z

Sure we are going to merge this one :)

I was talking about a Docusaurus PR here, that actually got closed for a better one that will solve the code tag in summary issue (see) on next release. But you'll have to use <code> (ie JSX) and not markdown, as MDX doesn't support interleaving markdown in JSX so well.

Great to see you like D2

About the footer, to me it looks similar, you don't get the star button hydrated properly on last version?

D1:

D2:

slorber · 2020-06-03T11:15:21Z

Ohhh, on navigate the Star button gets reset by React as it's now a SPA... :(

@yangshun do you have an example D2 site where there is a star button like that by chance? In the footer?

@sw-yx would you be ok to put this Star button somewhere else, as @yangshun suggested to keep the footer simple?

The basic D2 footer is only a list of links ordered by columns. We can override it with a custom React component (theme swizzling / shadowing), but that means more long-term maintenance on your side.

slorber · 2020-06-03T11:24:04Z

@sw-yx one solution would be to use a CSS-only github button. The D1 lib was some global JS script that looked for a link with some specific data attributes, and the fact it's global script only run at mount time does not play well with an SPA.

What about using this one instead?

http://necolas.github.io/css3-github-buttons/

The drawback of CSS only is that you don't have the current number of stars

Another possibility seems to do what @yangshun mentioned and use a "badge" that will draw the github button as an image/svg on the server, querying for a star count:

There are multiple options:

https://github.com/Naereen/badges#github-stars
https://shields.io/category/social

Just deployed that, is it ok for you?

swyxio · 2020-06-03T18:09:06Z

LGTM!!! thank you @slorber @yangshun and everyone else!!!

slorber · 2020-06-03T18:16:51Z

awesome :)

just need to think to upgrade in a few days after alpha.57 release with the fix for the summary/code thing ;)

swyxio · 2020-06-03T18:17:51Z

yup, no problem with that. i just like shipping things as soon as they're mostly ready :) can always bump things after

test

6b2f736

slorber marked this pull request as draft May 28, 2020 15:57

This was referenced May 28, 2020

Docusaurus Site #229

Closed

[Question] featuring react-typescript-cheatsheet in Docusaurus #216

Closed

Migrate Website to Docusaurus 2 Alpha #234

Closed

slorber added 16 commits May 28, 2020 18:28

revert test

372a8de

add .idea to gitignore

02e499c

Docusaurus v2 initial commit

355dd14

fix md parsing error

14b6c1f

fix navbar items

26e9325

migrate help page

0e8ed15

migrate useless users page

c0128a5

migrate homepage

4a677a1

Typescript => TypeScript

1e45720

migrate footer + some details

192257b

fix site tagline

13bd741

replace some inline styles with infima

d7d7213

add primary color

c1a6429

update readme to v2 readme

8b01dcc

addUserUrl

aa9286b

temporarily disable the github star button

7f63050

slorber marked this pull request as ready for review May 29, 2020 16:24

slorber added 2 commits May 29, 2020 18:41

add some space between <detail><summary> etc

6fe2328

prism: default to TS

6e1973a

yangshun reviewed May 30, 2020

View reviewed changes

swyxio added 2 commits June 1, 2020 00:57

Update docusaurus.config.js

1e68366

Update help.js

f00dcc7

slorber added 4 commits June 1, 2020 17:58

remove FB copyrights

e0dafad

useless comments

864a062

useless mediaqueries

2c0e4a0

larger buttons

47978d1

slorber mentioned this pull request Jun 1, 2020

Add a direct theme prop? buttons/react-github-btn#7

Closed

put back github star button in footer

fc38197

slorber force-pushed the docusaurus-v2 branch from 5b3c753 to fc38197 Compare June 1, 2020 17:04

slorber added a commit to slorber/docusaurus that referenced this pull request Jun 2, 2020

using <code> in a <summary> tag should render a regular inline code b…

d25a083

…lock instead of the prism editor context: typescript-cheatsheets/react#233 (comment)

use <code> instead of md syntax in summaries

9d97bc1

slorber mentioned this pull request Jun 2, 2020

fix(v2): allow using inline code in summary tag facebook/docusaurus#2868

Closed

slorber added 2 commits June 3, 2020 13:34

add github star footer item as badge

bf3d320

remove useless global script

f1dcb87

swyxio changed the title ~~docusaurus-v2~~ upgrade to docusaurus-v2 Jun 3, 2020

swyxio merged commit 230fb01 into typescript-cheatsheets:master Jun 3, 2020

swyxio mentioned this pull request Aug 20, 2020

[Long Term Plan] Move to docusaurus #37

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

upgrade to docusaurus-v2 #233

upgrade to docusaurus-v2 #233

slorber commented May 28, 2020 •

edited by swyxio

Loading

slorber commented May 29, 2020 •

edited

Loading

slorber commented May 29, 2020

yangshun commented May 30, 2020

yangshun left a comment

yangshun May 30, 2020

swyxio May 31, 2020

Nihat217716 May 16, 2023

swyxio commented May 31, 2020 •

edited

Loading

slorber commented May 31, 2020

slorber commented Jun 1, 2020

yangshun commented Jun 1, 2020

slorber commented Jun 1, 2020

yangshun commented Jun 1, 2020

slorber commented Jun 1, 2020 •

edited

Loading

slorber commented Jun 2, 2020 •

edited

Loading

swyxio commented Jun 2, 2020

slorber commented Jun 3, 2020

slorber commented Jun 3, 2020

slorber commented Jun 3, 2020 •

edited

Loading

swyxio commented Jun 3, 2020

slorber commented Jun 3, 2020

swyxio commented Jun 3, 2020

upgrade to docusaurus-v2 #233

upgrade to docusaurus-v2 #233

Conversation

slorber commented May 28, 2020 • edited by swyxio Loading

slorber commented May 29, 2020 • edited Loading

slorber commented May 29, 2020

yangshun commented May 30, 2020

yangshun left a comment

Choose a reason for hiding this comment

yangshun May 30, 2020

Choose a reason for hiding this comment

swyxio May 31, 2020

Choose a reason for hiding this comment

Nihat217716 May 16, 2023

Choose a reason for hiding this comment

swyxio commented May 31, 2020 • edited Loading

slorber commented May 31, 2020

slorber commented Jun 1, 2020

yangshun commented Jun 1, 2020

slorber commented Jun 1, 2020

yangshun commented Jun 1, 2020

slorber commented Jun 1, 2020 • edited Loading

slorber commented Jun 2, 2020 • edited Loading

swyxio commented Jun 2, 2020

slorber commented Jun 3, 2020

slorber commented Jun 3, 2020

slorber commented Jun 3, 2020 • edited Loading

swyxio commented Jun 3, 2020

slorber commented Jun 3, 2020

swyxio commented Jun 3, 2020

slorber commented May 28, 2020 •

edited by swyxio

Loading

slorber commented May 29, 2020 •

edited

Loading

swyxio commented May 31, 2020 •

edited

Loading

slorber commented Jun 1, 2020 •

edited

Loading

slorber commented Jun 2, 2020 •

edited

Loading

slorber commented Jun 3, 2020 •

edited

Loading