errose28 opened a new pull request, #92: URL: https://github.com/apache/ozone-site/pull/92
## What changes were proposed in this pull request? ## Motivation Currently the website's documentation sidebar is defined by a `_category_.yml` file in each *docs* subdirectory. The way we currently have these configured has the following limitations: - We cannot link to sections of the documentation, only individual pages. For example, we cannot send someone a link to the "Quick Start" section like `docs/quick-start`, only to a specific page in the section like `docs/quick-start/installation/docker`. - There is no place to add a summary of what content can be found (or should be added) to which section. - The breadcrumbs at the top of each page cannot be clicked to navigate the site. ## Implementation My initial pass at this involved trying to implement the above with the existing `_category_.yml` files as described in the [docusaurus docs](https://docusaurus.io/docs/sidebar/autogenerated#category-item-metadata). We could add a title, description, and index of content in that section using the yaml file. This had two major issues though: - The `description` field is rendered as a literal string, not markdown which limits what content can be put there. - The URLs generated for these sections appear under the `docs/category` slug regardless of their path in the filesystem. - For example, given the page `docs/quick-start/installation/docker`, the summary for the quick start installation section would be at `docs/category/installation` instead of `docs/quick-start/installation`. It seems like docusaurus "categories" are meant to be a something separate from the sidebar index, and it just provides the option to map them there. What I think we are actually want for this use case is what Docusaurus calls [index documents](https://docusaurus.io/docs/sidebar/autogenerated#category-index-convention). This is a markdown (or mdx) file at the root of each subdirectory that we can fill in with a title and summary just like any other markdown page. We can also automatically generate an index of the pages in this section with the `DocCardList` tag. Docusaurus supports calling these files either `index` or `README` with either `.md` or `.mdx` extensions. I went with `README` because it is automatically displayed when browsing via GitHub like [this](https://github.com/errose28/ozone-site/tree/section-pages-with-index/docs/02-quick-start). I am using the `.mdx` extension since each of these pages has a `DocCardList` react component embedded in it. CI has been updated to make sure that changes in this area continue to follow this convention. ## Summary of Changes This is a large change that can be broken into the following parts: 1. Delete all `_category.yml_` files previously used to add titles to doc sections. 2. Add `README.mdx` files for all doc sections. 3. Some reworking of the docs organization, since I had to review and summarize the entire docs structure as part of this change. 4. Replace CI check requiring `_category.yml_` files with a check requiring `README.mdx` files. 5. Update the contributing guide with instructions for adding a new docs subdirectory/sidebar section. The changes to 4 and 5 are contained in *CONTRIBUTING.md* and the *.github* directory. These are relatively small and can be reviewed with the standard GitHub diff view. To review changes to 1-3, it is probably easiest to use the rendered website. Use the [staging site](https://ozone-site-v2.staged.apache.org/) as the *before*, and build and run these changes locally to get the *after* site. Click through the docs sections to review the changes side by side in different tabs or windows. ## What is the link to the Apache Jira? HDDS-10885 ## How was this patch tested? - Changes previewed locally. - CI passes with the existing changes. - An example run with errors [fails](https://github.com/errose28/ozone-site/actions/runs/9165445567) - When there are issues, a help message is printed to the job summary and the console output of the sidebar check job. - Failing to create a *README.mdx* file for a directory or not including a `DocCardList` at the end causes this failure. - An example run using the `DocCardList` tag without importing it [fails](https://github.com/errose28/ozone-site/actions/runs/9165497333/job/25199111021) at the Docusaurus build stage with no extra changes required. -- 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] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
