ci: enhance docs workflow

.github/workflows/publish-docs.yaml

@@ -1,49 +1,81 @@
 name: Deploy to GitHub Pages
 
 on:
+  workflow_dispatch:
   push:
-    branches:
-      - main
+    paths:
+      - 'docs/**'
+      - '.github/workflows/publish-docs.yaml'
+  pull_request:
+    paths:
+      - 'docs/**'
+      - '.github/workflows/publish-docs.yaml'
 
 permissions:
   contents: read
   pages: write
   id-token: write
+  pull-requests: write
 
+# Allow only one concurrent deployment
 concurrency:
   group: "pages"
-  cancel-in-progress: false
+  cancel-in-progress: true
 
 jobs:
-  # Single deploy job since we're just deploying
-  deploy:
+  build-and-deploy:
+    runs-on: ubuntu-latest
     environment:
-      name: github-pages
+      name: ${{ github.ref == 'refs/heads/main' && 'github-pages' || 'preview' }}
       url: ${{ steps.deployment.outputs.page_url }}
-    runs-on: ubuntu-latest
     steps:
-      - name: Checkout
-        uses: actions/checkout@v3
+      - uses: actions/checkout@v4
+
       - uses: actions/setup-node@v3
         with:
           node-version: 18
-          cache: yarn
-          cache-dependency-path: 'docs/package-lock.json'
+          cache: npm
+          cache-dependency-path: docs/package-lock.json
 
-      - name: Install dependencies
+      - name: Build docs
         working-directory: docs
-        run: yarn install --frozen-lockfile
-      - name: Build website
-        working-directory: docs
-        run: yarn build
+        run: |
+          npm ci
+          npm run build
 
       - name: Setup Pages
-        uses: actions/configure-pages@v3
-      - name: Upload artifact
+        uses: actions/configure-pages@v4
+
+      - name: Upload Pages artifact
         uses: actions/upload-pages-artifact@v3
         with:
-          # Upload entire repository
-          path: 'docs/build'
-      - name: Deploy to GitHub Pages
+          path: docs/build
+          name: github-pages
+
+      - name: Deploy
         id: deployment
-        uses: actions/deploy-pages@v2
+        if: |
+          github.ref == 'refs/heads/main' ||
+          github.ref == 'refs/heads/docs-test' ||
+          startsWith(github.ref, 'refs/heads/docs/')
+        uses: actions/deploy-pages@v4
+        with:
+          artifact_name: github-pages
+          preview: ${{ github.ref != 'refs/heads/main' }}
+
+      - name: Comment PR
+        if: |
+          github.event_name == 'pull_request' &&
+          (github.ref == 'refs/heads/docs-test' ||
+           startsWith(github.ref, 'refs/heads/docs/'))
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const url = '${{ steps.deployment.outputs.page_url }}';
+            const message = `📚 Documentation preview available at: ${url}`;
+            github.rest.issues.createComment({
+              issue_number: context.issue.number,
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              body: message
+            });

docs/docs/modules/agents/executor/index.mdx

@@ -5,6 +5,7 @@ sidebar_position: 2
 
 import CodeBlock from "@theme/CodeBlock";
 import Example from "@examples/mrkl-agent-example/mrkl_agent.go";
+import DocCardList from "@theme/DocCardList";
 
 # Agent Executors
 
@@ -18,5 +19,4 @@ To make agents more powerful we need to make them iterative, ie. call the model
 An example that initialize a MRKL (Modular Reasoning, Knowledge and Language, pronounced "miracle") agent executor.
 <CodeBlock language="go">{Example}</CodeBlock>
 
-import DocCardList from "@theme/DocCardList";
 <DocCardList />

docs/docusaurus.config.js

@@ -5,6 +5,8 @@
 // eslint-disable-next-line import/no-extraneous-dependencies
 const { ProvidePlugin } = require("webpack");
 const path = require("path");
+const lightCodeTheme = require('prism-react-renderer').themes.github;
+const darkCodeTheme = require('prism-react-renderer').themes.dracula;
 
 const examplesPath = path.resolve(__dirname, "..", "examples");
 
@@ -124,8 +126,8 @@ const config = {
     /** @type {import('@docusaurus/preset-classic').ThemeConfig} */
     ({
       prism: {
-        theme: require("prism-react-renderer/themes/vsLight"),
-        darkTheme: require("prism-react-renderer/themes/vsDark"),
+        theme: lightCodeTheme,
+        darkTheme: darkCodeTheme,
       },
       image: "img/parrot-chainlink-icon.png",
       navbar: {