merge main

Author: Blargian

README.md

@@ -132,6 +132,10 @@ Please assign any pull request (PR) against an issue; this helps the docs team t
 
 Check out the GitHub docs for a refresher on [how to create a pull request](https://docs.github.com/en/desktop/working-with-your-remote-repository-on-github-or-github-enterprise/creating-an-issue-or-pull-request-from-github-desktop).
 
+### Style guidelines
+
+For style guidelines, see ["Style guide"](/contribute/style-guide.md).
+
 ### Tests and CI/CD {#tests-and-cicd}
 
 There are five workflows that run against PRs in this repo:

contribute/style-guide.md

@@ -0,0 +1,125 @@
+# 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.
+
+## 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
+slug: /chdb/guides/clickhouse-local
+description: Learn how to use a clickhouse-local database with chDB
+keywords: [chdb, clickhouse-local]
+---
+```
+
+## Explicit header tags
+
+Due to the way our translation system works, it is necessary to add an explicit
+anchor tag next to every header, such as `{#explicit-anchor-tag}`.
+
+For example:
+
+```markdown
+## My header {#my-header}
+```
+
+### Associated markdown rule or CI check
+- [`custom-anchor-headings`](/scripts/.markdownlint-cli2.yaml)
+
+## Images
+
+In all cases images get added to the `static/images` directory of the repository.
+Under the images directory you should place the images according to the folder
+structure of the docs.
+
+For example, if you wanted to add images to `clickhouse-local.md` which is 
+located at `/docs/chdb/guides/clickhouse-local.md`. You should add the 
+images at `/static/images/chdb/guides/`.
+
+Try to use descriptive names in lower case. For example:
+- `clickhouse-local-1.png`
+- `clickhouse-local-2.png`
+- `clickhouse-local-3.png` etc.
+
+In the markdown document import the images under the YAML frontmatter:
+
+```markdown
+---
+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]
+---
+
+import clickhouse-local-1 from '@site/static/images/chdb/guides/clickhouse-local-1.png'
+import clickhouse-local-2 from '@site/static/images/chdb/guides/clickhouse-local-2.png'
+import clickhouse-local-3 from '@site/static/images/chdb/guides/clickhouse-local-3.png'
+```
+
+Use the `<img/>` tag to place your image in the appropriate place:
+
+```markdown
+Here is some example text which refers to the image below:
+
+<img src={clickhouse-local-1}
+    alt='DESCRIPTION OF THE IMAGE'
+    style={{width: '800px'}} // optional
+/>
+
+Here is another paragraph...
+```
+
+## Codeblocks
+
+Codeblocks are defined using backticks. For example:
+
+```text
+\```sql title='Query'
+SELECT * FROM system.contributors;
+\```
+```
+
+Code blocks:
+- Should always have a language defined immediately next to the opening 3
+  backticks, without any space.
+- Have a title (optional) such as 'Query' or 'Response'
+- Use language `response` if it is for the result of a query.
+
+### Associated markdown rule or CI check
+
+- [`MD040` enforces that codeblocks have a language specified](/scripts/.markdownlint-cli2.yaml)
+
+## Broken links
+
+Making a change to a page slug or moving a file can result in broken links in
+numerous places across the docs. To mitigate this we use the built in link checker
+provided by Docusaurus. If broken links are found then docs check will fail with
+an error message something like this:
+
+```text
+Exhaustive list of all broken links found:
+
+- Broken link on source page path = /docs/observability/integrating-opentelemetry:
+   -> linking to /docs/observability/schema-design#using-maps
+- Broken link on source page path = /docs/operations/server-configuration-parameters/settings:
+   -> linking to ../../../engines/table-engines/mergetree-family/mergetree#mergetree-table-ttl (resolved as: /engines/table-engines/mergetree-family/mergetree#mergetree-table-ttl)
+- Broken link on source page path = /docs/partitions:
+   -> linking to /docs/optimize/sparse-primary-indexes#data-is-organized-into-granules-for-parallel-data-processing
+```
+
+To fix the links, find the source page, given after `source page path =` and search within it for the
+link given after `linking to`. As slugs are resolved relative to `/docs` you can exclude this from your
+search. E.g don't search `/docs/observability/schema-design#using-maps` but `/observability/schema-design#using-maps`
+
+**note** if you can't find the link on the page but you're sure that you are looking in the file 
+reported by the failing broken link checker, the link is most likely found in a snippet which is
+imported by that page. Find the snippet location from the import statement at the top of the page.
+
+

docs/_snippets/_GCS_authentication_and_bucket.md

@@ -1,43 +1,52 @@
 
+import GCS_bucket_1 from '@site/static/images/integrations/data-ingestion/s3/GCS-bucket-1.png';
+import GCS_bucket_2 from '@site/static/images/integrations/data-ingestion/s3/GCS-bucket-2.png';
+import GCS_create_service_account_key from '@site/static/images/integrations/data-ingestion/s3/GCS-create-a-service-account-key.png';
+import GCS_create_service_account_0 from '@site/static/images/integrations/data-ingestion/s3/GCS-create-service-account-0.png';
+import GCS_create_service_account_a from '@site/static/images/integrations/data-ingestion/s3/GCS-create-service-account-a.png';
+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';
+
 <details>
     <summary>Create GCS buckets and an HMAC key</summary>
 
 ### ch_bucket_us_east1 {#ch_bucket_us_east1}
 
-![Add a bucket](@site/docs/integrations/data-ingestion/s3/images/GCS-bucket-1.png)
+<img src={GCS_bucket_1} alt="Creating a GCS bucket in US East 1" />
 
 ### ch_bucket_us_east4 {#ch_bucket_us_east4}
 
-![Add a bucket](@site/docs/integrations/data-ingestion/s3/images/GCS-bucket-2.png)
+<img src={GCS_bucket_2} alt="Creating a GCS bucket in US East 4" />
 
 ### 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.
 
-![Add a bucket](@site/docs/integrations/data-ingestion/s3/images/GCS-create-a-service-account-key.png)
+<img src={GCS_create_service_account_key} alt="Generating a service account HMAC key in GCS" />
 
 ### Add a new service account {#add-a-new-service-account}
 
 If this is a project with no existing service account, **CREATE NEW ACCOUNT**.
 
-![Add a bucket](@site/docs/integrations/data-ingestion/s3/images/GCS-create-service-account-0.png)
+<img src={GCS_create_service_account_0} alt="Adding a new service account in GCS" />
 
 There are three steps to creating the service account, in the first step give the account a meaningful name, ID, and description.
 
-![Add a bucket](@site/docs/integrations/data-ingestion/s3/images/GCS-create-service-account-a.png)
+<img src={GCS_create_service_account_a} alt="Defining a new service account name and ID in GCS" />
 
 In the Interoperability settings dialog the IAM role **Storage Object Admin** role is recommended; select that role in step two.
 
-![Add a bucket](@site/docs/integrations/data-ingestion/s3/images/GCS-create-service-account-2.png)
+<img src={GCS_create_service_account_2} alt="Selecting IAM role Storage Object Admin in GCS" />
 
 Step three is optional and not used in this guide.  You may allow users to have these privileges based on your policies.
 
-![Add a bucket](@site/docs/integrations/data-ingestion/s3/images/GCS-create-service-account-3.png)
+<img src={GCS_create_service_account_3} alt="Configuring additional settings for the new service account in GCS" />
 
 The service account HMAC key will be displayed.  Save this information, as it will be used in the ClickHouse configuration.
 
-![Add a bucket](@site/docs/integrations/data-ingestion/s3/images/GCS-guide-key.png)
+<img src={GCS_guide_key} alt="Retrieving the generated HMAC key for GCS" />
 
 </details>

docs/_snippets/_S3_authentication_and_bucket.md

@@ -1,3 +1,20 @@
+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';
+import s3_4 from '@site/static/images/_snippets/s3/s3-4.png';
+import s3_5 from '@site/static/images/_snippets/s3/s3-5.png';
+import s3_6 from '@site/static/images/_snippets/s3/s3-6.png';
+import s3_7 from '@site/static/images/_snippets/s3/s3-7.png';
+import s3_8 from '@site/static/images/_snippets/s3/s3-8.png';
+import s3_9 from '@site/static/images/_snippets/s3/s3-9.png';
+import s3_a from '@site/static/images/_snippets/s3/s3-a.png';
+import s3_b from '@site/static/images/_snippets/s3/s3-b.png';
+import s3_c from '@site/static/images/_snippets/s3/s3-c.png';
+import s3_d from '@site/static/images/_snippets/s3/s3-d.png';
+import s3_e from '@site/static/images/_snippets/s3/s3-e.png';
+import s3_f from '@site/static/images/_snippets/s3/s3-f.png';
+import s3_g from '@site/static/images/_snippets/s3/s3-g.png';
+import s3_h from '@site/static/images/_snippets/s3/s3-h.png';
 
 <details>
   <summary>Create S3 buckets and an IAM user</summary>
@@ -10,85 +27,85 @@ In this procedure, we'll be creating a service account user, not a login user.
 
 2. In "users", select **Add users**
 
-  ![create_iam_user_0](@site/docs/_snippets/images/s3/s3-1.png)
+<img src={s3_1} alt="create_iam_user_0"/>
 
 3. Enter the user name and set the credential type to **Access key - Programmatic access** and select **Next: Permissions**
 
-  ![create_iam_user_1](@site/docs/_snippets/images/s3/s3-2.png)
+<img src={s3_2} alt="create_iam_user_1"/>
 
 4. Do not add the user to any group; select **Next: Tags**
 
-  ![create_iam_user_2](@site/docs/_snippets/images/s3/s3-3.png)
+<img src={s3_3} alt="create_iam_user_2"/>
 
 5. Unless you need to add any tags, select **Next: Review**
 
-  ![create_iam_user_3](@site/docs/_snippets/images/s3/s3-4.png)
+<img src={s3_4} alt="create_iam_user_3"/>
 
 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
     :::
 
-  ![create_iam_user_4](@site/docs/_snippets/images/s3/s3-5.png)
+<img src={s3_5} alt="create_iam_user_4"/>
 
 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.
 :::
 
-  ![create_iam_user_5](@site/docs/_snippets/images/s3/s3-6.png)
+<img src={s3_6} alt="create_iam_user_5"/>
 
 8. Click close, then find the user in the users screen.
 
-  ![create_iam_user_6](@site/docs/_snippets/images/s3/s3-7.png)
+<img src={s3_7} alt="create_iam_user_6"/>
 
 9. Copy the ARN (Amazon Resource Name) and save it for use when configuring the access policy for the bucket.
 
-  ![create_iam_user_7](@site/docs/_snippets/images/s3/s3-8.png)
+<img src={s3_8} alt="create_iam_user_7"/>
 
 ### Create an S3 bucket {#create-an-s3-bucket}
 1. In the S3 bucket section, select **Create bucket**
 
-  ![create_s3_bucket_0](@site/docs/_snippets/images/s3/s3-9.png)
+<img src={s3_9} alt="create_s3_bucket_0"/>
 
 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.
 
-  ![create_s3_bucket_2](@site/docs/_snippets/images/s3/s3-a.png)
+<img src={s3_a} alt="create_s3_bucket_2"/>
 
 4. Select **Create Bucket** at the bottom of the page
 
-  ![create_s3_bucket_3](@site/docs/_snippets/images/s3/s3-b.png)
+<img src={s3_b} alt="create_s3_bucket_3"/>
 
 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
 
-  ![create_s3_bucket_4](@site/docs/_snippets/images/s3/s3-c.png)
+<img src={s3_c} alt="create_s3_bucket_4"/>
 
 7. Select **Create folder**
 
-  ![create_s3_bucket_5](@site/docs/_snippets/images/s3/s3-d.png)
+<img src={s3_d} alt="create_s3_bucket_5"/>
 
 8. Enter a folder name that will be the target for the ClickHouse S3 disk and select **Create folder**
 
-  ![create_s3_bucket_6](@site/docs/_snippets/images/s3/s3-e.png)
+<img src={s3_e} alt="create_s3_bucket_6"/>
 
 9. The folder should now be visible on the bucket list
 
-  ![create_s3_bucket_7](@site/docs/_snippets/images/s3/s3-f.png)
+<img src={s3_f} alt="create_s3_bucket_7"/>
 
 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.
 
-  ![create_s3_bucket_8](@site/docs/_snippets/images/s3/s3-g.png)
+<img src={s3_g} alt="create_s3_bucket_8"/>
 
 11. Select the **Permissions** tab and click on the **Edit** button in the **Bucket Policy** section
 
-  ![create_s3_bucket_9](@site/docs/_snippets/images/s3/s3-h.png)
+<img src={s3_h} alt="create_s3_bucket_9"/>
 
 12. Add a bucket policy, example below:
 ```json

docs/_snippets/_add_remote_ip_access_list_detail.md

@@ -1,13 +1,15 @@
+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';
+
 <details>
     <summary>Manage your IP Access List</summary>
 
 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**:
 
-![Check to see if the service allows traffic](@site/docs/_snippets/images/ip-allow-list-check-list.png)
+<img src={ip_allow_list_check_list} class="image" alt="Check to see if the service allows traffic" />
 
 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**.
 
-![Add your current IP address](@site/docs/_snippets/images/ip-allow-list-add-current-ip.png)
+<img src={ip_allow_list_add_current_ip} class="image" alt="Add your current IP address" />
 
 </details>
-

docs/_snippets/_clickhouse_mysql_cloud_setup.mdx

@@ -1,16 +1,22 @@
+import mysql_1 from '@site/static/images/_snippets/mysql1.png';
+import mysql_2 from '@site/static/images/_snippets/mysql2.png';
+import mysql_3 from '@site/static/images/_snippets/mysql3.png';
+import mysql_4 from '@site/static/images/_snippets/mysql4.png';
+import mysql_5 from '@site/static/images/_snippets/mysql5.png';
+
 <br/>
 1. After creating your ClickHouse Cloud Service, on the `Connect your app` screen, select MySQL from the drop down.
 <br/>
 
 <div class="eighty-percent">
-![Credentials screen - Prompt](./images/mysql1.png)
+    <img src={mysql_1} class="image" alt="Credentials screen - Prompt" />
 </div>
 
-2. Toggle the switch to enable the MySQL interface for this specific service. This will expose port `3306` for this service and prompt you with your MySQL connection screen that include your unique MySQL username. 
 
-<br/>
+2. Toggle the switch to enable the MySQL interface for this specific service. This will expose port `3306` for this service and prompt you with your MySQL connection screen that include your unique MySQL username.
+
 <div class="eighty-percent">
-![Credentials screen - Enabled MySQL](./images/mysql2.png)
+    <img src={mysql_2} class="image" alt="Credentials screen - Enabled MySQL" />
 </div>
 <br/>
 
@@ -20,20 +26,20 @@ Alternatively, in order to enable the MySQL interface for an existing service:
 
 <br/>
 <div class="eighty-percent">
-![Connection screen - Prompt MySQL](./images/mysql3.png)
+    <img src={mysql_3} class="image" alt="Connection screen - Prompt MySQL" />
 </div>
 <br/>
 
 
 4. Select MySQL from the `Connect With` drop down.
 
 <br/>
-![Connection screen - Prompt MySQL](./images/mysql4.png)
+<img src={mysql_4} class="image" alt="Connection screen - Prompt MySQL" />
 <br/>
 
-5. Toggle the switch to enable the MySQL interface for this specific service. This will expose port `3306` for this service and prompt you with your MySQL connection screen that include your unique MySQL username. 
+5. Toggle the switch to enable the MySQL interface for this specific service. This will expose port `3306` for this service and prompt you with your MySQL connection screen that include your unique MySQL username.
 
-![Connection screen -  MySQL Enabled](./images/mysql5.png)
+<img src={mysql_5} class="image" alt="Connection screen - MySQL Enabled" />
 
 ## Creating multiple MySQL users in ClickHouse Cloud {#creating-multiple-mysql-users-in-clickhouse-cloud}