update style guide

Author: Blargian

contribute/style-guide.md

@@ -10,14 +10,29 @@ 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/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

@@ -6,6 +6,8 @@ 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) {
   return items.filter(({ type, id }) => {
@@ -328,6 +330,7 @@ const config = {
         checkFloatingPages,
         {
           failBuild: true,
+          exceptionsFile: path.resolve(__dirname, 'plugins/floating-pages-exceptions.txt')
         },
     ]
   ],

docs/whats-new/changelog/index.md

@@ -4,14 +4,39 @@ const { promisify } = require('util');
 const glob = promisify(require('glob'));
 const matter = require('gray-matter');
 
-async function checkFloatingPages(context, options) {
+async function checkFloatingPages(context, options = {}) {
     return {
         name: 'check-floating-pages',
 
         async postBuild({ siteConfig, routesPaths, outDir, head }) {
             const { baseUrl } = siteConfig;
             const docsDir = path.resolve(context.siteDir, 'docs');
 
+            // Read exceptions file if provided
+            let exceptions = [];
+            if (options.exceptionsFile && fs.existsSync(options.exceptionsFile)) {
+                try {
+                    const fileContent = fs.readFileSync(options.exceptionsFile, 'utf-8');
+                    exceptions = fileContent
+                        .split('\n')
+                        .map(line => line.trim())
+                        .filter(line => line && !line.startsWith('#')); // Skip empty lines and comments
+
+                    // Normalize exceptions paths
+                    exceptions = exceptions.map(exception => {
+                        // Remove leading /docs/ if present
+                        let normalized = exception.replace(/^\/docs\//, '');
+                        // Remove .md extension if present
+                        normalized = normalized.replace(/\.md$/, '');
+                        return normalized;
+                    });
+
+                    console.log(`Loaded ${exceptions.length} exceptions from ${options.exceptionsFile}`);
+                } catch (err) {
+                    console.error("Error reading exceptions file:", err);
+                }
+            }
+
             let sidebarItems = [];
             let autogeneratedDirs = [];
             const sidebarsPath = path.join(context.siteDir, 'sidebars.js');
@@ -47,6 +72,16 @@ async function checkFloatingPages(context, options) {
 
                 const idToCheck = data.id || relativePath;
 
+                // Skip if the page is in the exceptions list
+                if (exceptions.includes(idToCheck) ||
+                    exceptions.includes(relativePath) ||
+                    exceptions.includes(relativePath + '.md') ||
+                    exceptions.includes('/docs/' + relativePath) ||
+                    exceptions.includes('/docs/' + relativePath + '.md')) {
+                    console.log(`Skipping excepted page: ${relativePath}`);
+                    continue;
+                }
+
                 // Check various ways this document could be included in the sidebar
                 if (isDocumentIncluded(idToCheck, relativePath, sidebarItems, autogeneratedDirs)) {
                     continue;

docusaurus.config.en.js

@@ -0,0 +1,14 @@
+# List of pages to exclude from floating pages check
+# One path per line. Lines starting with # are comments
+# Paths can be in any of these formats:
+# - Relative to docs directory: integrations/language-clients/java/client-v1
+# - With .md extension: integrations/language-clients/java/client-v1.md
+# - With /docs/ prefix: /docs/integrations/language-clients/java/client-v1
+# - With /docs/ prefix and .md extension: /docs/integrations/language-clients/java/client-v1.md
+
+# Root index page
+/docs/index.md
+
+# Java client documentation
+integrations/language-clients/java/client-v1
+integrations/language-clients/java/jdbc-v1

plugins/checkFloatingPages.js

@@ -33,5 +33,6 @@ python3 scripts/table-of-contents-generator/toc_gen.py --single-toc --dir="docs/
 python3 scripts/table-of-contents-generator/toc_gen.py --single-toc --dir="docs/chdb/guides" --md="docs/chdb/guides/index.md" --ignore images
 python3 scripts/table-of-contents-generator/toc_gen.py --single-toc --dir="docs/cloud/manage/jan2025_faq" --md="docs/cloud/manage/jan2025_faq/index.md" --ignore images
 python3 scripts/table-of-contents-generator/toc_gen.py --single-toc --dir="docs/cloud/changelogs" --md="docs/cloud/reference/release-notes-index.md"
+python3 scripts/table-of-contents-generator/toc_gen.py --single-toc --dir="docs/cloud/manage/api" --md="docs/cloud/manage/api/api-reference-index.md"
 deactivate
 rm -r venv