wangzhigang1999 opened a new issue, #88: URL: https://github.com/apache/paimon-vector-index/issues/88
## Search before asking - [x] I searched the [issues](https://github.com/apache/paimon-vector-index/issues) and found nothing similar. ## Motivation The repository currently keeps its documentation as committed HTML, CSS, and JavaScript under [`docs/`](https://github.com/apache/paimon-vector-index/tree/main/docs). The [Apache Paimon website build](https://github.com/apache/paimon-website/blob/master/.github/workflows/build.yml) publishes these files by copying them into `docs/vector-index` without a build step. This works for a small set of pages, but it becomes harder to maintain as the documentation grows: - Each HTML page carries site structure such as navigation and page metadata. - Contributors edit rendered HTML instead of Markdown. - The vector index pages maintain their own layout and theme, so they can drift from the main Paimon documentation. - We do not have a documentation build that catches broken links and anchors before publication. [Apache Paimon's main documentation](https://github.com/apache/paimon/tree/master/docs) already uses Docusaurus. Using the same generator here would give contributors a Markdown source format and keep the vector index documentation closer to the main site's navigation, colors, typography, search, and mobile behavior. ## Solution Add a small Docusaurus site to this repository and treat Markdown as the documentation source. The vector index repository would own: - the Markdown pages and sidebar structure; - the Docusaurus configuration and the small amount of vector-index-specific styling; - a CI check that builds the static site and validates local links and anchors. The `paimon-website` repository would continue to own publication. Its build workflow would clone this repository, run the Docusaurus build, and copy the generated static files into `docs/vector-index` on the `asf-site` branch. This keeps the existing deployment model. The ASF website still serves static files and does not need a Node.js process at runtime. ### Repository boundary The migration would use two separate pull requests: 1. `apache/paimon-vector-index` adds the Markdown source, Docusaurus build, and documentation checks. 2. `apache/paimon-website` changes the vector index step from copying committed HTML to copying the Docusaurus build output. The website change should merge after the vector index change. Keeping the content and its build configuration in this repository means a documentation change can be reviewed with the code it describes; the website repository only needs to know how to publish the result. ### Compatibility and rollout The migration should preserve the current public links such as `/docs/vector-index/api.html` and `/docs/vector-index/ivf-pq.html`. Docusaurus can generate redirect pages for those paths while using directory-style canonical URLs for new links. A staged rollout would avoid a broken period between the two repositories: 1. Add the Docusaurus source and build while retaining the current `docs/` output. 2. Update `paimon-website` to build and publish the Docusaurus site. 3. Verify the published canonical and legacy URLs, then remove the old committed HTML in a later cleanup. This proposal does not change the Rust build, the vector index APIs, the storage format, or the ASF publication target. ### Why Docusaurus MkDocs can also produce a static site, but it would introduce a second documentation theme and toolchain beside the main Paimon documentation. Docusaurus lets this repository reuse the project's existing conventions and dependencies. The generated output can still be copied into the same subdirectory used today. ## Anything else? I would like feedback on these points before submitting the implementation: - Does the community agree with using Docusaurus and Markdown for this documentation? - Is the staged two-repository rollout above acceptable? - Should this repository keep the Docusaurus project and the Markdown source in separate directories, or place the Markdown under the site directory? ## Are you willing to submit a PR? - [x] I'm willing to submit a PR. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
