HDDS-9866. Add GitHub Actions checks for consistent Docusaurus formatting.

.github/resource/category.schema.json

@@ -0,0 +1,17 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://ozone.apache.org/category.schema.json",
+  "title": "Category",
+  "description": "Validates an allowed subset of keys in Docusaurus _category_.yml files.",
+  "type": "object",
+  "properties": {
+    "label": {
+      "description": "The name of this section shown in the docs sidebar.",
+      "type": "string"
+    }
+  },
+  "required": [
+    "label"
+  ],
+  "additionalProperties": false
+}

.github/resource/frontmatter.schema.json

@@ -0,0 +1,23 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://ozone.apache.org/frontmatter.schema.json",
+  "title": "Frontmatter",
+  "description": "Validates an allowed subset of Docusaurus docs frontmatter.",
+  "type": [ "object", "null" ],
+  "properties": {
+    "sidebar_label": {
+      "type": "string"
+    },
+    "slug": {
+      "description": "Only use slug to specify the base URL for documentation.",
+      "type": "string",
+      "enum": [ "/" ]
+    },
+    "draft": {
+      "description": "Makes pages for incomplete features only visible in development mode.",
+      "type": "boolean"
+    }
+  },
+  "additionalProperties": false
+}
+

.github/scripts/sidebar.sh

