Merge pull request #3518 from Blargian/page_for_luzmo

Docs checks: find floating pages

Author: gingerwizard

.gitignore

@@ -62,3 +62,4 @@ ClickHouse/
 # Ignore table of contents files
 docs/cloud/reference/release-notes-index.md
 docs/whats-new/changelog/index.md
+docs/cloud/manage/api/api-reference-index.md

contribute/style-guide.md

@@ -1,23 +1,38 @@
 # ClickHouse docs style guide
 
-In this document, you will find a number of style guidelines for writing documentation.
-The rules in this guide are intended to assist in helping us to create a high
-quality documentation offering on par with the quality of ClickHouse itself.
+In this document, you will find a number of style guidelines for writing ClickHouse
+documentation. As documentation is a collective effort, these guidelines are 
+intended to help all of us ensure quality and consistency across our documentation.
 
 ## YAML front matter
 
-Begin every new markdown document with YAML front-matter:
+Begin every new Markdown document with YAML front-matter:
 
 ```markdown
 ---
-title: Using a clickhouse-local database
-sidebar_label: Using clickhouse-local database
+title: 'Using a clickhouse-local database'
+sidebar_label: 'Using clickhouse-local database'
 slug: /chdb/guides/clickhouse-local
-description: Learn how to use a clickhouse-local database with chDB
-keywords: [chdb, clickhouse-local]
+description: 'Learn how to use a clickhouse-local database with chDB'
+keywords: ['chdb', 'clickhouse-local']
 ---
 ```
 
