ci: add DevPortal publishing pattern (#155)

* ci: add DevPortal publishing pattern

- Add static MDX generation from example source files
- Migrate docs from npm to pnpm
- Extract sidebar to sidebar.config.json
- Add publish-devportal-docs workflow
- Remove typeDocSidebarGroup import, use sidebar.config.json
- Simplify content.config.ts (remove examples collection)
- Delete dynamic example pages

* fix(ci): added npm i at root

* fix: check docs step and npm audit failure

* chore: addressed PR comments

Author: lempira

.github/workflows/pr.yml

@@ -28,19 +28,23 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Clone repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
         with:
           fetch-depth: 1
       - name: Setup Node.js
-        uses: actions/setup-node@v4
+        uses: actions/setup-node@v6
         with:
           node-version: 20.x
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          package_json_file: docs/package.json
       - name: Install root dependencies
         run: npm ci
       - name: Install docs dependencies
-        run: npm ci --prefix docs
+        run: pnpm install --frozen-lockfile --dir docs
       - name: Verify documentation builds
-        run: npm run docs:build
+        run: pnpm --dir docs build
   verify_examples:
     runs-on: ubuntu-latest
     steps:

.github/workflows/publish-devportal-docs.yml

@@ -0,0 +1,30 @@
+name: Publish DevPortal Docs
+
+on:
+  workflow_dispatch:
+  push:
+    branches: [ci/add-publish-to-devportal-workflow]
+    tags: ['v*']
+
+permissions:
+  contents: write
+
+jobs:
+  publish-docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-node@v6
+        with:
+          node-version: 22
+      - uses: pnpm/action-setup@v4
+        with:
+          package_json_file: docs/package.json
+      - name: Install root dependencies
+        run: npm ci
+      - name: Build package
+        run: npm run build
+      - name: Publish DevPortal Docs
+        uses: algorandfoundation/devportal/.github/actions/publish-devportal-docs@ci/update-publish-devportal-docs-workflow
+        with:
+          docs-dir: docs

.nsprc

@@ -4,4 +4,4 @@
     "notes": "@isaacs/brace-expansion via npm in @semantic-release/npm - bundled inside npm, waiting for upstream fix",
     "expiry": "2026-06-01"
   }
-}
+}

docs/.gitignore

@@ -4,6 +4,8 @@ dist/
 .astro/
 # generated API docs (built by starlight-typedoc)
 src/content/docs/api/
+# generated example docs (built by generate-examples-mdx.ts)
+src/content/docs/examples/
 
 # dependencies
 node_modules/

docs/astro.config.mjs

@@ -1,7 +1,8 @@
 // @ts-check
 import { defineConfig } from 'astro/config';
 import starlight from '@astrojs/starlight';
-import starlightTypeDoc, { typeDocSidebarGroup } from 'starlight-typedoc';
+import starlightTypeDoc from 'starlight-typedoc';
+import sidebar from './sidebar.config.json';
 import remarkGithubAlerts from 'remark-github-alerts';
 
 // https://astro.build/config
@@ -36,47 +37,11 @@ export default defineConfig({
           typeDoc: {
             excludeReferences: true,
             gitRevision: 'main',
+            entryFileName: 'index',
           },
         }),
       ],
-      sidebar: [
-        { label: 'Home', link: '/' },
-        {
-          label: 'Getting Started',
-          items: [{ label: 'Quick Start', slug: 'tutorials/quick-start' }],
-        },
-        {
-          label: 'Guides',
-          items: [
-            { slug: 'guide/subscriber' },
-            { slug: 'guide/subscriptions' },
-          ],
-        },
-        {
-          label: 'Concepts',
-          items: [
-            { slug: 'concepts/sync-behaviour' },
-            { slug: 'concepts/low-latency' },
-            { slug: 'concepts/watermarking' },
-            { slug: 'concepts/filtering' },
-            { slug: 'concepts/arc28-events' },
-            { slug: 'concepts/emit-arc28-events' },
-            { slug: 'concepts/inner-transactions' },
-            { slug: 'concepts/state-proofs' },
-            { slug: 'concepts/fast-catchup' },
-          ],
-        },
-        {
-          label: 'Examples',
-          items: [{ label: 'Overview', link: '/examples/' }],
-        },
-        {
-          label: 'Migration Guides',
-          collapsed: true,
-          autogenerate: { directory: 'migration' },
-        },
-        typeDocSidebarGroup,
-      ],
+      sidebar,
     }),
   ],
 });