Hi, Sheng Wu, I noticed that SkyWalking keeps the version docs by using different commit ids[1], a good way for me to rethink and learn.
BTW, we have updated the documentation for Apache APISIX Ingress Controller[2], as for other projects, will get updated soon. Welcome to take a look at the new documentation site! [1] https://github.com/apache/skywalking-website/blob/master/data/docs.yml#L10-L21 [2] https://apisix.apache.org/docs/ingress-controller/design Best Regards! @ Zhiyuan Ju <https://github.com/juzhiyuan> Sheng Wu <wu.sheng.841...@gmail.com> 于2021年2月25日周四 下午2:38写道： > Zhiyuan > > Have you rechecked how SkyWalking do this? > The menu could be in version control and managed in the target repo. > > Sheng Wu 吴晟 > Twitter, wusheng1108 > > > Zhiyuan Ju <juzhiy...@apache.org> 于2021年2月23日周二 下午10:06写道： > > > Hi, folks, > > > > Thanks for @qier222's help, after researching and trying Docusaurus[1], > we > > need to do two things to have a unified documentation style. > > > > 1. The apisix-website repo will fetch markdown files from resource repo, > > e.g apisix/apisix-dashboard/apisix-ingress-controller, and will put them > at > > the correct folder, then build & deploy. > > > > 2. Resource repos like apisix/apisix-dashboard need to adjust their docs > > folder structure like this. > > > > ``` > > . > > └── apisix > > ├── README.md > > └── docs > > ├── assets > > │ └── images > > │ └── sample.png > > ├── en > > │ ├── 2.3 > > │ │ ├── config.json > > │ │ ├── getting-started.md > > │ │ └── plugins > > │ │ ├── jwt-auth.md > > │ │ └── key-auth.md > > │ └── latest > > │ ├── config.json > > │ ├── getting-started.md > > │ └── plugins > > │ ├── jwt-auth.md > > │ └── key-auth.md > > └── zh > > > > 10 directories, 10 files > > ``` > > > > As for the `config.json` file, it's used to store some configurations > for a > > specified version, > > > > ```json > > { > > "version": 2.3, > > "sidebar": { > > "Get Involved": ["getting-started"], > > "Plugins": ["jwt-auth-id", "key-auth-id"] > > } > > } > > ``` > > > > @qier222 will take the first task, to update the apisix-website repo. As > > for the second task, if the structure above is ok, we will work on it as > > soon as possible :) > > > > [1] https://docusaurus.io/ > > > > Best Regards! > > @ Zhiyuan Ju <https://github.com/juzhiyuan> > > > > > > Zhiyuan Ju <juzhiy...@apache.org> 于2021年2月23日周二 上午6:36写道： > > > > > Hi Zexuan, > > > > > > Both put all i18n markdown files in a single repo and different repos > are > > > ok to fetch, for now, I would prefer putting them in a single repo, > here > > > are my reasons, > > > > > > 1. Easy to maintain for the community; > > > 2. Will have more contributors in that single repo; > > > > > > Best Regards! > > > @ Zhiyuan Ju <https://github.com/juzhiyuan> > > > > > > > > > Zexuan Luo <spacewan...@apache.org> 于2021年2月22日周一 上午11:12写道： > > > > > >> So the multiple languages need to hold in a single repo? Or they can > > >> be fetched separately? > > >> > > >> Zhiyuan Ju <juzhiy...@apache.org> 于2021年2月20日周六 下午2:29写道： > > >> > > > >> > Hi, folks, > > >> > > > >> > After searching and comparing those doc frameworks like > > >> > Hugo/Docsify/Docusaurus/KongHQ_Doc, I would prefer using > Docusaurus[1] > > >> to > > >> > build our doc site. > > >> > > > >> > The Docusaurus: > > >> > - Supports multiple languages. > > >> > - Support for multiple versions. > > >> > - Support for Algolia site-wide text search. > > >> > - Relying only on front-end components such as React, not involving > > >> > languages such as Ruby and Golang. > > >> > - Clear component division for easy development and maintenance. > > >> > - Robust community from Facebook, clear project documentation, and a > > >> > configurable way to get started quickly, allowing developers to > focus > > on > > >> > web business and maintainers to focus on documentation quality. > > >> > > > >> > We now have those projects: > > >> > - apisix > > >> > - apisix-ingress-controller > > >> > - apisix-dashboard > > >> > - apisix-docker > > >> > - apisix-helm-chart > > >> > > > >> > And we could follow those steps: > > >> > 1. Develop document specifications: directory structure, file > > >> > meta-information format, static resource storage location. For each > > >> > project, they will have a fixed URL like: > > >> > - https://apisix.apache.org/docs/apisix/2.3/en/getting-stared > > >> > - > > https://apisix.apache.org/docs/apisix-dashboard/2.4/en/getting-stared > > >> > 2. Automatic deployment: The documentation site actively fetches new > > >> > content from each project's docs directory and updates the > > documentation > > >> > site with the GitHub Action timer. > > >> > 3. Each project (apisix/apisix-dashboard/xxx) needs to adjust the > > >> contents > > >> > under the docs folder according to the specification. > > >> > > > >> > BTW, we have a contributor Jiahao Wang[2] to help us organize this > > >> > specification, and will update the infrastructure. Once the > > >> specification > > >> > gets done, we will put it in the apisix's website. > > >> > > > >> > [1] https://docusaurus.io/ > > >> > [2] https://github.com/qier222 > > >> > > > >> > Best Regards! > > >> > @ Zhiyuan Ju <https://github.com/juzhiyuan> > > >> > > > >> > > > >> > Sheng Wu <wu.sheng.841...@gmail.com> 于2021年2月14日周日 下午5:51写道： > > >> > > > >> > > I want to share the plan we are doing in the SkyWalking. > > >> > > SkyWalking used to host doc in every repo, and we are going to > keep > > >> this > > >> > > way. > > >> > > But also, at the same time, we know people want to read at the > > >> website, and > > >> > > good for search engine. > > >> > > So, our current ongoing plan to, generating docs on the website > > based > > >> on > > >> > > repo's commit IDs. > > >> > > > > >> > > A WIP PR is here, > > >> https://github.com/apache/skywalking-website/pull/215. > > >> > > > > >> > > > > >> > > Sheng Wu 吴晟 > > >> > > Twitter, wusheng1108 > > >> > > > > >> > > > > >> > > Zhiyuan Ju <juzhiy...@apache.org> 于2021年2月14日周日 下午5:40写道： > > >> > > > > >> > > > Hi, Kishani, > > >> > > > > > >> > > > Thanks for your continuous contribution to the Apache APISIX > > Website > > >> > > first. > > >> > > > > > >> > > > I would prefer the first solution, that put all docs in the > > >> > > apisix-website > > >> > > > repository. Here are my concerns: > > >> > > > > > >> > > > 1. It's easier to maintain only one doc repository than > multiples, > > >> no > > >> > > need > > >> > > > to sync (no matter manually or automatically) from other > > >> repositories; > > >> > > > 2. Yes, we could sync docs automatically from every project's > > >> repository > > >> > > of > > >> > > > course, but we have to set up then obey some Doc Writing rules, > > file > > >> > > > structure rules, and so on. Only in this way, we could have a > > >> universal > > >> > > > feeling to read docs in `apisix.apache.org`. It's not easy to > > obey > > >> those > > >> > > > rules in different repos. > > >> > > > 3. Every project should have some basic and needed docs, like > FAQ, > > >> > > README, > > >> > > > but for more detailed docs, we could use the apisix-website repo > > to > > >> keep > > >> > > > them. > > >> > > > > > >> > > > I would vote +1 for the first solution. > > >> > > > > > >> > > > Best Regards! > > >> > > > @ Zhiyuan Ju <https://github.com/juzhiyuan> > > >> > > > > > >> > > > > > >> > > > kishani kandasamy <kishanik1...@gmail.com> 于2021年2月14日周日 > > 下午3:26写道： > > >> > > > > > >> > > > > Hello community, > > >> > > > > The Apache Apisix website is getting updated by contributors > > >> .This > > >> > > > > discussion is for migrating docs from other projects to the > > >> website. > > >> > > > > > > >> > > > > Here we have some options to do that. > > >> > > > > > > >> > > > > [1]. Move all docs to website, and remove all docs from origin > > >> repo; > > >> > > > > [2]. Use some tools to auto sync docs from other repos, then > > there > > >> > > should > > >> > > > > have a universal rule, or docs from different repo would not > > have > > >> a > > >> > > > uniform > > >> > > > > show style. > > >> > > > > > > >> > > > > Or there has some other ways? > > >> > > > > > > >> > > > > I would prefer the [1]. > > >> > > > > What do you think? Any feedback is welcome. Thanks! > > >> > > > > > > >> > > > > Regards, > > >> > > > > Kishani. > > >> > > > > > > >> > > > > > >> > > > > >> > > > > > >
