Docs: Adds landing page and redirects (#2179)

slackapi · Aug 1, 2024 · dccafb2 · dccafb2
1 parent f636d75
commit dccafb2
Show file tree

Hide file tree

Showing 11 changed files with 394 additions and 374 deletions.
diff --git a/docs/README.md b/docs/README.md
@@ -10,9 +10,9 @@ docs/
 │   ├── getting-started.md
 │   └── concepts
 │       └── sending-message.md
-├── i18n/ja/ (the japanese translations)
-│   ├──docusaurus-theme-classic/ (footer/navbar translations)
-│   └──docusaurus-plugin-content-docs/
+├── i18n/ja-jp/ (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
@@ -24,17 +24,15 @@ docs/
 │       ├── rory.png 
 │       └── oslo.svg 
 ├── src/
-│   ├── pages/ (stuff that isn't docs content. This is empty for every repo but homepage)
+│   ├── 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)
-├── redirects-hashes.js (a # to / redirects script because the old site used # as pages)
-└── redirects-pages.js (a redirects script for regular pages -- redirects plugin doesn't work with above script)
 └── sidebar.js (manually set where the content docs are in the sidebar.)
 ```
 
 A cheat-sheet:
 * _I want to edit a doc._ `content/*/*.md`
-* _I want to edit a Japanese doc._ `i18n/ja-jp/docusaurus-plugin-content-docs/current/*/*.md`
+* _I want to edit a Japanese doc._ `i18n/ja-jp/docusaurus-plugin-content-docs/current/*/*.md`. See the [Japanese docs README](./docs/README.md)
 * _I want to change the docs sidebar._ `sidebar.js`
 * _I want to change the css._ Don't use this repo, use the home repo and the changes will propagate here.
 * _I want to change anything else._ `docusaurus.config.js`

diff --git a/docs/content/index.md b/docs/content/index.md
@@ -0,0 +1,21 @@
+# Bolt for JavaScript
+
+Bolt for JavaScript is a JavaScript framework to build Slack apps with the latest Slack platform features. Read the [Getting Started Guide](/getting-started) to set up and run your first Bolt app.
+
+Then, head over to the Concepts guides. They'll help you build a Bolt app for whatever use case you may have.
+
+## Getting help
+
+These docs have lots of information on Bolt for JavaScript. There's also an in-depth Reference section. Please explore!
+
+If you otherwise get stuck, we're here to help. The following are the best ways to get assistance working through your issue:
+
+* [Issue Tracker](http://github.com/slackapi/bolt-js/issues) for questions, bug reports, feature requests, and general discussion related to Bolt for JavaScript. Try searching for an existing issue before creating a new one.
+* [Email](mailto:support@slack.com) our developer support team: `support@slack.com`.
+
+## Contributing
+
+These docs live within the [Bolt-JS](https://github.com/slackapi/bolt-js/) repository and are open source.
+
+We welcome contributions from everyone! Please check out our
+[Contributor's Guide](https://github.com/slackapi/bolt-js/blob/main/.github/contributing.md) for how to contribute in a helpful and collaborative way.
diff --git a/docs/docusaurus.config.js b/docs/docusaurus.config.js
@@ -46,21 +46,38 @@ const config = {
     ],
   ],
 
-  clientModules: [
-    require.resolve('./redirects-hashes.js'),
-    require.resolve('./redirects-pages.js'),
+plugins:
+['docusaurus-theme-github-codeblock',
+  [
+    '@docusaurus/plugin-client-redirects',
+    {
+      redirects: [
+        {
+          to: '/getting-started',
+          from: ['/tutorial/getting-started'],
+        },
+        {
+          to: '/',
+          from: ['/concepts','/concepts/advanced','/concepts/basic'],
+        },
+      ],
+    },
+  ],
+
 ],
 
-  plugins:
-    ['docusaurus-theme-github-codeblock',
-  ],
 
   themeConfig:
     /** @type {import('@docusaurus/preset-classic').ThemeConfig} */
     ({
       colorMode: {
         respectPrefersColorScheme: true,
       },
+      docs: {
+        sidebar: {
+          autoCollapseCategories: true,
+        },
+      },
       navbar: {
         title: "Slack Developer Tools",
         logo: {

diff --git a/docs/i18n/ja-jp/README.md b/docs/i18n/ja-jp/README.md
@@ -0,0 +1,122 @@
+# slack.dev
+
+This README describes how the Japanese documentation is created. Please read the [/docs README](./docs/README) for information on _all_ the documentation.
+
+[Docusaurus](https://docusaurus.io) supports using different languages. Each language is a different version of the same site. Therefore, the Japanese documentation and English documentation must have the exact same pages.
+
+If you add a page to the English documentation, then you must add the page to the Japanese documentation too. If you don't speak Japanese, copy the English documentation to the Japanese page. 
+
+There will be English pages on the Japanese site if the pages are not translated yet. Japanese readers will not miss any content, but they may be confused seeing English and Japanese mixed together. Please give us your thoughts on this setup.
+
+Because of this, the sidebar does not need to be updated for the Japanese documentation. It's always the same as the English documentation!
+
+## Testing the Japanese site. 
+
+Please read the [/docs README](./docs/README.md) for instructions. Be sure to run the site in Japanese:
+
+```
+npm run start -- --locale ja-jp
+```
+
+---
+
+## Japanese documentation files
+
+```
+docs/
+├── content/
+│   ├── getting-started.md
+│   └── concepts
+│       └── sending-message.md
+├── i18n/ja-jp
+│   ├── code.json
+│   ├── docusaurus-theme-classic/
+│   │   ├── footer.json
+│   │   └── navbar.json
+│   └── docusaurus-plugin-content-docs/
+│       └── current/
+│           ├── getting-started.md
+│           └── concepts
+│               └── sending-message.md
+```
+
+The Japanese documentation is in `i18n/ja-jp/`. The folder contains `docusaurus-plugin-content-docs`, `docusaurus-theme-classic`, and `code.json`. 
+
+### `docusaurus-plugin-content-docs`
+
+```
+docs/
+├── content/ (English pages)
+│   ├── getting-started.md
+│   └── concepts
+│       └── sending-message.md
+├── i18n/ja-jp
+│   └── docusaurus-plugin-content-docs/ 
+│       └── current/ (Japanese pages)
+│           ├── getting-started.md
+│           └── concepts
+│               └── sending-message.md
+```
+
+The Japanese page files in `i18n/ja-jp/docusaurus-plugin-content-docs/current/` must be the same as the English page files in `docs/content/`. Please keep the file names in English (example: `sending-message.md`)
+
+Each page is a markdown file. If the page is not translated, it will be in English. Simply remove the English words and write Japanese to replace the page. 
+
+Please provide a title in Japanese. It will show up in the sidebar. There are two options:
+
+```
+---
+title: こんにちは
+---
+
+# こんにちは
+
+```
+
+[Read the Docusaurus documentation for info on writing pages in markdown](https://docusaurus.io/docs/markdown-features).
+
+### `docusaurus-theme-classic`
+
+```
+└── i18n/ja-jp
+    └── docusaurus-theme-classic/
+        ├── footer.json
+        └── navbar.json
+```
+
+`docusaurus-theme-classic` You can translate site components (footer and navbar) for the Japanese site. Each JSON object has a `messages` and `description` value:
+    * `message` - The Japanese translation. It will be in English if not translated.
+    * `description` - What and where the message is. This stays in English.
+
+For example:
+
+```
+{
+  "item.label.Hello": {
+    "message": "こんにちは",
+    "description": "The title of the page"
+  }
+}
+```
+
+The JSON files are created with the `npm run write-translations -- --locale ja-jp` command. [Please read the Docusaurus documentation](https://docusaurus.io/docs/i18n/tutorial#translate-your-react-code) for more info.
+
+### `code.json`
+
+```
+└── i18n/ja-jp
+    └── code.json
+```
+
+The `code.json` file is similar to `docusaurus-theme-classic` JSON objects. `code.json` has translations provided by Docusaurus for site elements. 
+
+For example:
+
+```
+  "theme.CodeBlock.copy": {
+    "message": "コピー",
+    "description": "The copy button label on code blocks"
+  },
+```
+
+Be careful changing `code.json`. If you change something in this repo, it will likely need to be changed in the other Slack.dev repos too, like the Bolt-Python repo. We want these translations to match for all Slack.dev sites. 
diff --git a/docs/i18n/ja-jp/docusaurus-plugin-content-docs/current/index.md b/docs/i18n/ja-jp/docusaurus-plugin-content-docs/current/index.md
@@ -0,0 +1,21 @@
+# Bolt for JavaScript
+
+Bolt for JavaScript is a JavaScript framework to build Slack apps with the latest Slack platform features. Read the [Getting Started Guide](/getting-started) to set up and run your first Bolt app.
+
+Then, head over to the Concepts guides. They'll help you build a Bolt app for whatever use case you may have.
+
+## Getting help
+
+These docs have lots of information on Bolt for JavaScript. There's also an in-depth Reference section. Please explore!
+
+If you otherwise get stuck, we're here to help. The following are the best ways to get assistance working through your issue:
+
+* [Issue Tracker](http://github.com/slackapi/bolt-js/issues) for questions, bug reports, feature requests, and general discussion related to Bolt for JavaScript. Try searching for an existing issue before creating a new one.
+* [Email](mailto:support@slack.com) our developer support team: `support@slack.com`.
+
+## Contributing
+
+These docs live within the [Bolt-JS](https://github.com/slackapi/bolt-js/) repository and are open source.
+
+We welcome contributions from everyone! Please check out our
+[Contributor's Guide](https://github.com/slackapi/bolt-js/blob/main/.github/contributing.md) for how to contribute in a helpful and collaborative way.