Migrate Website to Docusaurus 2 Alpha

[scottilee]

Hi there! 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 helping you migrate and be the POC throughout the migration process. Let me know what you think!

cc @yangshun @wgao19

[fredemmott]

FYI we’re also considering rewriting this site in Hack, reusing the existing docs.hhvm.com code.

If we did use docusaurus 2, the syntax highlighting would need to support Hack - and the PHP highlighter is no longer usable. If you’re using the same library as GitHub itself, that works, or if you can import vscode syntax highlighting definitions. We don’t want to maintain another syntax highlighting definition.

[turadg]

Looks like Docusaurus v2 uses https://prismjs.com/ for highlighting (instead of highlight.js in v1).

PrismJS doesn't claim support for Hacklang (https://prismjs.com/#supported-languages) and it has its own language definition DSL (https://prismjs.com/extending.html#language-definitions). I don't know the work to convert https://github.com/github/linguist or VS Code definitions to PrismJS's.

[fredemmott]

It would need to be fully automated; the ideal path forward would be if Docusaurus added support for a library that supports textmate grammars.

@bolinfest had a demo of Monaco Editor with TextMate support, but I don't know the current state, or what would be involved in docusaurus support.

[jjergus]

This repo is just the front page at https://hacklang.org/, isn't it? (every link there goes to docs.hhvm.com or elsewhere)

It has 3 hardcoded examples that basically never changed so setting up a full syntax highlighting library for that might be overkill, or at least doesn't need to be a hard blocker.

I should probably migrate the deployment of this repo to use GitHub Actions (or whatever GitHub Pages normally uses) because CircleCI is failing -- might be a good opportunity to migrate to the new Docusaurus version at the same time.

[fredemmott]

@jjergus yep. Two questions make this more complicated than just porting what we have:

• should we unify it with docs.hhvm.com to have a more cohesive UI etc - and to have hacklang.org running in hack :p
• are we going to bring back the interactive tutorial? In which case, we'll want some custom fanciness. This is blocked by the rust typechecker work - which is compilable to webasm, but not ready

[fredemmott]

"No" is fine for both of those, just should decide that first :)

[bolinfest]

FYI, https://github.com/bolinfest/monaco-tm is an up-to-date example of using TextMate grammars with Monaco, though you don't actually need to use Monaco to produce syntax highlighted code samples. Perhaps I should try to create a small npm package that provides a React component to display code snippets.