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

Author: Blargian

.github/CODEOWNERS

@@ -1 +1,2 @@
-/docs/en/integrations/ @ClickHouse/integrations
+*                      @ClickHouse/docs
+/docs/integrations/ @ClickHouse/integrations @ClickHouse/docs

.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

.github/dependabot.yml

@@ -6,13 +6,13 @@ updates:
     schedule:
       interval: "monthly"
   - package-ecosystem: "npm"
-    directory: "/docs/en/integrations"
+    directory: "/docs/integrations"
     schedule:
       interval: "monthly"
     # Disable version updates for dependencies in the code snippets
     open-pull-requests-limit: 0
   - package-ecosystem: "pip"
-    directory: "/docs/en/integrations"
+    directory: "/docs/integrations"
     schedule:
       interval: "monthly"
     # Disable version updates for dependencies in the code snippets

.github/pull_request_template.md

@@ -4,4 +4,4 @@
 ## Checklist
 - [ ] Delete items not relevant to your PR
 - [ ] URL changes should add a redirect to the old URL via https://github.com/ClickHouse/clickhouse-docs/blob/main/docusaurus.config.js
-- [ ] If adding a new integration page, also add an entry to the integrations list here: https://github.com/ClickHouse/clickhouse-docs/blob/main/docs/en/integrations/index.mdx
+- [ ] If adding a new integration page, also add an entry to the integrations list here: https://github.com/ClickHouse/clickhouse-docs/blob/main/docs/integrations/index.mdx

.github/workflows/check-build.yml

@@ -14,47 +14,69 @@ on:
 jobs:
   stylecheck:
     runs-on: ubuntu-latest
-
+    strategy:
+      matrix:
+        check_type: [spellcheck, kbcheck, md-lint]
     steps:
-      # Step 1: Check out the repository
-      - name: Check out repository
-        uses: actions/checkout@v4
-
-      # Step 2: Set up environment if required (e.g., installing Aspell)
+      # Add setup steps per check here
+      - uses: actions/checkout@v4
       - name: Install Aspell
+        if: matrix.check_type == 'spellcheck'
         run: sudo apt-get update && sudo apt-get install -y aspell aspell-en
-
-      # Step 3: Run the spellcheck script
-      - name: Run spellcheck
-        run: |
-          ./scripts/check-doc-aspell
-        continue-on-error: true
-        id: spellcheck
-
-      # Step 4: Setup Python and dependencies for KB checker
       - name: Set up Python
+        if: matrix.check_type == 'kbcheck'
         uses: actions/setup-python@v5
         with:
           python-version: '3.x'
-
-      # Step 5: Install Python dependencies
       - name: Install dependencies
+        if: matrix.check_type == 'kbcheck'
         run: |
           python -m pip install --upgrade pip
           pip install -r 'scripts/knowledgebase-checker/requirements.txt'
+      - name: Setup md-lint environment
+        if: matrix.check_type == 'md-lint'
+        uses: actions/setup-node@v3
+        with:
+          node-version: 20
+      - name: Install markdownlint-cli2
+        if: matrix.check_type == 'md-lint'
+        run: yarn add -D markdownlint-cli2
 
-      # Step 5: Run knowledgebase article checker
-      - name: Check KB
-        run: |
-          ./scripts/knowledgebase-checker/knowledgebase_article_checker.py --kb-dir="knowledgebase"
-        continue-on-error: true
-        id: kbcheck
-
-      # Step 6: Fail the build if any script returns exit code 1
-      - name: Check exit code
+      # Run the checks here
+      - name: Run checks
+        id: check_step
         run: |
-          if [[ "${{ steps.spellcheck.outcome }}" == "failure" ]] || [[ "${{ steps.kbcheck.outcome }}" == "failure" ]]; then
-            echo "Style check failed. See the logs for details."
+          if [[ "${{ matrix.check_type }}" == "spellcheck" ]]; then
+            ./scripts/check-doc-aspell
+          exit_code=$?
+          elif [[ "${{ matrix.check_type }}" == "kbcheck" ]]; then
+            ./scripts/knowledgebase-checker/knowledgebase_article_checker.py --kb-dir="knowledgebase"
+          exit_code=$?
+          elif [[ "${{ matrix.check_type }}" == "md-lint" ]]; then
+            yarn markdownlint-cli2 --config ./scripts/.markdownlint-cli2.yaml 'docs/**/*.md'
+          exit_code=$?
+          fi
+          
+          if [[ $exit_code -ne 0 ]]; then
+            echo "::error::${{ matrix.check_type }} check failed. See logs for details."
             exit 1
           fi
+
+      - name: Set check status
+        if: steps.check_step.outcome != 'success'
+        uses: actions/github-script@v6
+        with:
+          script: |
+            core.setFailed('${{ matrix.check_type }} check failed.');
+          
+  check_overall_status:
+    needs: stylecheck
+    runs-on: ubuntu-latest
+    if: always() # run the job even if stylecheck fails
+    steps:
+      - name: Check overall results
+        if: needs.stylecheck.result != 'success'
+        run: |
+          echo "::error::One or more checks of the style check failed."
+          exit 1
           

