Migrate from Paligo + Webpack to Docusaurus 3

.claude/launch.json

@@ -0,0 +1,11 @@
+{
+  "version": "0.0.1",
+  "configurations": [
+    {
+      "name": "docusaurus",
+      "runtimeExecutable": "npx",
+      "runtimeArgs": ["docusaurus", "serve", "--port", "3333"],
+      "port": 3333
+    }
+  ]
+}

.gitignore

@@ -3,5 +3,13 @@
 
 /temp
 /out
+/out_xml
 /deploy
-/node_modules
+/node_modules
+
+# Docusaurus
+.docusaurus/
+/build/
+
+# Migration intermediates
+/migration/docs/

README.md

@@ -17,4 +17,81 @@ The latest, user-friendly documentation is available at:
 👉 [docs.bitrise.io](https://docs.bitrise.io/)
 
 ## Note
-This repository is not intended for open source contributions. If you have questions or feedback about Bitrise or its documentation, please use the support channels provided on our website.
+This repository is not intended for open source contributions. If you have questions or feedback about Bitrise or its documentation, please use the support channels provided on our website.
+
+## Run the docs locally
+
+If you've never used Node.js or a docs site before, no problem — these steps walk you through everything.
+
+### 1. Install the tools you need (one-time setup)
+
+You need two things on your machine:
+
+- **Node.js** — the JavaScript runtime that powers Docusaurus. Get the **LTS** version from [nodejs.org](https://nodejs.org/) (or run `brew install node` on macOS). After installing, open a fresh terminal and confirm it's there:
+
+  ```bash
+  node --version   # should print v18.x or higher
+  npm --version    # should print 9.x or higher
+  ```
+
+- **Git** — to clone this repo. Check with `git --version`. macOS prompts you to install it on first run; on other systems grab it from [git-scm.com](https://git-scm.com/).
+
+### 2. Get the code
+
+```bash
+git clone git@github.com:bitrise-io/docs.git
+cd docs
+```
+
+### 3. Install the docs site's dependencies
+
+From inside the `docs/` folder:
+
+```bash
+npm install
+```
+
+This downloads everything Docusaurus needs into a `node_modules/` folder. It's safe to ignore the deprecation warnings; the install takes a minute or two.
+
+### 4. Start the docs locally
+
+```bash
+npm start
+```
+
+Docusaurus boots a development server, then opens [http://localhost:3000](http://localhost:3000) in your browser automatically. Every page is served at `/en/...` — for example [http://localhost:3000/en/bitrise-ci.html](http://localhost:3000/en/bitrise-ci.html).
+
+The dev server hot-reloads: edit any `.md` / `.mdx` file under `docs/` (or any partial under `src/partials/`), save, and the browser refreshes within a second.
+
+To stop the server, press `Ctrl+C` in the terminal.
+
+### 5. Build the static site (optional)
+
+When you want to verify the production build (same output that ships to docs.bitrise.io):
+
+```bash
+npm run build
+```
+
+The output lands in `build/`. To preview it locally:
+
+```bash
+npm run serve
+```
+
+### Where to edit what
+
+| You want to... | Edit this |
+|---|---|
+| Change the text of a page | `docs/<section>/.../<page>.md` or `.mdx` |
+| Change a piece of content reused across many pages | `src/partials/<readable-name>.mdx` |
+| Change the landing page (the `/` portal) | `src/pages/index.tsx` |
+| Change site-wide navbar / footer / colors | `docusaurus.config.ts`, `src/css/custom.css` |
+| Add a new image | drop it under `static/img/` and reference it as `/img/your-file.png` |
+
+### Troubleshooting
+
+- **`npm: command not found`** — Node.js isn't installed (or your terminal hasn't picked it up). Reinstall from [nodejs.org](https://nodejs.org/) and open a new terminal window.
+- **Build errors mentioning MDX** — usually a stray `<word>` or `{kebab-case}` placeholder in a Markdown file is being parsed as JSX. The error message points at the file and line; wrap the offending text in backticks (`` `<word>` ``) or escape with HTML entities (`&lt;word&gt;`).
+- **Port 3000 already in use** — pass a different port: `npm start -- --port 3001`.
+- **Browser shows an empty page after editing** — check the terminal for compile errors; the dev server pauses rendering until it can recompile.

docs/bitrise-build-cache/_category_.json

@@ -0,0 +1,8 @@
+{
+  "label": "Bitrise Build Cache",
+  "position": 1,
+  "link": {
+    "type": "doc",
+    "id": "bitrise-build-cache/index"
+  }
+}

docs/bitrise-build-cache/build-cache-for-bazel/_category_.json

@@ -0,0 +1,5 @@
+{
+  "label": "Build Cache for Bazel",
+  "position": 2,
+  "link": null
+}

docs/bitrise-build-cache/build-cache-for-bazel/configuring-the-build-cache-for-bazel-in-local-builds.md

@@ -0,0 +1,70 @@
+---
+title: "Configuring the build cache for Bazel in local builds"
+sidebar_position: 3
+slug: /bitrise-build-cache/build-cache-for-bazel/configuring-the-build-cache-for-bazel-in-local-builds
+sidebar_label: Configuring the Bitrise Build Cache for Bazel in local environments
+---
+
+You can use the Bitrise Build Cache for Bazel on any machine: you just need to create a `bitrise.bazelrc` configuration file that includes the required configuration for the cache endpoints.
+
+1. Select your Bitrise workspace and go to **Build Cache**.
+1. Click **New connection**.
+1. Select **Other CI provider** and then select your build tool from the dropdown menu.
+
+   ![2025-10-21-choose-build-tool.png](/img/_paligo/uuid-95236863-449a-87ff-2713-11f9a7f3cfdd.png)
+1. Click **Create token**.
+
+   ![2025-10-21-create-token.png](/img/_paligo/uuid-20c79dca-f52e-e046-e9f2-3fce1c6019ba.png)
+1. Enter a name and set it to never expire.
+1. Copy the keys and values of the two variables.
+1. Set the variables as Environment Variables in your local configuration.
+
+   ```
+   export BITRISE_BUILD_CACHE_WORKSPACE_ID=<workspace ID>
+   export BITRISE_BUILD_CACHE_AUTH_TOKEN=<token>
+   ```
+1. Download the CLI and install it in a temporary location. You will only need to use it to activate the build cache once, or if any of the settings change.
+
+   ```
+   curl --retry 5 -sSfL 'https://raw.githubusercontent.com/bitrise-io/bitrise-build-cache-cli/main/install/installer.sh' | sh -s -- -b /tmp/bin -d
+   ```
+1. Activate the Bitrise Build Cache.
+
+   There are a couple of flags you can use to control the configuration, but we recommend these defaults:
+
+   ```
+   /tmp/bin/bitrise-build-cache activate bazel --cache --cache-push=false
+   ```
+
+   :::note[Pulling from cache]
+
+   We recommend only pulling artifacts from the cache to avoid accidentally sharing incorrect cache data due to file modifications during a build.
+
+   For the full list of flags check the CLI’s `/tmp/bin/bitrise-build-cache activate bazel --help` command.
+
+   :::
+1. If you have Remote Build Execution enabled for your workspace, you can also use it locally by adding the `--rbe` flag.
+
+   :::note[Enabling RBE locally]
+
+   You will need to have the workers set up for your workspace, and the pool configuration in your repository’s `.bazelrc` file before enabling RBE locally!
+
+   :::
+1. Optionally, add your repository URL in your repository’s root `.bazelrc` file.
+
+   We recommend doing this to be able to identify your local builds.
+
+   :::note[Replace the URL]
+
+   Make sure to replace the placeholder URL in the command with your own!
+
+   :::
+
+   ```
+   build --remote_header='x-repository-url=https://github.com/bazelbuild/bazel.git'
+   build --bes_header='x-repository-url=https://github.com/bazelbuild/bazel.git'
+   ```
+
+That's it! You can now run any `bazel` commands and take advantage of the Bitrise Build Cache. You can check the invocation details through the link printed during builds:
+
+![bazel-local-printout.png](/img/_paligo/uuid-a87ac3d9-b1bf-89bc-8d33-84e7edc358c9.png)

docs/bitrise-build-cache/build-cache-for-bazel/configuring-the-build-cache-for-bazel-in-other-ci-environments.md

@@ -0,0 +1,46 @@
+---
+title: "Configuring the build cache for Bazel in other CI environments"
+sidebar_position: 2
+slug: /bitrise-build-cache/build-cache-for-bazel/configuring-the-build-cache-for-bazel-in-other-ci-environments
+sidebar_label: Configuring the Build Cache for Bazel in non-Bitrise CI environments
+---
+
+The Bitrise Build Cache does not require using the Bitrise CI. You can use other CI/CD services and still take advantage of remote caching to improve your Bazel build times.
+
+To do so, you need to configure your CI environment to download the Bitrise Build Cache CLI during the build and then run the CLI to enable the Bitrise Build Cache.
+
+1. Select your Bitrise workspace and go to **Build Cache**.
+1. Click **New connection**.
+1. Select **Other CI provider** and then select your build tool from the dropdown menu.
+
+   ![2025-10-21-choose-build-tool.png](/img/_paligo/uuid-95236863-449a-87ff-2713-11f9a7f3cfdd.png)
+1. Click **Create token**.
+
+   ![2025-10-21-create-token.png](/img/_paligo/uuid-20c79dca-f52e-e046-e9f2-3fce1c6019ba.png)
+1. Enter a name and set it to never expire.
+1. Copy the variables and add them to your CI configuration as Environment Variables.
+1. Add the following script to your CI configuration before the step you want to speed up:
+
+   :::important[Environment]
+
+   Make sure to run the script in the same environment as the Bazel command you want to speed up. For example, if you use multiple Docker containers throughout the build, make sure that the Bitrise Build Cache CLI runs in the same Docker container as the Bazel command.
+
+   :::
+
+   ```
+   #!/usr/bin/env bash
+   set -euxo pipefail
+
+   # download Bitrise Build Cache CLI
+   curl --retry 5 -sSfL 'https://raw.githubusercontent.com/bitrise-io/bitrise-build-cache-cli/main/install/installer.sh' | sh -s -- -b /tmp/bin -d
+
+   # run the CLI to enable Bitrise build cache for Bazel
+   /tmp/bin/bitrise-build-cache activate bazel --cache --cache-push
+   ```
+1. If you have Remote Build Execution enabled for your workspace, you can also use it locally by adding the `--rbe` flag.
+
+   :::note[Enabling RBE locally]
+
+   You will need to have the workers set up for your workspace, and the pool configuration in your repository’s `.bazelrc` file before enabling RBE locally!
+
+   :::

docs/bitrise-build-cache/build-cache-for-bazel/configuring-the-build-cache-for-bazel-in-the-bitrise-ci-environment.mdx

@@ -0,0 +1,35 @@
+---
+title: "Configuring the build cache for Bazel in the Bitrise CI environment"
+sidebar_position: 1
+slug: /bitrise-build-cache/build-cache-for-bazel/configuring-the-build-cache-for-bazel-in-the-bitrise-ci-environment
+sidebar_label: Configuring the Bitrise Build Cache for Bazel in the Bitrise CI environment
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+import GlossTerm from '@site/src/components/GlossTerm';
+import Partial_OpeningTheWorkflowEditorAndSelectingAWorkflow from '@site/src/partials/opening-the-workflow-editor-and-selecting-a-workflow.mdx';
+
+You can use the Bitrise Build Cache for Bazel on the Bitrise CI by adding our dedicated Step to your Workflow. The Step activates the Bitrise Build Cache. After it executes, Bazel builds will automatically read from the build cache and push new entries if it's enabled.
+
+Workflow Editor
+
+bitrise.yml
+
+1. <Partial_OpeningTheWorkflowEditorAndSelectingAWorkflow />
+1. Add the **Bitrise Build Cache for Bazel** Step to your Workflow.
+
+   The Step requires no configuration.
+
+1. Open the `bitrise.yml` file and add the `activate-build-cache-for-bazel` Step to your Workflow.
+
+   The Step requires no configuration.
+
+   ```yaml
+   your-workflow:
+     steps:
+       - git-clone: {}
+       - activate-build-cache-for-bazel:
+   ```
+
+During your first build, outputs will be saved to cache. We recommend running a couple of builds to ensure the cache is warmed up.

docs/bitrise-build-cache/build-cache-for-bazel/index.md

@@ -0,0 +1,8 @@
+---
+title: "Build cache for Bazel"
+sidebar_position: 2
+slug: /bitrise-build-cache/build-cache-for-bazel
+sidebar_label: Build Cache for Bazel
+---
+
+Build Cache for Bazel

docs/bitrise-build-cache/build-cache-for-bazel/remote-build-execution-for-bazel.mdx

@@ -0,0 +1,76 @@
+---
+title: "Remote build execution for Bazel"
+description: "Remote execution of a Bazel build allows you to distribute build and test actions across multiple machines. This speeds up build and test execution, allows reuse of build outputs across development teams, and provides"
+sidebar_position: 4
+slug: /bitrise-build-cache/build-cache-for-bazel/remote-build-execution-for-bazel
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+import GlossTerm from '@site/src/components/GlossTerm';
+import Partial_RecommendedFlagsForRemoteBuildExecution from '@site/src/partials/recommended-flags-for-remote-build-execution.mdx';
+
+Remote execution of a Bazel build allows you to distribute build and test actions across multiple machines. This speeds up build and test execution, allows reuse of build outputs across development teams, and provides a consistent environment.
+
+You can use the Bitrise Build Cache with remote build execution both on Bitrise and in a non-Bitrise CI environment.
+
+## Configuring remote build execution on Bitrise
+
+<Tabs>
+<TabItem value="workflow-editor" label="Workflow Editor" default>
+
+1. Set up the Bitrise Build Cache for Bazel: [Configuring the build cache for Bazel in the Bitrise CI environment](/en/bitrise-build-cache/getting-started-with-the-build-cache/build-cache-for-bazel/configuring-the-build-cache-for-bazel-in-the-bitrise-ci-environment).
+1. Log in to Bitrise and select **Bitrise CI** on the left, then select your project.
+1. Click the **Workflows** button on the main page.
+1. In the **Bitrise Build Cache for Bazel** Step, set the **Enable Bazel RBE** input field to **true**.
+
+</TabItem>
+<TabItem value="configuration-yaml" label="Configuration YAML">
+
+1. Open your configuration YAML file.
+1. Add the `activate-build-cache-for-bazel` Step to your Workflow.
+
+   ```
+   your-workflow:
+     steps:
+       - git-clone: {}
+       - activate-build-cache-for-bazel:
+           inputs:
+           - enable_rbe: true
+   ```
+
+</TabItem>
+</Tabs>
+
+## Configuring remote build execution in a non-Bitrise environment
+
+<Tabs>
+<TabItem value="other-ci" label="Other CI" default>
+
+1. Start setting up the Bitrise Build Cache for Bazel: [Configuring the build cache for Bazel in other CI environments](/en/bitrise-build-cache/getting-started-with-the-build-cache/build-cache-for-bazel/configuring-the-build-cache-for-bazel-in-other-ci-environments).
+1. When enabling the Bitrise Build Cache, add the `--rbe` flag.
+
+   ```
+   /tmp/bin/bitrise-build-cache activate bazel --cache --cache-push=false --rbe
+   ```
+
+   :::note[Cache]
+
+   We recommend setting the `--cache-push` flag to false because during remote build execution, workers upload results to the cache.
+
+   :::
+
+</TabItem>
+<TabItem value="local-environment" label="Local environment">
+
+1. Start setting up the Bitrise Build Cache for Bazel: [Configuring the build cache for Bazel in local builds](/en/bitrise-build-cache/getting-started-with-the-build-cache/build-cache-for-bazel/configuring-the-build-cache-for-bazel-in-local-builds).
+1. Add the RBE endpoint config to your `.bazelrc`:
+
+   ```
+   build:remote --remote_executor=grpcs://bitrise-accelerate.services.bitrise.io:443
+   ```
+
+</TabItem>
+</Tabs>
+
+<Partial_RecommendedFlagsForRemoteBuildExecution />

docs/bitrise-build-cache/build-cache-for-gradle/_category_.json

@@ -0,0 +1,5 @@
+{
+  "label": "Build Cache for Gradle",
+  "position": 3,
+  "link": null
+}