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
