initial working example

.github/workflows/sync-docs.yml

@@ -1,77 +0,0 @@
-name: Sync docs to docs site repo
-
-on:
-  pull_request:
-    branches:
-      - main
-    paths:
-      - "docs/**"
-  workflow_dispatch:
-
-jobs:
-  config-sync:
-    name: Sync docs to docs site repo
-    runs-on: ubuntu-latest
-    permissions:
-      contents: read
-
-    steps:
-      - name: Generate a GitHub token
-        id: ghtoken
-        uses: actions/create-github-app-token@df432ceedc7162793a195dd1713ff69aefc7379e # v2.0.6
-        with:
-          app-id: ${{ secrets.GH_APP_ID }}
-          owner: slackapi
-          private-key: ${{ secrets.GH_APP_PRIVATE_KEY }}
-
-      - name: Checkout the tool repo (source)
-        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
-        with:
-          persist-credentials: false
-
-      - name: Checkout the docs site repo (destination)
-        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
-        with:
-          repository: slackapi/slackapi.github.io
-          path: "docs_repo"
-          token: ${{ steps.ghtoken.outputs.token }}
-          persist-credentials: false
-
-      - name: Update docs in docs site repo
-        run: |
-          rsync -av --delete ./docs/ "./docs_repo/content/$REPO/"
-        env:
-          REPO: ${{ github.event.repository.name }}
-
-      - name: Install dependencies
-        run: |
-          cd docs_repo
-          npm ci
-
-      - name: Build Docusaurus site
-        run: |
-          cd docs_repo
-          npm run build
-
-      - name: Create a pull request
-        if: ${{ github.event.pull_request.merged || github.event_name == 'workflow_dispatch' }}
-        id: site-pr
-        uses: peter-evans/create-pull-request@271a8d0340265f705b14b6d32b9829c1cb33d45e # v7.0.8
-        with:
-          token: ${{ steps.ghtoken.outputs.token }}
-          title: "From ${{ github.event.repository.name }}: ${{ github.event.pull_request.title || 'manual docs sync' }}"
-          body: "${{ github.event.pull_request.body }}"
-          author: "slackapi[bot] <186980925+slackapi[bot]@users.noreply.github.com>"
-          committer: "slackapi[bot] <186980925+slackapi[bot]@users.noreply.github.com>"
-          commit-message: "Sync docs from ${{ github.event.repository.name }} to docs site repo"
-          base: "main"
-          branch: "docs-sync-${{ github.event.repository.name }}-${{ github.sha }}"
-          labels: docs
-          path: "./docs_repo"
-
-      - name: Output the pull request link
-        if: ${{ steps.site-pr.outputs.pull-request-url }}
-        run: |
-          echo "Pull request created: $URL" >> $GITHUB_STEP_SUMMARY
-        env:
-          URL: ${{ steps.site-pr.outputs.pull-request-url }}

.gitignore

@@ -9,3 +9,5 @@ node_modules
 
 # Testing remnants
 coverage
+
+.docusaurus-preview/

package.json

@@ -10,7 +10,8 @@
     "dev": "act public --eventpath .github/resources/.actions/event.json --secret-file .github/resources/.env --platform ubuntu-latest=node:20-buster --container-architecture linux/amd64",
     "lint:fix": "biome check --write",
     "lint": "biome check",
-    "test": "c8 mocha test/*.spec.js"
+    "test": "c8 mocha test/*.spec.js",
+    "preview-docs": "node scripts/preview-docs.js"
   },
   "repository": {
     "type": "git",

scripts/preview-docs.js

@@ -0,0 +1,103 @@
+#!/usr/bin/env node
+
+import { execSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const REPO_ROOT = path.resolve(__dirname, '..');
+const DOCS_SITE_REPO = 'slackapi/slackapi.github.io';
+const TEMP_DIR = path.join(REPO_ROOT, '.docusaurus-preview');
+
+function executeCommand(command, options = {}) {
+  try {
+    execSync(command, { stdio: 'inherit', ...options });
+  } catch (error) {
+    console.error('Failed to execute command:', command);
+    console.error(error.message);
+    process.exit(1);
+  }
+}
+
+function cleanupTempDir() {
+  if (fs.existsSync(TEMP_DIR)) {
+    console.log('Cleaning up existing preview directory...');
+    fs.rmSync(TEMP_DIR, { recursive: true, force: true });
+  }
+}
+
+function setupPreviewEnvironment() {
+  cleanupTempDir();
+  
+  console.log('Creating temporary directory...');
+  fs.mkdirSync(TEMP_DIR);
+
+  console.log('Fetching latest documentation site from main branch...');
+  executeCommand(`git clone --depth 1 https://github.com/${DOCS_SITE_REPO}.git .`, { cwd: TEMP_DIR });
+
+  const docsDir = path.join(TEMP_DIR, 'content', 'slack-github-action');
+  console.log('\nSetting up documentation:');
+  console.log('Source directory:', path.join(REPO_ROOT, 'docs'));
+  console.log('Target directory:', docsDir);
+
+  if (!fs.existsSync(docsDir)) {
+    console.log('Creating target directory...');
+    fs.mkdirSync(docsDir, { recursive: true });
+  }
+
+  console.log('\nSetting up documentation hardlinks...');
+  for (const file of fs.readdirSync(path.join(REPO_ROOT, 'docs'))) {
+    const sourcePath = path.join(REPO_ROOT, 'docs', file);
+    const targetPath = path.join(docsDir, file);
+    console.log(`\nProcessing ${file}:`);
+    console.log('  From:', sourcePath);
+    console.log('  To:', targetPath);
+    
+    // Remove existing file/link if it exists
+    if (fs.existsSync(targetPath)) {
+      console.log('  Removing existing file/link');
+      fs.rmSync(targetPath, { recursive: true, force: true });
+    }
+    
+    // For directories, we need to copy them
+    if (fs.statSync(sourcePath).isDirectory()) {
+      console.log('  Copying directory...');
+      fs.cpSync(sourcePath, targetPath, { recursive: true });
+    } else {
+      // For files, create hardlinks
+      console.log('  Creating hardlink...');
+      fs.linkSync(sourcePath, targetPath);
+    }
+  }
+
+  // Verify links
+  console.log('\nVerifying files:');
+  for (const file of fs.readdirSync(docsDir)) {
+    try {
+      const filePath = path.join(docsDir, file);
+      const stats = fs.statSync(filePath);
+      console.log(`${file} -> ${stats.isDirectory() ? 'Directory' : 'File'} (${stats.nlink} links)`);
+    } catch (error) {
+      console.error(`Error with file ${file}:`, error.message);
+    }
+  }
+}
+
+function startDocusaurusServer() {
+  console.log('Starting Docusaurus development server...');
+  executeCommand('npm install', { cwd: TEMP_DIR });
+  executeCommand('npm start', { cwd: TEMP_DIR });
+}
+
+async function main() {
+  console.log('Setting up documentation preview environment...');
+  setupPreviewEnvironment();
+  startDocusaurusServer();
+}
+
+main().catch(error => {
+  console.error('Failed to set up documentation preview:', error);
+  process.exit(1);
+});