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