feat: upload docs to the dfinity/icp-js-sdk-docs repo

.github/workflows/publish.yml

@@ -8,18 +8,19 @@ on:
       - closed
 
 jobs:
-  publish:
+  publish-packages:
     if: github.event.pull_request.merged == true && startsWith(github.event.pull_request.head.ref, 'release/')
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
 
       - name: Extract version from branch name
         run: |
           BRANCH="${{ github.event.pull_request.head.ref }}"
           VERSION="${BRANCH#release/}"
           echo "BRANCH=$BRANCH" >> $GITHUB_ENV
           echo "VERSION_TAG=v$VERSION" >> $GITHUB_ENV
+
       - name: Mark as Latest Release in GitHub Releases
         env:
           GH_TOKEN: '${{ secrets.GITHUB_TOKEN }}'
@@ -31,15 +32,82 @@ jobs:
         with:
           node_version_file: '.nvmrc'
 
-      - run: pnpm build
+      - run: pnpm build:packages
+
       - run: pnpm publish:packages
         env:
           NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
 
-      - name: Deploy Docs to Juno satellite
-        uses: junobuild/juno-action@main
+  publish-docs:
+    needs: publish-packages
+    runs-on: ubuntu-latest
+    steps:
+      - name: Create GitHub App Token
+        uses: actions/create-github-app-token@df432ceedc7162793a195dd1713ff69aefc7379e # v2.0.6
+        id: generate_token
         with:
-          args: deploy --mode production --immediate
+          app-id: ${{ vars.PR_AUTOMATION_BOT_PUBLIC_APP_ID }}
+          private-key: ${{ secrets.PR_AUTOMATION_BOT_PUBLIC_PRIVATE_KEY }}
+          owner: ${{ github.repository_owner }}
+          repositories: icp-js-sdk-docs
+
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+
+      - name: Setup PNPM
+        uses: dfinity/ci-tools/actions/setup-pnpm@main
+        with:
+          node_version_file: '.nvmrc'
+
+      - uses: dfinity/ci-tools/actions/extract-version@main
+        id: extract-version
+        with:
+          file: 'package.json'
+
+      - name: Prepare version
+        id: ver
+        run: |
+          echo "major_minor_version=v${{ steps.extract-version.outputs.major }}.${{ steps.extract-version.outputs.minor }}" >> $GITHUB_OUTPUT
+          echo "major_minor_patch_version=v${{ steps.extract-version.outputs.major }}.${{ steps.extract-version.outputs.minor }}.${{ steps.extract-version.outputs.patch }}" >> $GITHUB_OUTPUT
+
+      - name: Build docs for version ${{ steps.ver.outputs.major_minor_version }}
+        working-directory: docs
+        env:
+          DOCS_VERSION: ${{ steps.ver.outputs.major_minor_version }}
+          DOCS_VERSIONS_DROPDOWN_TITLE_VERSION: ${{ steps.ver.outputs.major_minor_patch_version }}
+        run: pnpm build --outDir dist/${{ steps.ver.outputs.major_minor_version }}
+
+      - name: Build docs for version latest
+        working-directory: docs
         env:
-          JUNO_TOKEN: ${{ secrets.JUNO_TOKEN }}
-          PROJECT_PATH: docs
+          DOCS_VERSION: latest
+          DOCS_VERSIONS_DROPDOWN_TITLE_VERSION: ${{ steps.ver.outputs.major_minor_patch_version }}
+        run: pnpm build --outDir dist/latest
+
+      - name: Checkout icp-pages branch
+        uses: actions/checkout@v4
+        with:
+          ref: icp-pages
+          path: icp-pages
+
+      - name: Assemble docs
+        uses: dfinity/ci-tools/actions/assemble-docs@main
+        with:
+          assets_dir: 'docs/dist/${{ steps.ver.outputs.major_minor_version }}'
+          version: ${{ steps.ver.outputs.major_minor_version }}
+          target_dir: 'icp-pages'
+          version_label: ${{ steps.ver.outputs.major_minor_version }}
+
+      - name: Assemble docs
+        uses: dfinity/ci-tools/actions/assemble-docs@main
+        with:
+          assets_dir: 'docs/dist/latest'
+          version: 'latest'
+          target_dir: 'icp-pages'
+          version_label: 'Latest (${{ steps.ver.outputs.major_minor_patch_version }})'
+
+      - name: Submit Documentation
+        uses: dfinity/ci-tools/actions/submit-docs@main
+        with:
+          destination_repo: 'dfinity/icp-js-sdk-docs'
+          token: ${{ steps.generate_token.outputs.token }}
+          target_dir: 'icp-pages'

docs/astro.config.mjs

@@ -5,11 +5,18 @@ import { additionalFilesPlugin } from '@dfinity/starlight/additional-files';
 import { markdownUrlsPlugin } from '@dfinity/starlight/markdown-urls';
 import { dfinityStarlightTheme } from '@dfinity/starlight/theme';
 import { libsPlugin } from '@dfinity/starlight/libs';
