From 8d4872773f742d35d72d962f44bee1edc3fe82ff Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?K=C3=A9vin=20Frick?= <kevin.frick@botpress.com>
Date: Mon, 15 Jun 2026 12:01:12 -0400
Subject: [PATCH 1/2] fix: prevent duplicate code snippets before hydration

---
 src/components/CodeGroup.tsx | 2 +-
 src/styles/global.css        | 6 ++++++
 2 files changed, 7 insertions(+), 1 deletion(-)

diff --git a/src/components/CodeGroup.tsx b/src/components/CodeGroup.tsx
index 146a82b..72d2aa0 100644
--- a/src/components/CodeGroup.tsx
+++ b/src/components/CodeGroup.tsx
@@ -73,7 +73,7 @@ function CodeGroup({ children }: { children: ReactNode }) {
   const activeLineCount = activeInfo?.lineCount ?? 0
 
   return (
-    <div className="code-group not-prose">
+    <div className="code-group not-prose" data-ready={tabs.length > 0 ? 'true' : undefined}>
       {tabs.length > 0 && (
         <div className="code-group-tabs" role="tablist">
           {tabs.map((title, i) => (
diff --git a/src/styles/global.css b/src/styles/global.css
index 5036ca2..bbec989 100644
--- a/src/styles/global.css
+++ b/src/styles/global.css
@@ -230,6 +230,12 @@
   overflow: hidden;
 }
 
+/* Before React hydrates CodeGroup, keep only the first snippet visible. */
+.code-group:not([data-ready='true']) astro-slot > pre.astro-code:not(:first-of-type),
+.code-group:not([data-ready='true']) > div > pre.astro-code:not(:first-of-type) {
+  display: none;
+}
+
 .code-group-tabs {
   display: flex;
   align-items: center;

From 14a54a31330a6c651521fb2e4521ab3bd022bc8c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?K=C3=A9vin=20Frick?= <kevin.frick@botpress.com>
Date: Mon, 15 Jun 2026 14:30:29 -0400
Subject: [PATCH 2/2] fix: normalize code block metadata

---
 src/content/docs/adk/conversations/setup.mdx  |  5 +-
 .../docs/integrations/sdk/bots-as-code.mdx    | 20 +++---
 .../docs/integrations/sdk/cli-reference.mdx   | 69 ++++++++++++-------
 .../docs/integrations/sdk/installation.mdx    |  4 +-
 .../integrations/sdk/integration/concepts.mdx |  2 +-
 .../sdk/integration/getting-started.mdx       | 12 ++--
 .../sdk/integration/messaging.mdx             |  3 +-
 .../webchat/get-started/embedding-webchat.mdx |  2 +-
 src/content/docs/webchat/integrations/wix.mdx |  2 +-
 .../webchat/interact/webchat-notification.mdx |  4 +-
 10 files changed, 73 insertions(+), 50 deletions(-)

diff --git a/src/content/docs/adk/conversations/setup.mdx b/src/content/docs/adk/conversations/setup.mdx
index ee7e83a..a36355e 100644
--- a/src/content/docs/adk/conversations/setup.mdx
+++ b/src/content/docs/adk/conversations/setup.mdx
@@ -72,7 +72,10 @@ export default new Conversation({
 
 ```ts title="Array of channels" highlight={2-5}
 export default new Conversation({
-  channel: ['chat.channel', 'webchat.channel'],
+  channel: [
+    'chat.channel',
+    'webchat.channel'
+  ],
   handler: async ({ execute }) => {
     await execute({
       instructions: 'You are a helpful assistant.',
diff --git a/src/content/docs/integrations/sdk/bots-as-code.mdx b/src/content/docs/integrations/sdk/bots-as-code.mdx
index a0f90e5..be277a0 100644
--- a/src/content/docs/integrations/sdk/bots-as-code.mdx
+++ b/src/content/docs/integrations/sdk/bots-as-code.mdx
@@ -35,16 +35,16 @@ yarn add -g @botpress/cli
 
 You can check that your installation was successful by running the following command:
 
-```bash title="bp --help"
-
+```bash
+bp --help
 ```
 
 ## 2. Log in to Botpress
 
 Next, log in to your Botpress account using the Botpress CLI. You can do this by running the following command in your terminal:
 
-```bash title="bp login"
-
+```bash
+bp login
 ```
 
 {/* TODO: add a guide on how to create a personal access token and link to it. */}
@@ -113,8 +113,8 @@ export default new BotDefinition({}).addIntegration(chat, {
 
 To refresh types available in your bot implementation, run the following command:
 
-```bash title="bp gen"
-
+```bash
+bp gen
 ```
 
 ## 7. Implement a message handlers
@@ -161,8 +161,8 @@ This bot will respond to any message sent to it. It will echo back the text mess
 
 Once you've made the necessary changes to your bot, you can deploy it to Botpress Cloud. Run the following command:
 
-```bash title="bp deploy --create-new-bot"
-
+```bash
+bp deploy --create-new-bot
 ```
 
 You'll be prompted for some information and confirmations. The `--create-new-bot` flag will create a new bot in your workspace. If you want to deploy to an existing bot, you can omit this flag. The CLI will prompt you for the bot in which you want to deploy.
@@ -173,8 +173,8 @@ After deploying, go to [the Dashboard](https://app.botpress.cloud). You should s
 
 Now you can chat with your bot using the CLI. Run the following command:
 
-```bash title="bp chat"
-
+```bash
+bp chat
 ```
 
 This command will prompt you for the bot you want to chat with. Select the bot you just deployed, and start chatting with it. Press the escape key to exit the chat.
diff --git a/src/content/docs/integrations/sdk/cli-reference.mdx b/src/content/docs/integrations/sdk/cli-reference.mdx
index ff08a99..fc7a03f 100644
--- a/src/content/docs/integrations/sdk/cli-reference.mdx
+++ b/src/content/docs/integrations/sdk/cli-reference.mdx
@@ -25,7 +25,8 @@ Login to Botpress Cloud.
 
 **Usage:**
 
-```bash title="bp login"
+```bash
+bp login
 bp login --token your-token --workspace-id your-workspace-id
 ```
 
@@ -45,8 +46,8 @@ Logout of Botpress Cloud.
 
 **Usage:**
 
-```bash title="bp logout"
-
+```bash
+bp logout
 ```
 
 ---
@@ -57,7 +58,8 @@ Initialize a new project.
 
 **Usage:**
 
-```bash title="bp init"
+```bash
+bp init
 bp init --type bot --name my-bot
 bp init --type integration --template webhook-message
 ```
@@ -79,7 +81,8 @@ Generate typings for IntelliSense. Alias: `gen`
 
 **Usage:**
 
-```bash title="bp generate"
+```bash
+bp generate
 bp gen --work-dir ./my-project
 ```
 
@@ -97,7 +100,8 @@ Generate typings and bundle a project.
 
 **Usage:**
 
-```bash title="bp build"
+```bash
+bp build
 bp build --work-dir ./my-project --minify false
 ```
 
@@ -117,7 +121,8 @@ Bundle a Botpress project.
 
 **Usage:**
 
-```bash title="bp bundle"
+```bash
+bp bundle
 bp bundle --work-dir ./my-project --source-map
 ```
 
@@ -137,7 +142,8 @@ Serve your project locally.
 
 **Usage:**
 
-```bash title="bp serve"
+```bash
+bp serve
 bp serve --port 8080 --secrets SECRET1=value1 SECRET2=value2
 ```
 
@@ -157,7 +163,8 @@ Run your project in dev mode.
 
 **Usage:**
 
-```bash title="bp dev"
+```bash
+bp dev
 bp dev --port 3000 --secrets API_KEY=secret123
 ```
 
@@ -183,7 +190,8 @@ Deploy your project to the cloud.
 
 **Usage:**
 
-```bash title="bp deploy"
+```bash
+bp deploy
 bp deploy --bot-id my-bot-id --visibility public
 bp deploy --create-new-bot --no-build
 ```
@@ -245,7 +253,8 @@ Read and parse an integration definition.
 
 **Usage:**
 
-```bash title="bp read"
+```bash
+bp read
 bp read --work-dir ./my-integration
 ```
 
@@ -263,7 +272,8 @@ Lint an integration definition (experimental).
 
 **Usage:**
 
-```bash title="bp lint"
+```bash
+bp lint
 bp lint --work-dir ./my-integration
 ```
 
@@ -281,7 +291,8 @@ Chat with a bot directly from CLI (experimental).
 
 **Usage:**
 
-```bash title="bp chat my-bot-id"
+```bash
+bp chat my-bot-id
 bp chat my-bot-id --chat-api-url https://chat.example.com
 ```
 
@@ -312,7 +323,8 @@ Create a new bot. Alias: `new`
 
 **Usage:**
 
-```bash title="bp bots create --name my-bot"
+```bash
+bp bots create --name my-bot
 bp bots new --name my-bot --if-not-exists
 ```
 
@@ -334,7 +346,8 @@ List bots. Alias: `ls`
 
 **Usage:**
 
-```bash title="bp bots list"
+```bash
+bp bots list
 bp bots ls --dev
 ```
 
@@ -355,8 +368,8 @@ Get bot details.
 
 **Usage:**
 
-```bash title="bp bots get my-bot-id"
-
+```bash
+bp bots get my-bot-id
 ```
 
 **Arguments:**
@@ -381,7 +394,8 @@ Delete a bot. Alias: `rm`
 
 **Usage:**
 
-```bash title="bp bots delete my-bot-id"
+```bash
+bp bots delete my-bot-id
 bp bots rm my-bot-id
 ```
 
@@ -411,7 +425,8 @@ List integrations. Alias: `ls`
 
 **Usage:**
 
-```bash title="bp integrations list"
+```bash
+bp integrations list
 bp integrations ls --name teams --dev
 ```
 
@@ -492,7 +507,8 @@ List interfaces. Alias: `ls`
 
 **Usage:**
 
-```bash title="bp interfaces list"
+```bash
+bp interfaces list
 bp interfaces ls
 ```
 
@@ -570,7 +586,8 @@ List plugins. Alias: `ls`
 
 **Usage:**
 
-```bash title="bp plugins list"
+```bash
+bp plugins list
 bp plugins ls --name knowledge
 ```
 
@@ -650,7 +667,8 @@ List all available profiles. Alias: `ls`
 
 **Usage:**
 
-```bash title="bp profiles list"
+```bash
+bp profiles list
 bp profiles ls
 ```
 
@@ -662,8 +680,8 @@ Get the profile properties you are currently using.
 
 **Usage:**
 
-```bash title="bp profiles active"
-
+```bash
+bp profiles active
 ```
 
 ---
@@ -674,7 +692,8 @@ Set the current profile.
 
 **Usage:**
 
-```bash title="bp profiles use my-profile"
+```bash
+bp profiles use my-profile
 bp profiles use production
 ```
 
diff --git a/src/content/docs/integrations/sdk/installation.mdx b/src/content/docs/integrations/sdk/installation.mdx
index 28b40cc..3c24b94 100644
--- a/src/content/docs/integrations/sdk/installation.mdx
+++ b/src/content/docs/integrations/sdk/installation.mdx
@@ -32,6 +32,6 @@ yarn add -g @botpress/cli
 
 You can check that your installation was successful by running the following command:
 
-```bash title="bp --help"
-
+```bash
+bp --help
 ```
diff --git a/src/content/docs/integrations/sdk/integration/concepts.mdx b/src/content/docs/integrations/sdk/integration/concepts.mdx
index 81ed797..dde35ca 100644
--- a/src/content/docs/integrations/sdk/integration/concepts.mdx
+++ b/src/content/docs/integrations/sdk/integration/concepts.mdx
@@ -68,7 +68,7 @@ Integrations can also provide multiple configuration schemas to support differen
 
 For example, here's how the official [GitHub](https://botpress.com/integrations/github) integration [defines its configuration schemas](https://github.com/botpress/botpress/blob/840e7e65901d0234353ad6890b0ad49a734b4de5/integrations/github/src/definitions/index.ts#L28-L65):
 
-```ts title="expandable"
+```ts [expandable]
 export const configurations = {
   manualApp: {
     title: 'Manual configuration',
diff --git a/src/content/docs/integrations/sdk/integration/getting-started.mdx b/src/content/docs/integrations/sdk/integration/getting-started.mdx
index d007650..9b92425 100644
--- a/src/content/docs/integrations/sdk/integration/getting-started.mdx
+++ b/src/content/docs/integrations/sdk/integration/getting-started.mdx
@@ -39,16 +39,16 @@ yarn add -g @botpress/cli
 
 You can check that your installation was successful by running the following command:
 
-```bash title="bp --help"
-
+```bash
+bp --help
 ```
 
 ## 2. Log in to Botpress
 
 Next, log in to your Botpress account using the Botpress CLI. You can do this by running the following command in your terminal:
 
-```bash title="bp login"
-
+```bash
+bp login
 ```
 
 {/* TODO: add a guide on how to create a personal access token and link to it. */}
@@ -122,8 +122,8 @@ Remove these error statements for now. You can come back later to implement your
 
 Once you've made the necessary changes to your integration, you can deploy it to Botpress Cloud. Run the following command:
 
-```bash title="bp deploy"
-
+```bash
+bp deploy
 ```
 
 You'll be prompted for some information and confirmations. This integration will be deployed privately to your Workspace, and will only be visible and usable by members of your Workspace. As long as it remains private, you can update the same version by running the deploy command again. To deploy a new version, update the integration definition and run the deploy command once more.
diff --git a/src/content/docs/integrations/sdk/integration/messaging.mdx b/src/content/docs/integrations/sdk/integration/messaging.mdx
index b7f8921..479865b 100644
--- a/src/content/docs/integrations/sdk/integration/messaging.mdx
+++ b/src/content/docs/integrations/sdk/integration/messaging.mdx
@@ -11,7 +11,8 @@ One of the most powerful features of Botpress Integrations is the ability to con
 
 Here's a high-level overview of how messaging works in Botpress:
 
-```mermaid title="sequenceDiagram"
+```mermaid
+sequenceDiagram
     actor U as End User
     participant ES as External Service
     participant I as Integration
diff --git a/src/content/docs/webchat/get-started/embedding-webchat.mdx b/src/content/docs/webchat/get-started/embedding-webchat.mdx
index db3f856..67bd141 100644
--- a/src/content/docs/webchat/get-started/embedding-webchat.mdx
+++ b/src/content/docs/webchat/get-started/embedding-webchat.mdx
@@ -45,7 +45,7 @@ You will need:
   <Step title="Copy the script URL">
       Open the URL in your browser and **copy the content of the page**. It should look something like this:
 
-      ``` uri https://files.bpcontent.cloud/20XX/0X/0X/XX/XXXXXXXXXXXXXXXX-XXXXXXXX.js [expandable]
+      ```js title="https://files.bpcontent.cloud/20XX/0X/0X/XX/XXXXXXXXXXXXXXXX-XXXXXXXX.js" [expandable]
       window.botpress.init({
           "botId": "xxxxxxxxxxxxxxxxxxxxxx",
           "configuration": {
diff --git a/src/content/docs/webchat/integrations/wix.mdx b/src/content/docs/webchat/integrations/wix.mdx
index 2867b3e..d1e50f8 100644
--- a/src/content/docs/webchat/integrations/wix.mdx
+++ b/src/content/docs/webchat/integrations/wix.mdx
@@ -80,7 +80,7 @@ You can also embed your bot in an HTML div. This is useful if you want more cont
   <Step title="Copy the script URL">
     Open the URL in your browser and **copy the content of the page**. It should look something like this:
 
-    ``` uri https://files.bpcontent.cloud/20XX/0X/0X/XX/XXXXXXXXXXXXXXXX-XXXXXXXX.js [expandable]
+    ```js title="https://files.bpcontent.cloud/20XX/0X/0X/XX/XXXXXXXXXXXXXXXX-XXXXXXXX.js" [expandable]
     window.botpress.init({
         "botId": "xxxxxxxxxxxxxxxxxxxxxx",
         "configuration": {
diff --git a/src/content/docs/webchat/interact/webchat-notification.mdx b/src/content/docs/webchat/interact/webchat-notification.mdx
index 9fb9a9c..c7ad8ce 100644
--- a/src/content/docs/webchat/interact/webchat-notification.mdx
+++ b/src/content/docs/webchat/interact/webchat-notification.mdx
@@ -475,7 +475,7 @@ First, add the bubble element somewhere in your website's HTML:
 
 Then, add the following snippet to your website's JavaScript:
 
-```js expandable
+```js [expandable]
 function openNotification() {
   if (window.botpress) {
     window.botpress.open()
@@ -579,7 +579,7 @@ This handles the behaviour of the notification bubble. For example:
 
 Finally, add this CSS snippet to your website's stylesheet:
 
-```css expandable
+```css [expandable]
 :root {
   /* Change these to match your page's brand */
   --bubble-bg: #ccddfa; /* background */