Update sidebar navigation for version 3.9 of English and Japanese docs #597

josh-wong · 2024-12-04T06:21:06Z

Caution

This PR should not be merged until after we're ready to add the displayed_sidebar: docsEnglish configuration to the front-matter properties of English docs and displayed_sidebar: docsJapanese configuration to the front-matter properties of Japanese docs. By adding this configuration, we can specify the appropriate sidebar language that should be displayed for the respective language when the visitor is on a page.

This method follows Docusaurus's method for sidebars, as described in Understanding sidebar association.

Description

This PR updates the sidebar navigation for ScalarDL 3.9 (and will apply to later versions as well). Since we'll be hard-coding titles (labels) in the sidebar navigation in the near future, we should address this now before it becomes an issue.

If we don't specify which sidebar navigation to show for each language, the sidebar navigation for Japanese docs would show in English.

Note

We hard-code the titles (labels) in the sidebar navigation so that we can make the titles shorted in the sidebar navigation while keeping longer titles at the top of each doc. Keeping titles within the actual doc provides readers with better context and is better for SEO.

See an example of the sidebar navigation at:

https://674ff389d1a359f671379685--scalardl-category-indexes-202412.netlify.app/docs/latest/
- The sidebar changes exist only for 3.9 docs.

Related issues and/or PRs

Changes to doc front-matter properties: https://github.com/scalar-labs/docs-internal-scalardl/pull/286

Note

Similar changes are being done in the ScalarDB docs:

Sidebar changes: Add sidebar navigation for Japanese docs docs-scalardb#762
Changes to doc front-matter properties: https://github.com/scalar-labs/docs-internal-scalardb/pull/658

Changes made

Changed the default sidebar name from docs to docsEnglish.
Added a sidebar structure for Japanese docs (docsJapanese) that matches the English docs.
Translated the titles (labels) in the docsJapanese sidebar into Japanese.

Checklist

The following is a best-effort checklist. If any items in this checklist are not applicable to this PR or are dependent on other, unmerged PRs, please still mark the checkboxes after you have read and understood each item.

I have updated the side navigation as necessary.
I have commented my code, particularly in hard-to-understand areas.
I have updated the documentation to reflect the changes. N/A
Any remaining open issues linked to this PR are documented and up-to-date (Jira, GitHub, etc.).
My changes generate no new warnings.
Any dependent changes in other PRs have been merged and published.

Additional notes (optional)

N/A

This navigation is necessary since we will be hard-coding titles (`labels`) in the sidebar navigation in the near future. Without this, the sidebar navigation for Japanese docs would show in English.

jnmt

Thank you! Almost LGTM. I left a few comments. PTAL!

sidebars.js

versioned_sidebars/version-3.9-sidebars.json

sidebars.js

netlify · 2024-12-19T09:32:21Z

✅ Deploy Preview for staging-scalardl-docs-site ready!

Name	Link
🔨 Latest commit	`f1ff29a`
🔍 Latest deploy log	https://app.netlify.com/sites/staging-scalardl-docs-site/deploys/6763e7f2c703bc0008f882e1
😎 Deploy Preview	https://deploy-preview-597--staging-scalardl-docs-site.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
Lighthouse	1 paths audited Performance: 55 Accessibility: 98 Best Practices: 92 SEO: 96 PWA: 90 View the detailed breakdown and full score reports

To edit notification comments on pull requests, go to your Netlify site configuration.

josh-wong

@jnmt Thank you for the review! I've applied your suggestions in 0b2c8fe and f1ff29a. PTAL again when you have time.

sidebars.js

jnmt

Thank you for revising it! I left a very minor improvement, but basically LGTM.

sidebars.js

jnmt · 2024-12-20T09:16:19Z

sidebars.js

