Docs: adds Docusaurus site

[lukegalbraithrussell]

Category

• Document pages under /docs

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.
• I've run ./scripts/install_all_and_run_tests.sh after making the changes.

Summary

This is the new Docusaurus site. Tested that it builds properly.

This is less absurdly large then it looks! ~15,000 of the changed lines are package-lock.json 😬 . Most of the files are from moving stuff around (I used git mv!). I talked to @WilliamBergamin about moving the generated docs -- the reference docs are going in /docs/static now instead of /docs.

Speaking of those reference docs... they don't work with npm run start or npm run build/serve. It doesn't like the .html links being explicit. BUT it works in production. I tested out a page on my personal repo. Weird stuff. I wasted a a few days of my life on that

Anyway, there are about only a few files in this PR that matter for review:

Maintenance files:

• .scripts/generate_api_docs.sh Changed the path where the reference docs go
• .github/maintainers_guide.md. I added a section linking to the docs README
• .workflows/docs-deploy.yml Deploys site on merge, tests on PR
• docs/README.md All the instructions

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
│   └── concepts
│       └── sending-message.md
├── i18n/ja/ (the japanese translations)
│   ├──docusaurus-theme-classic/ (footer/navbar translations)
│   └──docusaurus-plugin-content-docs/
│       └── current/ (this folder's file names need to exactly match **/content/, but japanese content)
│           ├── getting-started.md
│           └── concepts
│               └── sending-message.md
├── static/
│   ├── css/
│   │   └── custom.css (the css for everything!)
│   └── img/ (the pictures for the site)
│       ├── rory.png 
│       └── oslo.svg 
├── src/
│   ├── pages/ (stuff that isn't docs content. This is empty for this repo)
│   └── 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.)

The default name for my 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 - i.e. something in the basics or the advanced folder (and others) has the concepts slug: /bolt-python/concepts/authorization. This is slightly different than the previous site, which took the form of /bolt-python/concepts#authorization. They're all separate pages, not headers now.

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.

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).
• Update tutorials with self-updating GitHub code snippet links.

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 91.80%. Comparing base (8f6f69d) to head (1353ce4).

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #1113   +/-   ##
=======================================
  Coverage   91.80%   91.80%           
=======================================
  Files         186      186           
  Lines        6408     6408           
=======================================
  Hits         5883     5883           
  Misses        525      525           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[zimeg]

Nice!!!! 🤩 These are great changes and I'm a big fan of the build. It's exciting to have a bit more room for code snippets and expanded details for different pages.

Approving this now since I'm confident in these changes - thanks for sifting through so many files 🙏 - but think a few comments are worth checking out before merging.

🚀 Awesomeness in all of these changes and love how it all reads!

[WilliamBergamin]

This is great work 💯

Do you think we can safely remove scripts/run_jekyll.sh?

Also what do you think about enabling dependabot for this directory I think adding the following in .github/dependabot.yml should be sufficient

  - package-ecosystem: "npm"
    directory: "/docs"
    schedule:
      interval: "monthly"

[WilliamBergamin]

Thanks for the changes 💯

Found one more line to address but then we should be good to ship 🚢