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. > > > > > >
