merged with main and replaced img with Image

Author: razvanilin

.github/ISSUE_TEMPLATE/translation_issue.yaml

@@ -0,0 +1,39 @@
+name: Translation Issue Report
+description: File a report for translated documentation.
+title: "[translation issue]: "
+labels: ["translation issue"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Please report any problems found with translations of the documentation
+        using this form.
+  - type: dropdown
+    id: language
+    attributes:
+      label: Language
+      description: For which language are you reporting a translation issue?
+      options:
+        - Русский (Russian)
+        - 中文 (Mandarin)
+        - 日本語 (Japanese)
+      default: 0
+    validations:
+      required: true
+  - type: input
+    id: url
+    attributes:
+      label: URL to page
+      description: Please provide the URL of the page in question.
+      placeholder: eg. https://clickhouse.com/docs/ru/architecture/replication
+    validations:
+      required: true
+  - type: textarea
+    id: problem
+    attributes:
+      label: What is the problem?
+      description: Please tell us what the problem is
+      placeholder: Tell us what you see!
+      value: "The translation issue on this page is..."
+    validations:
+      required: true

.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
@@ -53,8 +54,12 @@ docs/whats-new/changelog/index.md
 .aspell.en.prepl
 *.md.bak
 
-# Don't ignore generated table of contents files
-!toc.json
 **.translated
 **.translate
 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

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,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
@@ -61,21 +76,31 @@ 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'
+import Image from '@theme/IdealImage';
 ```
 
-Use the `<img/>` tag to place your image in the appropriate place:
+To render images we use a fork of the IdealImage plugin. This generates multiple variants of an image, [asynchronously loading them as well as selecting the most appropriate based on the network connection](https://github.com/stereobooster/react-ideal-image/blob/master/introduction.md).
+
+Ensure you import the `Image` component as shown above.
+
+Use the `<Image/>` 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
-/>
+<Image img={clickhouse-local-1} alt='DESCRIPTION OF THE IMAGE' size="md" border background="black"/>
 
 Here is another paragraph...
 ```
 
+This component takes a number of props:
+
+1. `img` - the imported image
+2. `alt` - mandatory alternate text specified
+3. `size` - either `lg` (width 1024px), `md` (width 600px), `sm` (width 300px) or `logo` (48x). This sets the maximum image size. Lower resolutions maybe used on smaller screens or slower connections.
+4. `border` - Applies a border. **Use for screenshots only.**
+5. `background` - either `white` or `black`. Applicable if your image is transparent. All new images must use `black`.
+
 ## Codeblocks
 
 Codeblocks are defined using backticks. For example:
@@ -92,6 +117,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)
@@ -159,4 +216,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

@@ -1,4 +1,3 @@
-
 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';
@@ -7,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>