.gitignore

@@ -2,22 +2,22 @@ node_modules
 .docusaurus
 .vercel
 build
-docs/en/development
-docs/en/engines
-docs/en/getting-started
-docs/en/interfaces
-docs/en/operations
-docs/en/sql-reference
+docs/development
+docs/engines
+docs/getting-started
+docs/interfaces
+docs/operations
+docs/sql-reference
+docs/_clients
 docs/ru
 docs/zh
-docs/_clients
 
 **/.DS_Store
 run.sh
 cleanup.sh
 update.sh
 
-docs/en/whats-new/changelog/_2023.md
+docs/whats-new/changelog/_2023.md
 
 .ignore
 .marksman.toml
@@ -40,14 +40,22 @@ active_links.json
 scripts/settings/tmp
 
 # Files whose content gets autogenerated
-docs/en/cloud/manage/api/invitations-api-reference.md
-docs/en/cloud/manage/api/keys-api-reference.md
-docs/en/cloud/manage/api/members-api-reference.md
-docs/en/cloud/manage/api/organizations-api-reference.md
-docs/en/cloud/manage/api/services-api-reference.md
+docs/cloud/manage/api/invitations-api-reference.md
+docs/cloud/manage/api/keys-api-reference.md
+docs/cloud/manage/api/members-api-reference.md
+docs/cloud/manage/api/organizations-api-reference.md
+docs/cloud/manage/api/services-api-reference.md
+docs/cloud/manage/api/privateEndpointConfig-api-reference.md
+docs/cloud/manage/api/prometheus-api-reference.md
+docs/cloud/manage/api/usageCost-api-reference.md
+docs/whats-new/changelog/index.md
 .vscode
 .aspell.en.prepl
 *.md.bak
 
-# Don't ignore generated table of contents files
-!toc.json
+**.translated
+**.translate
+ClickHouse/
+
+# Ignore generated table of contents files
+docs/cloud/reference/release-notes-index.md

README.md

