Merge branch 'main' of https://github.com/ClickHouse/clickhouse-docs into Blargian-patch-940827

Author: Blargian

.github/workflows/badges-notify.yml

@@ -13,7 +13,7 @@ jobs:
 
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
 
       - name: Make script executable
         run: chmod +x scripts/badger.sh

.github/workflows/build-search.yml

@@ -20,10 +20,10 @@ jobs:
 
     steps:
       - name: Checkout Repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
 
       - name: Set up Node.js
-        uses: actions/setup-node@v4
+        uses: actions/setup-node@v6
         with:
           node-version: '20' 
 

.github/workflows/check-build.yml

@@ -19,7 +19,7 @@ jobs:
         check_type: [spellcheck, kbcheck, md-lint, glossary-check]
     steps:
       # Add setup steps per check here
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
       - name: Install Aspell
         if: matrix.check_type == 'spellcheck'
         run: sudo apt-get update && sudo apt-get install -y aspell aspell-en
@@ -31,7 +31,7 @@ jobs:
           uv python install 3.12 --verbose
       - name: Setup md-lint environment
         if: matrix.check_type == 'md-lint'
-        uses: actions/setup-node@v3
+        uses: actions/setup-node@v6
         with:
           node-version: 20
       - name: Install markdownlint-cli2

.github/workflows/pull-request.yaml

@@ -21,10 +21,10 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v3
+        uses: actions/checkout@v5
 
       - name: Set up Node.js
-        uses: actions/setup-node@v3
+        uses: actions/setup-node@v6
         with:
           node-version: '20'  # Adjust Node.js version as needed
           cache: 'yarn'       # Cache yarn dependencies

.github/workflows/trademark-cla-approval.yml

@@ -170,7 +170,7 @@ jobs:
 
       - name: Check out repository
         if: success() && steps.process-comment.outputs.pr_number != ''
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
         with:
           fetch-depth: 0
           # For forked PRs, we need to fetch from the fork and checkout the SHA

.github/workflows/trademark-cla-notice.yml

@@ -25,7 +25,7 @@ jobs:
           private-key: "${{ secrets.WORKFLOW_AUTH_PUBLIC_PRIVATE_KEY }}"
 
       - name: Check out code
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
         with:
           fetch-depth: 0
           # Use the GitHub App token if available, otherwise fallback to GITHUB_TOKEN

.github/workflows/vale-linter.yml

@@ -20,7 +20,7 @@ jobs:
     timeout-minutes: 10
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v3
+        uses: actions/checkout@v5
         with:
           fetch-depth: 0
           path: .

contribute/style-guide.md

@@ -331,7 +331,53 @@ which may need versioned documentation, we use the following custom
 <ClientVersionDropdown versions={}/>
 ```
 
-### How to use it 
+### How to use it
+
+The `ClientVersionDropdown` component supports two APIs:
+
+#### API 1: Inline Content (Recommended)
+
+This approach keeps all content in the main file, which allows Docusaurus to properly generate the table of contents (TOC) for all versions.
+
+```js
+import ClientVersionDropdown from '@theme/ClientVersionDropdown/ClientVersionDropdown'
+import Version from '@theme/ClientVersionDropdown/Version'
+
+<ClientVersionDropdown versions={[
+    {
+        'version': 'v0.8+'
+    },
+    {
+        'version': 'v0.7.x'
+    }
+]}>
+
+<Version>
+## Environment requirements
+
+Your v0.8+ content here...
+</Version>
+
+<Version>
+## Environment requirements {#v07-environment-requirements}
+
+Your v0.7.x content here...
+</Version>
+
+</ClientVersionDropdown>
+```
+
+**Important Notes:**
+- All content is placed directly in the main `.mdx` file
+- Each `<Version>` block contains the content for one version
+- The order of `<Version>` blocks must match the order in the `versions` array
+- **Make header IDs unique** across versions using explicit anchor IDs (e.g., `{#v07-environment-requirements}`)
+- The TOC will show only headers from the currently selected version
+- The component will display the first version as 'selected' by default
+
+#### API 2: External Snippets (Legacy)
+
+This approach uses separate snippet files for each version. Note that this method has limitations with TOC generation.
 
 Versioned folders are structured as follows:
 
@@ -352,9 +398,9 @@ Versioned folders are structured as follows:
 ```
 
 * The content for each version is placed in a snippet. For example `_v0_7.mdx`
-  * Snippets begin with `_` 
+  * Snippets begin with `_`
   * Snippets do not contain front-matter
-  * These snippets import any components they may need (See `_v0_7.mdx` for example)
+  * These snippets import any components they may need
   * They should be .mdx files
 * There is a single page for all versions. For example `client.mdx`
   * This page contains frontmatter
@@ -370,8 +416,8 @@ import ClientVersionDropdown from '@theme/ClientVersionDropdown/ClientVersionDro
 Also import the two snippets:
 
 ```js
-import v07 from './_v0_7.mdx'
-import v08 from './_v0_8.mdx'
+import v07 from './_snippets/_v0_7.mdx'
+import v08 from './_snippets/_v0_8.mdx'
 ```
 
 Pass it an array of objects representing versions and their respective snippets: