Merge branch 'main' into ryans_patch

Author: gingerwizard

.gitignore

@@ -29,6 +29,7 @@ yarn.lock
 yarn.error-log
 .comments
 yarn-error.log
+frontmatter-validation-errors.log
 
 # Output files used by scripts to verify links
 sidebar_links.txt
@@ -57,5 +58,8 @@ docs/whats-new/changelog/index.md
 **.translate
 ClickHouse/
 
-# Ignore generated table of contents files
+
+# 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

clickhouseapi.js

@@ -40,8 +40,10 @@ function groupEndpointsByPrefix(spec) {
 }
 
 function generateDocusaurusMarkdown(spec, groupedEndpoints, prefix) {
-  let markdownContent = `---\nsidebar_label: ${prefix.charAt(0).toUpperCase() + prefix.slice(1)}\n`;
-  markdownContent += `title: ${prefix.charAt(0).toUpperCase() + prefix.slice(1)}\n---\n`;
+  let markdownContent = `---\nsidebar_label: '${prefix.charAt(0).toUpperCase() + prefix.slice(1)}'\n`;
+  markdownContent += `title: '${prefix.charAt(0).toUpperCase() + prefix.slice(1)}'\n`;
+  markdownContent += `slug: /cloud/manage/api/${prefix}-api-reference\n`;
+  markdownContent += `description: 'Cloud API reference documentation for ${prefix}'\n---\n`;
 
   for (const path in groupedEndpoints) {
     for (const method in groupedEndpoints[path]) {

contribute/contrib-writing-guide.md

@@ -265,6 +265,7 @@ slug: /integrations/sql-clients/clickhouse-client-local
 sidebar_label: clickhouse-client
 title: clickhouse-client and clickhouse-local
 ---
+
 import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
 

contribute/style-guide.md

@@ -1,21 +1,37 @@
 # 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
 
@@ -91,6 +107,38 @@ Code blocks:
 - Have a title (optional) such as 'Query' or 'Response'
 - Use language `response` if it is for the result of a query.
 
+### Highlighting
+
+You can highlight lines in a code block using the following keywords:
+
+- `highlight-next-line` 
+- `highlight-start`
+- `highlight-end`
+
+These keywords should be added as comments in the codeblock with the appropriate
+escape symbol for the codeblock language. 
+
+For example, if the codeblock is SQL:
+
+```text
+SELECT UserID, count(UserID) AS Count
+-- highlight-next-line
+FROM mv_hits_URL_UserID
+WHERE URL = 'http://public_search'
+GROUP BY UserID
+ORDER BY Count DESC
+LIMIT 10;
+```
+
+If the codeblock is a response: 
+
+```text
+10 rows in set. Elapsed: 0.026 sec.
+# highlight-next-line
+Processed 335.87 thousand rows,
+13.54 MB (12.91 million rows/s., 520.38 MB/s.)
+```
+
 ### Associated markdown rule or CI check
 
 - [`MD040` enforces that codeblocks have a language specified](/scripts/.markdownlint-cli2.yaml)
@@ -158,4 +206,37 @@ export function Anchor(props) {
 ```
 - Replace `<span id="some-id"></span>` with `Anchor id="some-id"/>`
 
+### Floating 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.
+
+When adding a new page from the ClickHouse/ClickHouse repo this check will fail
+unless the file is in a folder which [`sidebars.js`](https://github.com/ClickHouse/clickhouse-docs/blob/main/sidebars.js)
+uses with `type: autogenerated` to generate the navigation items from the markdown
+files in the folder.
+
+If you've added a new page on ClickHouse/ClickHouse and this check is failing.
+
+For example:
+
+```text
+✅ All markdown files passed frontmatter validation.
+Loaded 3 exceptions from /opt/clickhouse-docs/plugins/floating-pages-exceptions.txt
+Skipping excepted page: index
+Skipping excepted page: integrations/language-clients/java/client-v1
+Skipping excepted page: integrations/language-clients/java/jdbc-v1
+�[31m1 floating pages found:�[0m
+  - /opt/clickhouse-docs/docs/operations/query-condition-cache.md
+```
+
+You will need to open a PR on docs repo to add this page to [`floating-pages-exceptions.txt`](https://github.com/ClickHouse/clickhouse-docs/blob/main/plugins/floating-pages-exceptions.txt). Once it is merged
+you can then rerun the docs check on the ClickHouse/ClickHouse repo which 
+should pass. Finally open another PR on the docs repo again to remove the 
+file from the exception list and add it to `sidebars.js` in the appropriate
+sidebar.
 

docs/_placeholders/changelog/_index.md

@@ -1,8 +1,9 @@
 ---
+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'
 ---
 

docs/_snippets/_GCS_authentication_and_bucket.md

@@ -6,46 +6,47 @@ import GCS_create_service_account_a from '@site/static/images/integrations/data-
 import GCS_create_service_account_2 from '@site/static/images/integrations/data-ingestion/s3/GCS-create-service-account-2.png';
 import GCS_create_service_account_3 from '@site/static/images/integrations/data-ingestion/s3/GCS-create-service-account-3.png';
 import GCS_guide_key from '@site/static/images/integrations/data-ingestion/s3/GCS-guide-key.png';
+import Image from '@theme/IdealImage';
 
 <details>
     <summary>Create GCS buckets and an HMAC key</summary>
 
 ### ch_bucket_us_east1 {#ch_bucket_us_east1}
 
-<img src={GCS_bucket_1} alt="Creating a GCS bucket in US East 1" />
+<Image size="md" img={GCS_bucket_1} alt="Creating a GCS bucket in US East 1" border />
 
 ### ch_bucket_us_east4 {#ch_bucket_us_east4}
 
-<img src={GCS_bucket_2} alt="Creating a GCS bucket in US East 4" />
+<Image size="md" img={GCS_bucket_2} alt="Creating a GCS bucket in US East 4" border />
 
 ### Generate an Access key {#generate-an-access-key}
 
 ### Create a service account HMAC key and secret {#create-a-service-account-hmac-key-and-secret}
 
 Open **Cloud Storage > Settings > Interoperability** and either choose an existing **Access key**, or **CREATE A KEY FOR A SERVICE ACCOUNT**.  This guide covers the path for creating a new key for a new service account.
 
-<img src={GCS_create_service_account_key} alt="Generating a service account HMAC key in GCS" />
+<Image size="md" img={GCS_create_service_account_key} alt="Generating a service account HMAC key in GCS" border />
 
 ### Add a new service account {#add-a-new-service-account}
 
 If this is a project with no existing service account, **CREATE NEW ACCOUNT**.
 
-<img src={GCS_create_service_account_0} alt="Adding a new service account in GCS" />
+<Image size="md" img={GCS_create_service_account_0} alt="Adding a new service account in GCS" border />
 
 There are three steps to creating the service account, in the first step give the account a meaningful name, ID, and description.
 
-<img src={GCS_create_service_account_a} alt="Defining a new service account name and ID in GCS" />
+<Image size="md" img={GCS_create_service_account_a} alt="Defining a new service account name and ID in GCS" border />
 
 In the Interoperability settings dialog the IAM role **Storage Object Admin** role is recommended; select that role in step two.
 
-<img src={GCS_create_service_account_2} alt="Selecting IAM role Storage Object Admin in GCS" />
+<Image size="md" img={GCS_create_service_account_2} alt="Selecting IAM role Storage Object Admin in GCS" border />
 
 Step three is optional and not used in this guide.  You may allow users to have these privileges based on your policies.
 
-<img src={GCS_create_service_account_3} alt="Configuring additional settings for the new service account in GCS" />
+<Image size="md" img={GCS_create_service_account_3} alt="Configuring additional settings for the new service account in GCS" border />
 
 The service account HMAC key will be displayed.  Save this information, as it will be used in the ClickHouse configuration.
 
-<img src={GCS_guide_key} alt="Retrieving the generated HMAC key for GCS" />
+<Image size="md" img={GCS_guide_key} alt="Retrieving the generated HMAC key for GCS" border />
 
 </details>

docs/_snippets/_S3_authentication_and_bucket.md

@@ -1,3 +1,4 @@
+import Image from '@theme/IdealImage';
 import s3_1 from '@site/static/images/_snippets/s3/s3-1.png';
 import s3_2 from '@site/static/images/_snippets/s3/s3-2.png';
 import s3_3 from '@site/static/images/_snippets/s3/s3-3.png';
@@ -27,85 +28,85 @@ In this procedure, we'll be creating a service account user, not a login user.
 
 2. In "users", select **Add users**
 
-<img src={s3_1} alt="create_iam_user_0"/>
+<Image size="md" img={s3_1} alt="AWS IAM Management Console - Adding a new user" border force/>
 
 3. Enter the user name and set the credential type to **Access key - Programmatic access** and select **Next: Permissions**
 
-<img src={s3_2} alt="create_iam_user_1"/>
+<Image size="md" img={s3_2} alt="Setting user name and access type for IAM user" border force/>
 
 4. Do not add the user to any group; select **Next: Tags**
 
-<img src={s3_3} alt="create_iam_user_2"/>
+<Image size="md" img={s3_3} alt="Skipping group assignment for IAM user" border force/>
 
 5. Unless you need to add any tags, select **Next: Review**
 
-<img src={s3_4} alt="create_iam_user_3"/>
+<Image size="md" img={s3_4} alt="Skipping tag assignment for IAM user" border force/>
 
 6. Select **Create User**
 
     :::note
     The warning message stating that the user has no permissions can be ignored; permissions will be granted on the bucket for the user in the next section
     :::
 
-<img src={s3_5} alt="create_iam_user_4"/>
+<Image size="md" img={s3_5} alt="Creating the IAM user with no permissions warning" border force/>
 
 7. The user is now created; click on **show** and copy the access and secret keys.
 :::note
 Save the keys somewhere else; this is the only time that the secret access key will be available.
 :::
 
-<img src={s3_6} alt="create_iam_user_5"/>
+<Image size="md" img={s3_6} alt="Viewing and copying the IAM user access keys" border force/>
 
 8. Click close, then find the user in the users screen.
 
-<img src={s3_7} alt="create_iam_user_6"/>
+<Image size="md" img={s3_7} alt="Finding the newly created IAM user in the users list" border force/>
 
 9. Copy the ARN (Amazon Resource Name) and save it for use when configuring the access policy for the bucket.
 
-<img src={s3_8} alt="create_iam_user_7"/>
+<Image size="md" img={s3_8} alt="Copying the ARN of the IAM user" border force/>
 
 ### Create an S3 bucket {#create-an-s3-bucket}
 1. In the S3 bucket section, select **Create bucket**
 
-<img src={s3_9} alt="create_s3_bucket_0"/>
+<Image size="md" img={s3_9} alt="Starting the S3 bucket creation process" border force/>
 
 2. Enter a bucket name, leave other options default
 :::note
 The bucket name must be unique across AWS, not just the organization, or it will emit an error.
 :::
 3. Leave `Block all Public Access` enabled; public access is not needed.
 
-<img src={s3_a} alt="create_s3_bucket_2"/>
+<Image size="md" img={s3_a} alt="Configuring the S3 bucket settings with public access blocked" border force/>
 
 4. Select **Create Bucket** at the bottom of the page
 
-<img src={s3_b} alt="create_s3_bucket_3"/>
+<Image size="md" img={s3_b} alt="Finalizing S3 bucket creation" border force/>
 
 5. Select the link, copy the ARN, and save it for use when configuring the access policy for the bucket.
 
 6. Once the bucket has been created, find the new S3 bucket in the S3 buckets list and select the link
 
-<img src={s3_c} alt="create_s3_bucket_4"/>
+<Image size="md" img={s3_c} alt="Finding the newly created S3 bucket in the buckets list" border force/>
 
 7. Select **Create folder**
 
-<img src={s3_d} alt="create_s3_bucket_5"/>
+<Image size="md" img={s3_d} alt="Creating a new folder in the S3 bucket" border force/>
 
 8. Enter a folder name that will be the target for the ClickHouse S3 disk and select **Create folder**
 
-<img src={s3_e} alt="create_s3_bucket_6"/>
+<Image size="md" img={s3_e} alt="Setting the folder name for ClickHouse S3 disk usage" border force/>
 
 9. The folder should now be visible on the bucket list
 
-<img src={s3_f} alt="create_s3_bucket_7"/>
+<Image size="md" img={s3_f} alt="Viewing the newly created folder in the S3 bucket" border force/>
 
 10. Select the checkbox for the new folder and click on **Copy URL** Save the URL copied to be used in the ClickHouse storage configuration in the next section.
 
-<img src={s3_g} alt="create_s3_bucket_8"/>
+<Image size="md" img={s3_g} alt="Copying the S3 folder URL for ClickHouse configuration" border force/>
 
 11. Select the **Permissions** tab and click on the **Edit** button in the **Bucket Policy** section
 
-<img src={s3_h} alt="create_s3_bucket_9"/>
+<Image size="md" img={s3_h} alt="Accessing the S3 bucket policy configuration" border force/>
 
 12. Add a bucket policy, example below:
 ```json

docs/_snippets/_add_remote_ip_access_list_detail.md

@@ -1,3 +1,4 @@
+import Image from '@theme/IdealImage';
 import ip_allow_list_check_list from '@site/static/images/_snippets/ip-allow-list-check-list.png';
 import ip_allow_list_add_current_ip from '@site/static/images/_snippets/ip-allow-list-add-current-ip.png';
 
@@ -6,10 +7,10 @@ import ip_allow_list_add_current_ip from '@site/static/images/_snippets/ip-allow
 
 From your ClickHouse Cloud services list choose the service that you will work with and switch to **Settings**.  If the IP Access List does not contain the IP Address or range of the remote system that needs to connect to your ClickHouse Cloud service, then you can resolve the problem with **Add IPs**:
 
-<img src={ip_allow_list_check_list} class="image" alt="Check to see if the service allows traffic" />
+<Image size="md" img={ip_allow_list_check_list} alt="Check to see if the service allows traffic from your IP address in the IP Access List" border />
 
 Add the individual IP Address, or the range of addresses that need to connect to your ClickHouse Cloud service. Modify the form as you see fit and then **Save**.
 
-<img src={ip_allow_list_add_current_ip} class="image" alt="Add your current IP address" />
+<Image size="md" img={ip_allow_list_add_current_ip} alt="Add your current IP address to the IP Access List in ClickHouse Cloud" border />
 
 </details>