Docusaurus doc preview issues

[crusso]

1. The doc/docusaurus code use to make a live preview of documentation currently uses a hard-coded moc base library, but should use the correctly versioned, matching base library from nix/sources.json. This isn't much of an issue since little of the executable documentation reference base, and most libraries (but not all) will continue to work just fine as the compiler evolves.

2. The navigation sidebar is auto-generated from folder contents, randomly ordered, and includes rogue entries like base index, and other legacy pages not included in the official portal. Needs cleanup and perhaps more sharing with portal's side-bar code (which can easily omit new doc).

3. Dark mode doesn't work with code samples.

[rvanasa]

Fixed the dark mode syntax highlighting issue in this commit on ryan/docusaurus.

The problem was caused by style conflicts between Prism and Highlight.js, so I configured the project to use Sass to switch between different light/dark hl.js themes based on the Docusaurus dark mode setting (i.e. it's a clean solution).

The specific light/dark themes can be reconfigured in src/css/custom.scss.

@chenyan-dfinity

[chenyan-dfinity]

Thanks for the fix!

While you are at this, can we also try to enable line numbers for the code block: https://github.com/dfinity/motoko/blob/master/doc/docusaurus/src/theme/CodeBlock/Content/String.js#L74

The main issue is to configure the line number style to match the rest of the page.

[rvanasa]

I found a way to improve the line numbers, but the solution is necessarily a bit of a hack due to limitations of the CodeJar package. The line numbers also tend to update incorrectly when adding/removing newlines, but this seems to be out of our control without switching to a different code rendering library.

This should be good enough for the previewer, and there might be a more elegant solution for the developer portal (since they're using Tailwind CSS).

Worth noting: the documentation will now trim \n characters from the start/end of code blocks, so let me know if any examples could be affected by this for some reason.

3368

[chenyan-dfinity]

If tailwind makes things simpler, we can also use Tailwind here just to be consistent with portal. But the current approach by overriding style for the line number class looks good to me.

FYI, this was my last attempt for styling line number in the adoc world: https://github.com/dfinity/antora-sdk/blob/master/src/js/vendor/run_repl.js#L83-L94

Worth noting: the documentation will now trim \n characters from the start/end of code blocks, so let me know if any examples could be affected by this for some reason.

Yep, that should be fine.

[chenyan-dfinity]

I am also open to alternatives for codeJar. The requirement is that the code editor should have small code size and small memory, so that we can embed a lot of code blocks in a single page. On the contrary, monaco editor would be too heavyweight for this purpose.