Docs: adds Docusaurus site

[lukegalbraithrussell]

Requirements

• I've read and understood the Contributing Guidelines and have done my best effort to follow them.
• I've read and agree to the Code of Conduct.

Summary

This is the new Docusaurus site. Tested that it builds properly. This is all done in the same way as the Bolt sites.

This is less absurdly large then it looks! 15,000 of the changed lines are package-lock.json 😬 , and 55,000 are from the generated reference (along with like 800 files 😬 😬 ). If you ignore those, this PR is a -2,000 line change. Most of the files listed are from moving stuff around (I used git mv!).

If the github files tab is too laggy to review, I can pull out the reference pages temporarily then add them in after review. Let me know! Or let me know if you think that's too many files and we should flatten them. Demo of what the reference looks like here:

sdk-reference.mov

Anyway, there are about only a few files in this PR that matter for review. If you've looked at the previous PRs, it's all pretty similar

Maintenance files:

• .github/maintainers_guide.md. I added a section linking to the docs README and explained that the reference docs are automatic
• .workflows/docs-deploy.yml Deploys site on merge, tests on PR
• docs/README.md All the instructions
• typedoc.json A list of params for the typedoc generated reference

Site config files:

• docs/babel.config.js This file exists and that’s about it
• docs/docusaurus.config.js The main config file. Also where topbar and footer are set.
• docs/package.json The packages
• /docs/sidebar.js Sets the docs sidebar nav
• /docs/src/css/custom.css The CSS - matches homepage.

The 404 page has two files, for Docusaurus ~ reasons ~

• /docs/theme/NotFound/Content/index The words
• /docs/theme/NotFound/index The page the words go into

Folder and file organization

This shares the same structure as the other sites. At large:

docs/
├── content/ (the good stuff. md and mdx files supported)
│   ├── getting-started.md
│   ├── packages/ (written .md files)
│   │   └── oauth.md
│   └── reference/
│       └── logger/ (generated reference files)
├── static/
│   ├── css/
│   │   └── custom.css (the css for everything!)
│   └── img/ (the pictures for the site)
│       ├── rory.png 
│       └── oslo.svg 
├── src/
│   └── theme (only contains the 404 page)
├── docusaurus.config.js (main config file. also where to set navbar/footer)
├── sidebar.js (manually set where the content docs are in the sidebar.)
└── typedoc.json (typedoc parameters for generating reference from src)

The default name for the content folder was docs but docs/docs was silly. I am open to other names though.

Docs pages: slugs and links

The organization of pages is purposefully kept as similar to the current layout of pages so developers don't get jarred from both a site change and page changes. Slugs are all named matching that previous organization. URLs stay the same.

All .md files were renamed (yes, I used git mv) to match the title and the slug. Everything now matches up.

All markdown reference links were also updated to be up-to-date and working. If it's a link on the site, it now works. I also stripped all the pages of any residual HTML or custom formatting. They should all be the most basic of markdown now.

Editing and managing the site

The README contains a basic docs editing guide. You don't need to worry about the site unless you're touching something inside the /docs folder.

There is a new action workflow: it does a test build on docs PRs and deploys the site on merges to main. It does so also on every release so the generated reference docs stay up-to-date

Next steps

This wouldn't be a DevRel project without some fast follows. This is what I plan on doing after all the sites are live:

• Set up action workflow to update this custom.css if the main site's custom.css is changed.
• General copy editing (I avoided this the best I could in this PR).

[technically-tracy]

Wonderful!

[filmaj]

Looks amazing!

I do have some recommended changes and follow-ups but the Files Changes tab on GitHub simply can't handle the pure unadulterated awesomeness that this PR contains, so I think I'll send a more focussed PR at a later date once this is merged.

The one question I have is how the GitHub workflow included in this PR works with the Pages settings set on this repo?

I suppose the bundled workflow supersedes this Pages deployment setting, and we can disable the Pages? 🤔

[lukegalbraithrussell]

@filmaj This does supersede those settings if the GitHub workflow is ran, but it would still default to trying to build the old site on any PR where the GitHub workflow is not ran. But! Immediately after a site is live I change the Pages settings to only use this set up. It'll look like this (from the Bolt-JS repo, which was in the same situation):

[filmaj]

Awesome!