+import { versionedSidebarPlugin } from '@dfinity/starlight/versioned-sidebar';
+
+const BASE_DOCS_PATH = '/core';
+const docsVersion = process.env.DOCS_VERSION ?? 'local';
+
+const UPGRADE_BANNER_CONTENT =
+  'Still using <code>@dfinity/agent</code>? Migrate to <a href="/core/latest/upgrading/v4">@icp-sdk/core</a>!';
 
 // https://astro.build/config
 export default defineConfig({
   site: 'https://js.icp.build/',
-  base: '/core/',
+  base: `${BASE_DOCS_PATH}/${docsVersion}/`,
   image: {
     service: passthroughImageService(),
   },
@@ -26,7 +33,14 @@ export default defineConfig({
           typeDoc: {
             exclude: ['../packages/core', '../packages/migrate'],
           },
-          frontmatter: { editUrl: false, next: true, prev: true },
+          frontmatter: {
+            editUrl: false,
+            next: true,
+            prev: true,
+            banner: {
+              content: UPGRADE_BANNER_CONTENT,
+            },
+          },
         }),
         additionalFilesPlugin({
           additionalFiles: [
@@ -38,10 +52,16 @@ export default defineConfig({
                 editUrl: false,
                 next: false,
                 prev: false,
+                banner: {
+                  content: UPGRADE_BANNER_CONTENT,
+                },
               },
             },
           ],
         }),
+        versionedSidebarPlugin({
+          versionsJsonPath: `${BASE_DOCS_PATH}/versions.json`,
+        }),
       ],
       sidebar: [
         {

docs/plugins/package.json

@@ -43,6 +43,9 @@
     "./additional-files": "./src/additional-files.ts",
     "./libs": "./src/libs.ts",
     "./markdown-urls": "./src/markdown-urls.ts",
-    "./theme": "./src/theme.ts"
+    "./theme": "./src/theme.ts",
+    "./versioned-sidebar": "./src/versioned-sidebar/index.ts",
+    "./versioned-sidebar/components/VersionedSidebar.astro": "./src/versioned-sidebar/components/VersionedSidebar.astro",
+    "./versioned-sidebar/components/VersionDropdown.astro": "./src/versioned-sidebar/components/VersionDropdown.astro"
   }
 }

docs/plugins/src/versioned-sidebar/components/VersionDropdown.astro

@@ -0,0 +1,100 @@
+---
+const IS_DEV = import.meta.env.DEV;
+const BASE_URL = import.meta.env.BASE_URL;
+const DOCS_VERSIONS_DROPDOWN_TITLE_VERSION = import.meta.env.DOCS_VERSIONS_DROPDOWN_TITLE_VERSION;
+---
+
+<div>
+  <label for="sidebar-version-select" class="sidebar-version-select-label">
+    Version{DOCS_VERSIONS_DROPDOWN_TITLE_VERSION ? ` (${DOCS_VERSIONS_DROPDOWN_TITLE_VERSION})` : ''}
+  </label>
+  <select id="sidebar-version-select" aria-label="Select documentation version"></select>
+</div>
+
+<script define:vars={{ IS_DEV, BASE_URL }} is:inline>
+    const BASE_URL_NO_TRAILING_SLASH = BASE_URL.replace(/\/$/, '');
+
+    function removeBaseUrlFromPath(pathname) {
+        const relative = pathname.startsWith(BASE_URL)
+            ? pathname.slice(BASE_URL.length)
+            : pathname.startsWith(BASE_URL_NO_TRAILING_SLASH)
+                ? pathname.slice(BASE_URL_NO_TRAILING_SLASH.length)
+                : pathname;
+
+        return relative.startsWith('/') ? relative.slice(1) : relative;
+    }
+
+    async function initVersionDropdown() {
+        const select = document.getElementById('sidebar-version-select');
+        if (!select || !(select instanceof HTMLSelectElement)) {
+            console.error('No select element found');
+            return;
+        }
+
+        let versions = [];
+        if (!IS_DEV) {
+            try {
+                const versionsUrl = document.getElementsByName('versions-json-path')[0]?.getAttribute('content');
+                if (!versionsUrl) {
+                    console.error('No versions.json path found');
+                    return;
+                }
+                const res = await fetch(versionsUrl, { cache: 'no-store' });
+                if (res.ok) {
+                    const data = await res.json();
+                    if (Array.isArray(data)) {
+                        versions = data;
+                    }
+                }
+            } catch (e) {
+                console.error('Error fetching versions.json', e);
+            }
+        }
+
+        const currentVersion = (BASE_URL.replace(/\/$/, '').split('/').pop() || '').toLowerCase();
+        const { pathname, search, hash } = window.location;
+
+        // If the current URL's base segment doesn't match any known versions,
+        // add a synthetic option so users can see/select the current build.
+        if (!versions.some(v => v.path.toLowerCase() === currentVersion)) {
+            versions.unshift({ path: currentVersion, label: currentVersion });
+        }
+
+        select.innerHTML = '';
+        for (const v of versions) {
+            const newBase = BASE_URL.replace(/([^/]+)\/$/, `${v.path}/`);
+            const relative = removeBaseUrlFromPath(pathname);
+            const href = newBase + relative + search + hash;
+            const opt = document.createElement('option');
+            opt.value = href;
+            opt.textContent = v.label;
+            if (v.path.toLowerCase() === currentVersion) {
+                opt.selected = true;
+            }
+            select.appendChild(opt);
+        }
+
+        select.addEventListener('change', () => {
+            const href = select.value;
+            const current = pathname + search + hash;
+            if (href && href !== current) {
+                window.location.href = href;
+            }
+        });
+    };
+
+    initVersionDropdown();
+</script>
+
+<style>
+    #sidebar-version-select {
+        width: 100%;
+        padding: 0.25rem 0.5rem;
+        border-radius: 0.375rem;
+    }
+    .sidebar-version-select-label {
+        display: block;
+        font-size: var(--sl-text-sm);
+        cursor: pointer;
+    }
+</style>

