HDDS-10885. Add a landing page for each section of the documentation.

[errose28]

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. 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. 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. 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 mostly 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 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 README.mdx errors fails
  • 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 at the Docusaurus build stage with no extra changes required.
• README.mdx files are still subject to the same spelling and front matter checks as other pages:
  • Spelling failure
  • Front matter failure

[errose28]

Apologies in advance for this monster change 😄

@adoroszlai would you be able to review the CI and dev experience portions of this change (everything outside of the docs directory)?

@swagle @umamaheswararao @arp7 can you review the doc content portion of this change (everything inside the docs directory)? As I mentioned in the PR description this part is probably easier to do with the rendered sites instead of GitHub's diff view.

it is probably easiest to use the rendered website. Use the staging site 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.

[adoroszlai]

Thanks @errose28 for the patch, the parts outside docs/ LGTM.

[errose28]

The change set on this PR is understandably daunting, but since Attila has already reviewed the CI portion the final approval really only requires clicking through the docs section of the new website to visually check the changes:

• Docs section structure still makes sense. Minor tweaks were made here from the existing version.
• Breadcrumbs at the top of the docs section work for navigation.
• The summary pages of each docs section (accessible by clicking on the section's name in the sidebar) have descriptions that make sense.

Here's a graphic of one of the new section summary pages to demonstrate the change.

[kerneltime]

Minor nit: Can be done as a separate PR. Changing the port so that it does not conflict with Grafana and moving blogs one level up.

diff --git a/compose.yml b/compose.yml
index b039dfa8..46fba14e 100644
--- a/compose.yml
+++ b/compose.yml
@@ -20,7 +20,7 @@ services:
     build: .
     image: ozone-site
     ports:
-    - 3000:3000
+    - 3001:3000
     volumes:
     - .:/ozone-site
     # The below option is used to prevent overwriting the node_modules directory in the docker image
diff --git a/docusaurus.config.js b/docusaurus.config.js
index 28028689..97adb6ea 100644
--- a/docusaurus.config.js
+++ b/docusaurus.config.js
@@ -142,6 +142,10 @@ const config = {
             to: 'faq',
             label: 'FAQ',
           },
+          {
+            to: 'blogs',
+            label: 'Blogs',
+          },
           {
             label: 'Community',
             items: [
@@ -165,10 +169,6 @@ const config = {
                 to: 'community/events-and-media',
                 label: 'Events and Media',
               },
-              {
-                to: 'community/blogs',
-                label: 'Blogs',
-              },
             ]
           },
           {

[errose28]

Thanks @kerneltime. I moved blogs up for better visibility in this PR since there were already some layout changes here. Port change I will do in #98

[dombizita]

Thanks for working on this @errose28, I checked it locally with docker compose and it looks good to me

[errose28]

Thanks for the reviews everyone