@@ -0,0 +1,48 @@
+#!/usr/bin/env sh
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+# Validates docusaurus _category_.yml files used to configure the docs sidebar.
+# Each docs subdirectory should have a _category_.yml file, and it must follow the defined schema.
+# The schema is more restrictive than what Docusaurus allows, and can be used to disallow keys or require all category
+# files to define the same keys.
+
+rc=0
+
+root="$(git rev-parse --show-toplevel)"
+schema="$root"/.github/resource/category.schema.json
+
+# Make sure all docs directories have a category sidebar file.
+for child in $(find "$root"/docs/*); do
+    if [ -d "$child" ]; then
+        category_file="$child/_category_.yml"
+        if [ ! -f "$category_file" ]; then
+            echo "_category_.yml is required for docs subdirectory $child" 1>&2
+            rc=1
+        fi
+    fi
+done
+
+[ "$rc" = 0 ] || exit $rc
+
+# If all category files are present, make sure they follow the schema.
+if ! pnpm ajv validate -s "$schema" -d "$root/docs/**/_category_.yml" 1>/dev/null; then
+    rc=1
+    echo "Sidebar configuration validation failed against JSON schema $schema" 1>&2
+fi
+
+exit "$rc"

.github/workflows/static.yml

@@ -83,3 +83,22 @@ jobs:
       working-directory: ${{ env.script_dir }}
       run: |
         ./markdownlint.sh
+  check-sidebar:
+    runs-on: ubuntu-latest
+    steps:
+    - name: Checkout project
+      uses: actions/checkout@v4
+    - name: Enable corepack
+      run: |
+        corepack enable
+    - name: Use Node.js ${{ env.node_version }}
+      uses: actions/setup-node@v4
+      with:
+        node-version: ${{ env.node_version }}
+        cache: pnpm
+    - name: Install pnpm dependencies
+      run: pnpm install --dev
+    - name: Run docs sidebar check
+      working-directory: ${{ env.script_dir }}
+      run: |
+        ./sidebar.sh

CONTRIBUTING.md

@@ -100,7 +100,7 @@ Docusaurus provides many options for laying out documentation pages and their me
 
 - File names and therefore generated URLs should all be `kebab-case`.
 
-- Let Docusaurus automatically generate the page's title from its top level markdown heading instead of using `title` in the frontmatter. This is different from the sidebar label or URL slug.
+- Let Docusaurus automatically generate the page's title from its top level markdown heading instead of using `title` in the front matter. This is different from the sidebar label or URL slug.
 
 - Use relative file paths for all links between pages.
   - This keeps page links pointing to the current version of the documentation.
@@ -129,7 +129,7 @@ Docusaurus provides many options for laying out documentation pages and their me
           Object Store Bucket Layout
   ```
 
-  - Sidebar labels are automatically generated from page titles. To use a different sidebar label, use the `sidebar_label` property in the page's frontmatter.
+  - Sidebar labels are automatically generated from page titles. To use a different sidebar label, use the `sidebar_label` property in the page's front matter.
 
 - Don't rely on Ozone specific acronyms in the sidebar. This makes docs navigation more beginner friendly.
   - For example, the pages on bucket layouts may be organized as:
@@ -178,7 +178,7 @@ The file names and content of all markdown pages are checked for spelling mistak
 
 - Option 1: If the word is relevant for the whole Ozone project, add it to the `words` list in *cspell.yaml* so that it is considered valid.
 
-- Option 2: If the word is only relevant for one specific page, add an [inline directive](https://cspell.org/configuration/document-settings/) as a comment in the markdown frontmatter of that page only.
+- Option 2: If the word is only relevant for one specific page, add an [inline directive](https://cspell.org/configuration/document-settings/) as a comment in the markdown front matter of that page only.
 
 ### Updating Graphics
 

cspell.yaml

@@ -78,7 +78,6 @@ words:
 - gpg
 - sed
 - mds
-- frontmatter
 - javadoc
 # Misc words
 - acking

docs/07-system-internals/02-data-operations/04-hsync.md

@@ -1,6 +1,6 @@
 ---
-# Page is accessible by direct link only in production site builds. It can be included in the sidebar when the feature is complete.
-unlisted: true
+# Page is available only in the development server. It can be included in production builds when the feature is complete.
+draft: true
 sidebar_label: HFlush and HSync
 ---
 

docs/07-system-internals/07-features/05-ratis-streaming.md

@@ -1,6 +1,6 @@
 ---
-# Page is accessible by direct link only in production site builds. It can be included in the sidebar when the feature is complete.
-unlisted: true
+# Page is available only in the development server. It can be included in production builds when the feature is complete.
+draft: true
 sidebar_label: Ratis Streaming
 ---
 

docusaurus.config.js

@@ -1,6 +1,8 @@
 // @ts-check
 // Note: type annotations allow type checking and IDEs autocompletion
 
+import Ajv from 'ajv';
+
 const {themes} = require('prism-react-renderer');
 const lightCodeTheme = themes.github;
 const darkCodeTheme = themes.dracula;
@@ -34,6 +36,31 @@ const config = {
     locales: ['en'],
   },
 
+  markdown: {
+    // Validate markdown frontmatter against a more restrictive schema than what Docusaurus allows.
+    // This ensures all pages are using a minimal set of consistent keys.
+    // It can also be used to require all pages to define certain markdown front matter keys.
+    parseFrontMatter: async (params) => {
+      // Reuse the default parser.
+      const result = await params.defaultParseFrontMatter(params);
+
+      // Validate front matter against the schema.
+      const schemaPath = './.github/resource/frontmatter.schema.json';
+      const frontMatterSchema = require(schemaPath);
+      const ajv = new Ajv();
+      const validate = ajv.compile(frontMatterSchema);
+      const isValid = validate(result.frontMatter);
+
+      if (!isValid) {
+        console.error('Front matter validation error in', params.filePath + ':\n', validate.errors);
+        console.error('Front matter validation failed against JSON schema', schemaPath);
+        process.exit(1);
+      }
+
+      return result;
+    },
+  },
+
   presets: [
     [
       'classic',

package.json

@@ -21,7 +21,8 @@
     "clsx": "^2.1.0",
     "prism-react-renderer": "^2.3.1",
     "react": "^18.2.0",
-    "react-dom": "^18.2.0"
+    "react-dom": "^18.2.0",
+    "ajv": "^8.12.0"
   },
   "devDependencies": {
     "@docusaurus/module-type-aliases": "3.1.1",
@@ -30,6 +31,7 @@
     "@cspell/dict-java": "^5.0.6",
     "@cspell/dict-markdown": "^2.0.1",
     "@cspell/dict-shell": "^1.0.6",
+    "ajv-cli": "^5.0.0",
     "markdownlint-cli": "^0.39.0"
   },
   "browserslist": {