docs/plugins/src/versioned-sidebar/components/VersionedSidebar.astro

@@ -0,0 +1,18 @@
+---
+import MobileMenuFooter from '@astrojs/starlight/components/MobileMenuFooter.astro';
+import SidebarPersister from '@astrojs/starlight/components/SidebarPersister.astro';
+import SidebarSublist from '@astrojs/starlight/components/SidebarSublist.astro';
+import VersionDropdown from './VersionDropdown.astro';
+
+const { sidebar } = Astro.locals.starlightRoute;
+---
+
+<VersionDropdown />
+
+<SidebarPersister>
+	<SidebarSublist sublist={sidebar} />
+</SidebarPersister>
+
+<div class="md:sl-hidden">
+	<MobileMenuFooter />
+</div>

docs/plugins/src/versioned-sidebar/index.ts

@@ -0,0 +1,55 @@
+import type { StarlightPlugin } from '@astrojs/starlight/types';
+
+/**
+ * Options for the VersionsPlugin.
+ */
+interface VersionedSidebarPluginOptions {
+  /**
+   * The path at which the `versions.json` file is served in production.
+   */
+  versionsJsonPath: string;
+}
+
+/**
+ * You can set the `DOCS_VERSIONS_DROPDOWN_TITLE_VERSION` environment variable to show a version above the versions dropdown.
+ *
+ * @example
+ * ```bash
+ * DOCS_VERSIONS_DROPDOWN_TITLE_VERSION=v3.2.1 pnpm build
+ * ```
+ *
+ * This will result in:
+ * ```html
+ * <div>
+ *   <label for="sidebar-version-select">Version (v3.2.1)</label>
+ *   <select id="sidebar-version-select" aria-label="Select documentation version">
+ *     <!-- options from {opts.versionsJsonPath} file -->
+ *   </select>
+ * </div>
+ * ```
+ */
+export function versionedSidebarPlugin(opts: VersionedSidebarPluginOptions): StarlightPlugin {
+  return {
+    name: 'versions-starlight-plugin',
+    hooks: {
+      'config:setup': ctx => {
+        ctx.updateConfig({
+          head: [
+            ...(ctx.config.head ?? []),
+            {
+              tag: 'meta',
+              attrs: {
+                name: 'versions-json-path',
+                content: opts.versionsJsonPath,
+              },
+            },
+          ],
+          components: {
+            ...ctx.config.components,
+            Sidebar: '@dfinity/starlight/versioned-sidebar/components/VersionedSidebar.astro',
+          },
+        });
+      },
+    },
+  };
+}

docs/plugins/tsconfig.json

@@ -1,3 +1,6 @@
 {
-  "extends": "astro/tsconfigs/strictest"
+  "extends": "astro/tsconfigs/strictest",
+  "compilerOptions": {
+    "types": ["@astrojs/starlight/locals"]
+  }
 }

docs/src/content/docs/upgrading/v3.md

@@ -1,6 +1,11 @@
 ---
-title: Release notes for v3.0.0
-description: Release notes for the ICP JavaScript SDK v3.0.0.
+title: Upgrading to v3
+description: Upgrade your project to the v3 of the ICP JavaScript SDK.
+sidebar:
+  label: v3
+  order: 2
+banner:
+  content: Still using <code>@dfinity/agent</code>? Migrate to <a href="/core/latest/upgrading/v4">@icp-sdk/core</a>!
 ---
 
 This release marks a major update to the ICP JavaScript SDK, introducing several breaking changes, new features, and improvements. This guide is intended to help developers upgrade their projects to the latest version. Among the key improvements, this release eliminates Buffer and similar dependencies, significantly [reducing bundle size](#bundle-size) and improving performance across all packages.