@@ -18,25 +18,25 @@
 
 ClickHouse is blazing fast, but understanding ClickHouse and using it effectively is a journey. The documentation is your source for gaining the knowledge you need to be successful with your ClickHouse projects and applications. [Head over to clickhouse.com/docs to learn more →](https://clickhouse.com/)
 
-## Table of contents
+## Table of contents {#table-of-contents}
 
 - [About this repo](#about-this-repo)
 - [Run locally](#run-locally)
 - [Contributing](#contributing)
 - [Issues](#issues)
 - [License](#license)
 
-## About this repo
+## About this repo {#about-this-repo}
 
 This repository manages the documentation for [ClickHouse](https://clickhouse.com/docs). The content is built with [Docusaurus](https://docusaurus.io/) and hosted on [Vercel](https://vercel.com). Documentation content is written in Markdown and is held in the `/docs` directory.
 
-## Run locally
+## Run locally {#run-locally}
 
 You can run a copy of this website locally within a few steps. Some folks find this useful when contributing so they can see precisely what their changes will look like on the production site.
 
 1. Install Git and npm. If you already have them installed, skip this step:
 
-    | OS | Package manager | Install command | 
+    | OS | Package manager | Install command |
     | ---| --------------- | --------------- |
     | macOS | Homebrew | `brew install git node` |
     | Ubuntu | Apt | `sudo apt install git nodejs npm` |
@@ -69,22 +69,16 @@ You can run a copy of this website locally within a few steps. Some folks find t
     # ✨  Done in 6.44s.
     ```
 
-1. Use Yarn to grab the latest documentation changes from the `ClickHouse/ClickHouse` repository:
+1. Use Yarn to grab the latest documentation changes from the `ClickHouse/ClickHouse` repository and build the documentation using `yarn-build`:
 
     ```shell
-    yarn copy-clickhouse-repo-docs
+    yarn build
 
     # Cloning into 'ClickHouse'...
     # ...
-    # Copying docs from ClickHouse ...
-    # Successfully executed copy from master
-    # ✨  Done in 18.56s.
-    ```
-
-    Alternatively, you can use a local copy of `ClickHouse/ClickHouse` if you already have that repository cloned locally with `-l`.
-
-    ```shell
-    yarn copy-clickhouse-repo-docs -l "/Users/johnny/clickhouse/"
+    # [SUCCESS] Generated static files in "build".
+    # [INFO] Use `npm run serve` command to test your build locally.
+    # ✨  Done in 105.96s.
     ```
 
 1. Start the local web-server:
@@ -98,35 +92,51 @@ You can run a copy of this website locally within a few steps. Some folks find t
     #
     ```
 
-    This command will build the documentation site and serve it locally. Once the build has finished, browse the website at [localhost:3000](http://localhost:3000/docs/en/intro).
+    This command will build the documentation site and serve it locally. Once the build has finished, browse the website at [localhost:3000](http://localhost:3000/docs/intro).
 
 1. To stop the local server, press `ctrl` + `c` in the terminal window.
 
 If you want to build a static copy of this repository that doesn't require a constant server running to view, you can use `yarn build` instead of `yarn start`. The `yarn build` will output a static copy of the website in the `/build` directory. This process takes around 10 minutes to complete on an M1 Macbook with 8GB RAM.
 
-### Notes
+1. Should you wish to make changes to documents which are located in the ClickHouse/ClickHouse repo and want to visualize what the changes made look like locally you can use `yarn copy-clickhouse-repo-docs -l` and provide a path to the ClickHouse repository on your local machine, for example:
+
+   ```
+   # yarn copy-clickhouse-repo-docs -l /Users/user/Desktop/ClickHouse
+   # Successfully executed local copy
+   # ✨  Done in 1.15s.
+   ```
+
+We recommend to install rsync in order to only copy what is needed, however the script will fallback to using `cp` if rsync is not available.
+
+Running `yarn copy-clickhouse-repo-docs` without any arguments will pull in the latest docs changes from github.
+
+### Notes {#notes}
 
 Here are some things to keep in mind when building a local copy of the ClickHouse docs site.
 
-#### Build-time
+#### Build-time {#build-time}
 
 Due to the complex structure of this repo, the docs site can take some time to build locally. As a benchmark, it takes ~3 minutes to build on an M1 Macbook with 8GB RAM.
 
-#### Redirects
+#### Redirects {#redirects}
 
-Due to how the local server is built, redirects will not work. For example, visiting `clickhouse.com/docs` on the production site will lead you to `clickhouse.com/docs/en/intro`. However, on a local copy of the site, you will see a 404 page if you try to visit `localhost:8000/docs`.
+Due to how the local server is built, redirects will not work. For example, visiting `clickhouse.com/docs` on the production site will lead you to `clickhouse.com/docs/intro`. However, on a local copy of the site, you will see a 404 page if you try to visit `localhost:8000/docs`.
 
-## Contributing
+## Contributing {#contributing}
 
 Want to help out? Contributions are always welcome! If you want to help out but aren't sure where to start, check out the [issues board](https://github.com/clickhouse/clickhouse-docs/issues).
 
-### Pull requests
+### Pull requests {#pull-requests}
 
 Please assign any pull request (PR) against an issue; this helps the docs team track who is working on what and what each PR is meant to address. If there isn't an issue for the specific _thing_ you want to work on, quickly create one and comment so that it can be assigned to you. One of the repository maintainers will add you as an assignee.
 
 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).
 
-### Tests and CI/CD
+### 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:
 
@@ -138,7 +148,7 @@ There are five workflows that run against PRs in this repo:
 | [Scheduled Vercel build](https://github.com/ClickHouse/clickhouse-docs/blob/main/.github/workflows/scheduled-vercel-build.yml) | Builds the site every day at 00:10 UTC and hosts the build on Vercel. |
 | [Trigger build](https://github.com/ClickHouse/clickhouse-docs/blob/main/.github/workflows/trigger-build.yml) | Uses the [peter-evans/repository-dispatch@v2](https://github.com/peter-evans/repository-dispatch) workflow to create a repository dispatch. |
 
-### Quick contributions
+### Quick contributions {#quick-contributions}
 
 Have you noticed a typo or found some wonky formatting? For small contributions like these, it's usually faster and easier to make your changes directly in GitHub. Here's a quick guide to show you how the GitHub editor works:
 
@@ -150,33 +160,33 @@ Have you noticed a typo or found some wonky formatting? For small contributions
 
 1. Once you're in GitHub, click the pencil icon to edit this page:
 
-    ![](./images/readme-pencil-icon.png)
+    ![README Pencil Icon](./images/readme-pencil-icon.png)
 
 1. GitHub will _fork_ the repository for you. This creates a copy of the `clickhouse-docs` repository on your personal GitHub account.
 1. Make your changes in the textbox. Once you're done, click **Commit changes**:
 
-    ![](./images/readme-commit-changes.png)
+    ![README Commit Changes](./images/readme-commit-changes.png)
 
 1. In the **Propose changes** popup, enter a descriptive title to explain the changes you just made. Keep this title to 10 words or less. If your changes are fairly complex and need further explanation, enter your comments into the **Extended description** field.
 1. Make sure **Create a new branch** is selected, and click **Propose changes**:
 
-    ![](./images/readme-propose-changes.png)
+    ![README Propose Changes](./images/readme-propose-changes.png)
 
 1. A new page should open with a new pull request. Double-check that the title and description are accurate.
 1. If you've spoken to someone on the docs team about your changes, tag them into the **Reviewers** section:
 
-    ![](./images/readme-create-pull-request.png)
+    ![README Create Pull Request](./images/readme-create-pull-request.png)
 
     If you haven't mentioned your changes to anyone yet, leave the **Reviewers** section blank.
 
 1. Click **Create pull request**.
 
 At this point, your pull request will be handed over to the docs team, who will review it and suggest or make changes where necessary.
 
-## Issues
+## Issues {#issues}
 
 Found a problem with the Clickhouse docs site? [Please raise an issue](https://github.com/clickhouse/clickhouse-docs/issues/new). Be as specific and descriptive as possible; screenshots help!
 
-## License
+## License {#license}
 
 This work is licensed under a [Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License](http://creativecommons.org/licenses/by-nc-sa/4.0/).