+        {
+          type: 'doc',
+          id: 'use-generic-contracts',
+          label: '汎用コントラクトおよびファンクションの使用',


Probably, this is consistent with others, and a short one might be better.

Suggested change

label: '汎用コントラクトおよびファンクションの使用',

label: '汎用コントラクトを使用する',

Ah, thank you for mentioning this!

In a PR for the ScalarDB sidebar, @/feeblefakie mentioned noun form and verb form. In that PR, I changed them to noun form, so I've done the same in the sidebars in this PR as well in 7e4b2e0.

Make Japanese titles consistently use noun form, as mentioned in the PR for the ScalarDB sidebar navigation (https://github.com/scalar-labs/docs-scalardb/pull/762/files/1c1b5404f5b23485105ae6a17a42977ecdc5aac3#r1869009005).

josh-wong

@jnmt I address your comment and made some related changes in 7e4b2e0. PTAL!

josh-wong · 2024-12-23T07:49:17Z

sidebars.js

+        {
+          type: 'doc',
+          id: 'use-generic-contracts',
+          label: 'Use Generic Contracts and Functions',


@jnmt As mentioned in your comment for the Japanese phrasing, should we shorten the English wording as well?

Suggested change

label: 'Use Generic Contracts and Functions',

label: 'Use Generic Contracts',

josh-wong · 2024-12-23T07:50:07Z

sidebars.js

+        {
+          type: 'doc',
+          id: 'use-generic-contracts',
+          label: '汎用コントラクトおよびファンクションの使用',


Ah, thank you for mentioning this!

In a PR for the ScalarDB sidebar, @/feeblefakie mentioned noun form and verb form. In that PR, I changed them to noun form, so I've done the same in the sidebars in this PR as well in 7e4b2e0.

sidebars.js

feeblefakie · 2024-12-24T04:06:38Z

sidebars.js

+                  type: 'doc',
+                  id: 'scalar-kubernetes/CreateBastionServer',
+                  label: 'Create a Bastion Server',
+                },
              ],
            },
            {
              type: 'category',
              label: 'Cluster Guides',


I don't think Cluster Guides and Container Image Guides are needed in the sidebar because they are part of deployment and covered by the Deployment guides.

Although I'm OK with not showing these docs in the sidebar in the future, as long as the content is available in the other docs, I do have one concern.

Many other docs link to these docs listed in this sub-category. If we remove these docs from the sidebar, when a visitor clicks a link to go to these pages, then the sidebar navigation will not be displayed on those pages. I think not showing the sidebar navigation would be confusing for users because they would need to go back to the previous page or go to the home page to see the sidebar navigation again.

With that in mind, how about we address this in a different PR?

kota2and3kan

Thank you for the updates! (And sorry for my late review...)
I left several comments and suggestions.
Please take a look when you have time! 🙇‍♂️

kota2and3kan · 2024-12-25T10:24:19Z

sidebars.js

+        {
+          type: 'doc',
+          id: 'getting-started-auditor',
+          label: 'Run a Contract Through ScalarDL Ledger and ScalarDL Auditor',


Suggested change

label: 'Run a Contract Through ScalarDL Ledger and ScalarDL Auditor',

label: 'Run a Contract Through ScalarDL Auditor mode',

I think we can make the label length short if we can use the term Auditor mode.

However, I don't know whether we can use the term Auditor mode as an official term.

If we should not use Auditor mode, I think we can keep the current label name as is.

@feeblefakie @jnmt
What do you think?

kota2and3kan · 2024-12-25T10:43:27Z

sidebars.js

+        {
+          type: 'doc',
+          id: 'installation-with-docker',
+          label: 'Install ScalarDL in Your Local Environment',


Suggested change

label: 'Install ScalarDL in Your Local Environment',

label: 'Install ScalarDL in Your Local Environment with Docker',

Now, we are creating another document Deploy ScalarDL Ledger Locally that uses Minikube to deploy ScalarDL locally in another PR.
https://github.com/scalar-labs/docs-internal-orchestration/pull/83

So, I think it would be better to mention with Docker explicitly here to avoid unnecessary confusion.

What do you think?
(If with Docker is too long, let me consider other ideas.)

kota2and3kan · 2024-12-25T10:49:40Z

sidebars.js

+        {
+          type: 'doc',
+          id: 'generic-contracts-reference',
+          label: '汎用コントラクトおよびファンクション',


Suggested change

label: '汎用コントラクトおよびファンクション',

label: 'Generic Contracts Reference',

It seems that we should use English here.

I think we don't treat Generic contracts as a proper noun. So, I think it's fine as is.
Maybe, it's better to be just 汎用コントラクト.

@feeblefakie
Ah, sorry. My comment was a bit ambiguous.

Here is the docsEnglish section. Not the docsJapanese section.

So, simply we should use English here. I think it was translated by accident.

According to your suggestion, it might be better to use Generic Contracts (without Reference) here though.

kota2and3kan · 2024-12-25T10:51:37Z

sidebars.js

+            {
+              type: 'doc',
+              id: 'scalardl-java-client-sdk/README',
+              label: 'ScalarDL Java クライアント SDK',


Suggested change

label: 'ScalarDL Java クライアント SDK',

label: 'ScalarDL Java Client SDK',

I think ScalarDL Java Client SDK is a component name. So, I think we should not translate Client here.

kota2and3kan · 2024-12-25T11:04:11Z

sidebars.js

+        {
+          type: 'doc',
+          id: 'authentication',
+          label: '認証を使用',


Suggested change

label: '認証を使用',

label: '認証',

I think 認証 is simple and better because the origin English word is Authentication.

kota2and3kan · 2024-12-25T11:40:29Z

versioned_sidebars/version-3.9-sidebars.json

+                {
+                  "type": "doc",
+                  "id": "scalar-kubernetes/BackupRDB",
+                  "label": "Kubernetes で RDB をバックアップ"


Suggested change

"label": "Kubernetes で RDB をバックアップ"

"label": "Kubernetes 環境で RDB をバックアップ"

Same as sidebars.js.

kota2and3kan · 2024-12-25T11:40:39Z

versioned_sidebars/version-3.9-sidebars.json

+                {
+                  "type": "doc",
+                  "id": "scalar-kubernetes/BackupNoSQL",
+                  "label": "Kubernetes で NoSQL データベースをバックアップ"


Suggested change

"label": "Kubernetes で NoSQL データベースをバックアップ"

"label": "Kubernetes 環境で NoSQL データベースをバックアップ"

Same as sidebars.js.

kota2and3kan · 2024-12-25T11:40:51Z

versioned_sidebars/version-3.9-sidebars.json

+                {
+                  "type": "doc",
+                  "id": "scalar-kubernetes/RestoreDatabase",
+                  "label": "Kubernetes でデータベースを復元"


Suggested change

"label": "Kubernetes でデータベースを復元"

"label": "Kubernetes 環境でデータベースを復元"

Same as sidebars.js.

kota2and3kan · 2024-12-25T11:42:44Z

sidebars.js

+        {
+          type: 'doc',
+          id: 'getting-started-auditor',
+          label: 'ScalarDL Ledger と ScalarDL Auditor を通じてコントラクトを実行',


Suggested change

label: 'ScalarDL Ledger と ScalarDL Auditor を通じてコントラクトを実行',

label: 'ScalarDL Auditor モードを通じてコントラクトを実行',

If we can use Auditor mode as an official word, we can make this label shorter.

kota2and3kan · 2024-12-25T11:43:17Z

versioned_sidebars/version-3.9-sidebars.json

+        {
+          "type": "doc",
+          "id": "getting-started-auditor",
+          "label": "ScalarDL Ledger と ScalarDL Auditor を通じてコントラクトを実行"


Suggested change

"label": "ScalarDL Ledger と ScalarDL Auditor を通じてコントラクトを実行"

"label": "ScalarDL Auditor モードを通じてコントラクトを実行"

Same as sidebars.js.

Add docsJapanese navigation

71de214

This navigation is necessary since we will be hard-coding titles (`labels`) in the sidebar navigation in the near future. Without this, the sidebar navigation for Japanese docs would show in English.

josh-wong added the sidebar navigation Updates to the sidebar navigation label Dec 4, 2024

josh-wong self-assigned this Dec 4, 2024

josh-wong mentioned this pull request Dec 4, 2024

Add sidebar navigation for Japanese docs scalar-labs/docs-scalardb#762

Merged

6 tasks

josh-wong added 2 commits December 19, 2024 11:34

Merge branch 'main' into sidebar-nav/update-structure

1b04c53

Update sidebars

e15e2c9

josh-wong requested review from feeblefakie, jnmt and kota2and3kan December 19, 2024 03:24

josh-wong marked this pull request as ready for review December 19, 2024 03:24

jnmt reviewed Dec 19, 2024

View reviewed changes

sidebars.js Outdated Show resolved Hide resolved

versioned_sidebars/version-3.9-sidebars.json Outdated Show resolved Hide resolved

sidebars.js Show resolved Hide resolved

josh-wong added 2 commits December 19, 2024 18:28

Revise Helm Chart title

0b2c8fe

Add ja-jp docs for generic contracts and error codes

f1ff29a

josh-wong commented Dec 19, 2024

View reviewed changes

sidebars.js Outdated Show resolved Hide resolved

sidebars.js Show resolved Hide resolved

jnmt approved these changes Dec 20, 2024

View reviewed changes

Make Japanese titles consistent with ScalarDB titles

7e4b2e0

Make Japanese titles consistently use noun form, as mentioned in the PR for the ScalarDB sidebar navigation (https://github.com/scalar-labs/docs-scalardb/pull/762/files/1c1b5404f5b23485105ae6a17a42977ecdc5aac3#r1869009005).

josh-wong commented Dec 23, 2024

View reviewed changes

josh-wong requested a review from jnmt December 23, 2024 07:59

feeblefakie reviewed Dec 24, 2024

View reviewed changes

Apply suggestions from code review

9680fed

josh-wong requested a review from feeblefakie December 25, 2024 10:04

kota2and3kan reviewed Dec 25, 2024

View reviewed changes

Merge branch 'main' into sidebar-nav/update-structure

30027d5

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Update sidebar navigation for version 3.9 of English and Japanese docs #597

Update sidebar navigation for version 3.9 of English and Japanese docs #597

josh-wong commented Dec 4, 2024 •

edited

Loading

jnmt left a comment

netlify bot commented Dec 19, 2024 •

edited

Loading

josh-wong left a comment

jnmt left a comment

jnmt Dec 20, 2024

josh-wong Dec 23, 2024

josh-wong left a comment

josh-wong Dec 23, 2024

josh-wong Dec 23, 2024

feeblefakie Dec 24, 2024

josh-wong Dec 25, 2024

kota2and3kan left a comment

kota2and3kan Dec 25, 2024

kota2and3kan Dec 25, 2024

kota2and3kan Dec 25, 2024

feeblefakie Dec 27, 2024

kota2and3kan Dec 27, 2024

kota2and3kan Dec 25, 2024

kota2and3kan Dec 25, 2024

kota2and3kan Dec 25, 2024

kota2and3kan Dec 25, 2024

kota2and3kan Dec 25, 2024

kota2and3kan Dec 25, 2024

kota2and3kan Dec 25, 2024

	label: '汎用コントラクトおよびファンクションの使用',
	label: '汎用コントラクトを使用する',

	label: 'Use Generic Contracts and Functions',
	label: 'Use Generic Contracts',

	label: 'Run a Contract Through ScalarDL Ledger and ScalarDL Auditor',
	label: 'Run a Contract Through ScalarDL Auditor mode',

	label: 'Install ScalarDL in Your Local Environment',
	label: 'Install ScalarDL in Your Local Environment with Docker',

	label: '汎用コントラクトおよびファンクション',
	label: 'Generic Contracts Reference',

	label: 'ScalarDL Java クライアント SDK',
	label: 'ScalarDL Java Client SDK',

	"label": "Kubernetes で RDB をバックアップ"
	"label": "Kubernetes 環境で RDB をバックアップ"

	"label": "Kubernetes で NoSQL データベースをバックアップ"
	"label": "Kubernetes 環境で NoSQL データベースをバックアップ"

	"label": "Kubernetes でデータベースを復元"
	"label": "Kubernetes 環境でデータベースを復元"

	label: 'ScalarDL Ledger と ScalarDL Auditor を通じてコントラクトを実行',
	label: 'ScalarDL Auditor モードを通じてコントラクトを実行',

	"label": "ScalarDL Ledger と ScalarDL Auditor を通じてコントラクトを実行"
	"label": "ScalarDL Auditor モードを通じてコントラクトを実行"

Update sidebar navigation for version 3.9 of English and Japanese docs #597

Are you sure you want to change the base?

Update sidebar navigation for version 3.9 of English and Japanese docs #597

Conversation

josh-wong commented Dec 4, 2024 • edited Loading

Description

Related issues and/or PRs

Changes made

Checklist

Additional notes (optional)

jnmt left a comment

Choose a reason for hiding this comment

netlify bot commented Dec 19, 2024 • edited Loading

✅ Deploy Preview for staging-scalardl-docs-site ready!

josh-wong left a comment

Choose a reason for hiding this comment

jnmt left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

josh-wong left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

kota2and3kan left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

josh-wong commented Dec 4, 2024 •

edited

Loading

netlify bot commented Dec 19, 2024 •

edited

Loading