+1, That’s a good idea.
> On Dec 16, 2022, at 07:07, tison <wander4...@gmail.com> wrote:
>
> Hi,
>
> After several works around the build flow of our official website[1][2][3],
> the content sync and site build flow is debuggable and reproducible now.
>
> However, compared to other Apache projects' websites' project layouts and
> workflow, we still meet two challenges on the Pulsar site:
>
> 1. We don't have a pre-commit workflow for any website-related changes.
> Thus, we don't detect broken links or syntax errors when reviewing new
> patches[4][5][6].
> 2. The website's content is two-level down in `site2/website-next` for
> historical reasons, which is confusing for contributors.
>
> To overcome these two shortcomings, I propose the following:
>
> 1. Move the website's content to the root level, then we have a first-class
> Docu&yarn-based JS project layout. It's more convenient and familiar to
> related developers.
> 2. Host the source of docs in the site repo (apache/pulsar-site) instead of
> under `site2` folder in the main repo and do content sync.
>
> Below are the pros and cons:
>
> Pros
>
> 1. Obviously, we have the pre-commit workflow now. And since we host the
> source of docs in one repo, we don't have to run the pre-commit workflow in
> two places, which can be quite cumbersome to implement.
> 2. The size of the source release of the main repo can be reduced a lot.
> Currently, 63MB out of 140MB of the sources are taken by the site2 folder,
> which we can remove totally. In addition, we carry out full-versioned docs
> every release.
> 3. We can clean up a large portion of "integration" to debug the site
> brittlely on the main repo[7] (etc.) and redundant contribution guide[8].
> This way, when updating docs, we can preview the result in one repo instead
> of actually doing the sync on the fly. In addition, this integration blocks
> we move the website content to the top level since it makes strong
> assumptions about the relative layout.
>
> Cons
>
> The most significant con is that we cannot update the code and docs in one
> patch against apache/pulsar now. You must open a new pull request to
> apache/pulsar-site, cross-reference each other and manage the merge order
> (synchronization).
>
> Alternatives:
>
> To resolve the versioned docs issue, an alternative is to host only the
> user docs along with each version, like Flink does[9]. But it both detaches
> from the Docu framework and requires significant development efforts.
>
> Since it can explicitly change the development flow (that is, you should
> now update docs separately), I am starting this discussion here to reach
> for your feedback.
>
> Welcome to leave your comments!
>
> Best,
> tison.
>
> [1] https://pulsar.apache.org/
> [2] https://github.com/apache/pulsar-site
> [3] https://github.com/apache/pulsar/issues/18014
> [4] https://github.com/apache/pulsar/issues/17599
> [5] https://github.com/apache/pulsar/pull/17863#discussion_r990174850
> [6] https://github.com/apache/pulsar/pull/17853#discussion_r991803704
> [7]
> https://github.com/apache/pulsar/blob/b1f9e351fa4d5aba197d33cfc0c536516b55b61f/site2/website/start.sh
> [8]
> https://pulsar.apache.org/contribute/document-preview/#preview-documentation-changes
> [9] https://github.com/apache/flink/tree/master/docs
