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