Docs: adds docusaurus site

[lukegalbraithrussell]

Summary

This PR adds a Docusaurus site. Tested that it builds properly. This is all done in the same way as the other sites site.

java-slack-sdk.mov

14,569 of those line changes are from package-lock.json. So it's really a +1900 change

If you've looked at the previous PRs, it's all pretty similar, with the exception of docs/version-config.yml and its use in .workflows/doc-deploy.

You'll see placeholders in markdown files for version values. For example: sdkLatestVersion. The github workflow replaces these placeholders with the values set in docs/version-config.yml. The sdkLatestVersion value is set via scripts/set_version.sh but the other values are changed directly in the file. When a value in version-config.yml is changed, the site is rebuilt automatically due to the github workflow looking for changes to /docs. I tested this all out on my personal deployed docusaurus test site.

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

Maintenance files:

• .scripts/set_version.sh Changed the path of the yml file to update
• .github/maintainers_guide.md. I added a section linking to the docs README
• .github/pull_request_template.md. Removed script reference
• .workflows/docs-deploy.yml Deploys site on merge, tests on PR
• docs/README.md All the instructions
• docs/version-config.yml 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:

java-slack-sdk/
├── .github/
│   └── workflows/
│       └── deploy.yaml (deploys to site, and inserts values from version-config.yml)
├── docs/ (the good stuff. md/mdx files supported)
│   ├── index.md
│   └── guides
│       └── bolt-basics.md
├── i18n/ja-jp/ (the japanese translations)
│   ├── docusaurus-theme-classic/ (footer/navbar translations)
│   └── docusaurus-plugin-content-docs/
│       └── current/ ( file names need to exactly match **/docs/, but japanese content)
│           ├── index.md
│           └── guides
│               └── bolt-basics.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. This is empty for this repo!)
│   └── theme/ (only contains the 404 page)
├── version-config.yml (Where version numbers are set)
├── docusaurus.config.js (main config file. also where to set navbar/footer)
└── sidebar.js (manually set where the docs are in the sidebar.)

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 for the English site.

The Japanese site unfortunately has to have slightly different slugs - they were at /guides/ja/page and docusaurus does /ja/guides/page. At that point, I changed it to /ja-jp/guides/pages to match the other sites. I've added redirects, but they may need to toggle the language once redirected.

All .md files were renamed 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. 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).

Testing

You can run the site locally:

npm install

npm run start

You can build and serve on your computer to swap between english and japanese:

npm run build

npm run serve

Click around! have fun!

Category

Just docs

Requirements

Please read the Contributing guidelines and Code of Conduct before creating this issue or pull request. By submitting, you agree to those rules.

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 74.98%. Comparing base (9db47c3) to head (a94b9a7).

Additional details and impacted files

@@            Coverage Diff            @@
##               main    #1342   +/-   ##
=========================================
  Coverage     74.98%   74.98%           
  Complexity     4189     4189           
=========================================
  Files           451      451           
  Lines         12930    12930           
  Branches       1331     1331           
=========================================
  Hits           9696     9696           
  Misses         2463     2463           
  Partials        771      771           

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

[seratch]

Fantastic! When I run this document site on my local machine, all the Java code snippets are not highlighted while highlighting works for Kotlin, JSON, and XML data. Is this something we should resolve before merging?

[lukegalbraithrussell]

@seratch Nice catch! For some reason Java highlighting isn't enabled by default in Docusaurus. I've added the syntax highlighting for both Java and Groovy

[seratch]

@lukegalbraithrussell Thanks for quickly resolving it!

With the latest revision, the only remaining issue I found is /image/* file access error. For example, img/bolt-middleware.png access from http://localhost:3000/java-slack-sdk/guides/bolt-basics returns not found HTML page instead of the png file. Can I ask you to identify the cause?

[lukegalbraithrussell]

@seratch The pictures are now working. Those shortened /img/path file paths (instead of /docs/static/img/path) only work in markdown it seems. I switched it to markdown!

[seratch]

Thanks for quickly fixing the issue! LGTM now