Extract the doc generation logic into a seperate package

[yqrashawn]

The current sidebar config generation behaviour

The id syntax in docusaurus v2 sidebar is like below

docs/introduction/en/what_is_conflux

docs/introduction/en is the directory contains the what_is_conflux.md doc file. what_is_conflux is the id of the documentation.

This needs users to actively maintain the id every time there's doc file location change.

We made a hack here to enable user just specify the folder in docs dir and doc id so that we don't need user to maintain the location of the doc file, like below.

{ type: "doc", folder: "conflux-portal", id: "introduction" }

Currently, the yarn genconf command runs the script and generates a sidebars.en.js with the docusaurus v2 syntax.

The problem

This gen doc logic should go into @docusaurus/plugin-content-docs, which is used by @docusaurus/preset-classic and then this project.

Recommended solution

Create our own docusaurus preset and custom everything(site design, gen config) in it. Additionally, we need to add multi-language support and integrate it with the soon coming i18n feature.

Summary

We need to

1. fork docusaurus, create a custom preset
2. add the multi-language feature
3. integrate official i18n support into it when the feature releases.

[AngeliaQ]

I think maybe we can wait the official i18n support, or we can deploy different sites with two repos for multiple language requirement

[yqrashawn]

It depends on how they are implementing the i18n feature. If it only supports the text on UI not the contents, we still need to implement the multi-language feature.

Or we can do it like the react community with multiple sites.

[xiaods]

hey, in the early stage, we suggest focusing on content management. if the site only supports English id, how about use English id to manage the Chinese docs. so it make sure works, then we can work in times. I prefer don't add more development resources to refactor the docs site generate feature. we can claim our feature and hear the Docusaurus community's suggestions.

[xiaods]

I don't mind the English interface.

[AngeliaQ]

hey, in the early stage, we suggest focusing on content management. if the site only supports English id, how about use English id to manage the Chinese docs. so it make sure works, then we can work in times. I prefer don't add more development resources to refactor the docs site generate feature. we can claim our feature and hear the Docusaurus community's suggestions.

the problem is how to switch between the Chinese and English. If our goal is to supply the Chinese site, we can deploy different sites with two repos like the react community easily

[xiaods]

@angelia-yuqi-personal docs team original requirement is support multi-language developer site. It will engage all another country's developers to involved. if we can keep the repo is only the one, yes, I agree we can add another Chinese site to a special Chinese developer. if not, I want to mix all docs in one site, just use some category to list here.

[xiaods]

FYI Frank comments

2. 多语言版本是单站点还是多站点？我觉得单站点容易管理。 比如 [简体中文]docs/cn/conflux-portal/overview.md,docs/cn/conflux-portal/treegraph.md ... [简体中文]docs/cn-hk/conflux-portal/overview.md,docs/cn-hk/conflux-portal/treegraph.md ... [English]docs/en/conflux-portal/overview.md,docs/en/conflux-portal/treegraph.md ... [Korean]docs/kr/conflux-portal/overview.md,docs/kr/conflux-portal/treegraph.md ... 你们当前写的hack代码也实现了这个功能。

3.多语言切换， 可以考虑用cookie 或者localstorage 客户端存储

你们可以先把英文先弄出来， 我们施工队负责把中文翻译出来，这些.md 文档应该不会受到i18n 发布的影响。

[cfx-gspos]

we can load all language sidebars with hide status, and then display the current selected language.

This need to inject some custom codes in docs file, I am working on it.

[yqrashawn]

we can load all language sidebars with hide status, and then display the current selected language. This need to inject some custom codes in docs file, I am working on it.

Need to tweak the original classic theme here https://github.com/facebook/docusaurus/tree/master/packages/docusaurus-theme-classic/src/theme

[xiaods]

done by core team.

[xiaods]

@yqrashawn please close this issue.