Upgrade Docusaurus v2 + try to fix Prism

[slorber]

Motivation

Attempt to fix highlighting for python

see facebook/docusaurus#3004

Have you read the Contributing Guidelines on pull requests?

Yes

Test Plan

No

---

http://localhost:3000/docs/next/tutorials/structured_config/minimal_example

http://localhost:3000/docs/next/tutorials/structured_config/nesting

(the imports have the class "keyword", it's just not styled by the theme, so you could improve that).

[slorber]

Note, it's actually upgrading the dependency from 1.1.0 to 1.1.1 that seems to break the highlighting, so I forced the former using:

  "resolutions": {
    "prism-react-renderer": "1.1.0"
  },

You likely upgraded without knowing as it's a minor semver range

[omry]

Thanks for digging!
I tried on a clean website just now (npx @docusaurus/init@next init my-website classic):

It seems to work with Docs or with docs.
Any idea why the difference?

[omry]

Ah, docs plugin is actually what I am using for versioning.

Related : in this, the npm command is not working.

[slorber]

It seems to work with Docs or with docs.
Any idea why the difference?

We want to support multiple instances of docs plugin at the same time in the future. This part is not the most robust or easy to understand with things hardcoded here and there. You should rather use docs. I can't tell you yet why but will know more soon :)

Related : in this, the npm command is not working.

It seems to work for me (using "docs" at least)

[omry]

Is it the same "Docs" from the top bar?

[slorber]

This navbar is just a link with a label and a target, that you can configure in your site config:

[omry]

Ah, cool.
While testing locally, I noticed this change:

In my case I would actually not want to discourage users that are browsing the next version. (I am in pre-release stage and I did not cut a version of the docs yet).
Do you know if this something I can play with in the docs plugin?

[slorber]

You don't need to match the sidebar to the label of this link.

Actually the sidebar attribute name "docs" or "Docs" is more like an idea than a label displayed anywhere.

For example, take a look at Docusaurus 2 website, using 2 different sidebars:

• https://v2.docusaurus.io/docs/design-principles
• https://v2.docusaurus.io/docs/team/

[omry]

For example, take a look at Docusaurus 2 website, using 2 different sidebars:

* https://v2.docusaurus.io/docs/design-principles

* https://v2.docusaurus.io/docs/team/

Holy shit, I never thought you could have two different sidebars. this is awesome.

[slorber]

Unfortunately, this banner is something we added recently and I think there's currently no way to disable it. If you would open an issue so we don't forget. (related facebook/docusaurus#2916)

In a more general way, there's also a feature that has been quite requested to make "next" the "current version".

Yes, 2 different sidebars, and soon we also plan to work on multiple instances (like for example ios sdk vs android sdk, when both don't have different versioning lifecycles)

[omry]

Unfortunately, this banner is something we added recently and I think there's currently no way to disable it. If you would open an issue so we don't forget. (related facebook/docusaurus#2916)

facebook/docusaurus#3013

In a more general way, there's also a feature that has been quite requested to make "next" the "current version".

This has not been a big deal to me, when I want people to start using the next version in earnest I will cut a version.
I know that I can change the default version by ordering versions.json.
Maybe an easy solution for this request is to support it there:

[
  "0.11", 
  "next"
]

VS:

[
  "next",
  "0.11"
]

Yes, 2 different sidebars, and soon we also plan to work on multiple instances (like for example ios sdk vs android sdk, when both don't have different versioning lifecycles).

very nice.