+### Associated markdown rule or CI check
+
+#### front-matter validation 
+
+There is a custom Docusaurus plugin which runs on build that makes the following
+checks on front-matter:
+
+- title, description and slug are specified.
+- keywords use flow style arrays with single quoted items e.g. 
+  `keywords: ['integrations']`
+- single quotes are used for title, description, slug, sidebar_label
+- there is an empty line after the YAML frontmatter block
+
+For implementation details see [plugins/frontmatter-validation](https://github.com/ClickHouse/clickhouse-docs/tree/main/plugins/frontmatter-validation)
+
 ## Explicit header tags
 
 Due to the way our translation system works, it is necessary to add an explicit
@@ -191,4 +206,12 @@ export function Anchor(props) {
 ```
 - Replace `<span id="some-id"></span>` with `Anchor id="some-id"/>`
 
+### Dangling pages
+
+In order to prevent pages from becoming 'floating' or 'orphaned' it is
+necessary that you add a newly created page to `sidebars.js`. We have a [custom
+docusaurus plugin](plugins/checkFloatingPages.js) to catch dangling pages.
+
+If there is some specific reason that you need to bypass this check, you can
+add an exception to `floating-pages-exceptions.txt` in the plugins directory.
 

docs/cloud/manage/api/api-reference-index.md

@@ -4,11 +4,7 @@ slug: /cloud/manage/api/
 description: 'Landing page for Cloud API'
 ---
 
-| Page                                                           | Description                      |
-|----------------------------------------------------------------|----------------------------------|
-| [Invitations](/cloud/manage/api/invitations-api-reference)     | API reference for invitations.   |
-| [Keys](/cloud/manage/api/keys-api-reference)                   | API reference for keys.          |
-| [Members](/cloud/manage/api/members-api-reference)             | API reference for requests.      |
-| [Organizations](/cloud/manage/api/organizations-api-reference) | API reference for organizations. |
-| [Services](/cloud/manage/api/services-api-reference)           | API reference for services.      |
-| [Usage cost](/cloud/manage/api/usageCost-api-reference)        | API reference for services.      |
+<!-- The table on this page is autogenerated by the script at https://github.com/ClickHouse/clickhouse-docs/blob/main/scripts/autogenerate-table-of-contents.sh
+if you've spotted an error or want to change something, please edit the YAML
+frontmatter of the files themselves.
+-->

docs/cloud/manage/api/index.md

@@ -10,4 +10,4 @@ This section contains reference documentation for Cloud API and contains the fol
 |---------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------|
 | [Overview](/cloud/manage/api/api-overview)|  Provides an overview of rate limits, Terraform Provider, Swagger (OpenAPI) Endpoint and UI and available support.                   | 
 | [Managing API Keys](/cloud/manage/openapi)                          | Learn more about Cloud's API utilizing OpenAPI that allows you to programmatically manage your account and aspects of your services. |
-| [API Reference](/cloud/manage/api)                              | API reference documentation.                                                                                                         |
+| [API Reference](/cloud/manage/api)                              | API reference documentation.                                                                                                         |

docs/cloud/reference/changelog.md

@@ -27,7 +27,6 @@ import fast_releases from '@site/static/images/cloud/reference/june-13-fast-rele
 import share_queries from '@site/static/images/cloud/reference/may-30-share-queries.png';
 import query_endpoints from '@site/static/images/cloud/reference/may-17-query-endpoints.png';
 
-
 In addition to this ClickHouse Cloud changelog, please see the [Cloud Compatibility](/cloud/reference/cloud-compatibility.md) page.
 ## March 7, 2025 {#march-7-2025}
 
@@ -305,7 +304,7 @@ Services are available in GCP `us-central-1` to customers with the **Dedicated**
 
 We recently announced the Private Preview for Compute-Compute Separation for AWS. We're happy to announce that it is now available for GCP and Azure.
 
-Compute-compute separation allows you to designate specific services as read-write or read-only services, allowing you to design the optimal compute configuration for your application to optimize cost and performance. Please [read the docs](/cloud/reference/compute-compute-separation) for more details.
+Compute-compute separation allows you to designate specific services as read-write or read-only services, allowing you to design the optimal compute configuration for your application to optimize cost and performance. Please [read the docs](/cloud/reference/warehouses) for more details.
 
 ### Self-service MFA recovery codes {#self-service-mfa-recovery-codes}
 
@@ -357,7 +356,7 @@ Please also check out our [Trust Center](https://trust.clickhouse.com/) for secu
 
 For existing ClickHouse Cloud services, replicas handle both reads and writes, and there is no way to configure a certain replica to handle only one kind of operation. We have an upcoming new feature called Compute-compute separation that allows you to designate specific services as read-write or read-only services, allowing you to design the optimal compute configuration for your application to optimize cost and performance.
 
-Our new compute-compute separation feature enables you to create multiple compute node groups, each with its own endpoint, that are using the same object storage folder, and thus, with the same tables, views, etc. Read more about [Compute-compute separation here](/cloud/reference/compute-compute-separation). Please [contact support](https://clickhouse.com/support/program) if you would like access to this feature in Private Preview.
+Our new compute-compute separation feature enables you to create multiple compute node groups, each with its own endpoint, that are using the same object storage folder, and thus, with the same tables, views, etc. Read more about [Compute-compute separation here](/cloud/reference/warehouses). Please [contact support](https://clickhouse.com/support/program) if you would like access to this feature in Private Preview.
 
 <img alt="Example architecture for compute-compute separation"
   style={{width: '600px'}}

docs/cloud/reference/compute-compute-separation.md

@@ -14,7 +14,7 @@ This section acts as a reference guide for some of the more technical details of
 |-----------------------------------|-----------------------------------------------------------------------------------------------------------|
 | [Architecture](/cloud/reference/architecture)               | Discusses the architecture of ClickHouse Cloud, including storage, compute, administration, and security. |
 | [SharedMergeTree](/cloud/reference/shared-merge-tree)            |  Explainer on SharedMergeTree, the cloud-native replacement for the ReplicatedMergeTree and analogues.    |
-| [Warehouses](/cloud/reference/compute-compute-separation)                 | Explainer on what Warehouses and Compute-Compute separation are in ClickHouse Cloud.                      |
+| [Warehouses](/cloud/reference/warehouses)                 | Explainer on what Warehouses and Compute-Compute separation are in ClickHouse Cloud.                      |
 | [BYOC (Bring Your Own Cloud)](/cloud/reference/byoc)| Explainer on the Bring Your Own Cloud (BYOC) service available with ClickHouse Cloud.                     |
 | [Changelogs](/cloud/reference/changelogs)                 | Cloud Changelogs and Release Notes.                                                                       |
 | [Cloud Compatibility](/whats-new/cloud-compatibility)        | A guide to what to expect functionally and operationally in ClickHouse Cloud.                             |

docs/cloud/reference/index.md

@@ -1,9 +1,10 @@
 ---
+description: 'Changelog for 2025'
+note: 'This file is autogenerated by the yarn new-build'
 slug: /whats-new/changelog/
 sidebar_position: 2
-sidebar_label:  2025
-title: 2025 Changelog
-note: This file is autogenerated by the yarn new-build
+sidebar_label: '2025'
+title: '2025 Changelog'
 ---
 
 ### Table of Contents

docs/interfaces/native-clients-and-interfaces-index.md

@@ -4,6 +4,9 @@ import katex from "rehype-katex";
 import chHeader from "./plugins/header.js";
 import fixLinks from "./src/hooks/fixLinks.js";
 const { customParseFrontMatter } = require('./plugins/frontmatter-validation/customParseFrontMatter');
+const checkFloatingPages = require('./plugins/checkFloatingPages');
+const frontmatterValidator = require('./plugins/frontmatter-validation/frontmatterValidatorPlugin');
+const path = require('path');
 
 // Helper function to skip over index.md files.
 function skipIndex(items) {
@@ -317,13 +320,26 @@ const config = {
       },
     ],
     chHeader,
-    './plugins/frontmatter-validation/frontmatterValidatorPlugin'
+    [
+      frontmatterValidator,
+      {
+        failBuild: true,
+      },
+    ],
+    [
+        checkFloatingPages,
+        {
+          failBuild: true,
+          exceptionsFile: path.resolve(__dirname, 'plugins/floating-pages-exceptions.txt')
+        },
+    ]
   ],
   customFields: {
     blogSidebarLink: "/docs/knowledgebase", // Used for KB article page
     galaxyApiEndpoint:
       process.env.NEXT_PUBLIC_GALAXY_API_ENDPOINT || "http://localhost:3000",
   },
+
 };
 
 module.exports = config;