chore(docs): fix Actions workflow to correctly build reference docs

Before generating the site, also gracefully handle the missing "references" sidebar config. Remove the, now generated, _reference.js sidebar config file

Author: grega

.github/workflows/deploy-docusaurus.yml

@@ -49,9 +49,14 @@ jobs:
           cache-dependency-path: 'package-lock.json' # root level, since we're using npm workspaces
 
       - name: Install dependencies
-        working-directory: ./packages/docs
         run: npm ci
 
+      - name: Build Blockly and generate reference docs
+        working-directory: ./packages/blockly
+        run: |
+          npm run package
+          npm run docs
+
       - name: Build the Docusaurus site
         working-directory: ./packages/docs
         run: npm run build

packages/blockly/scripts/gulpfiles/docs_tasks.mjs

@@ -209,7 +209,7 @@ const prependFrontmatter = function(done) {
     const description = extractDescription(content, file);
 
     let frontmatter = '---\n';
-    frontmatter += 'sidebar: referenceSidebar\n';
+    frontmatter += 'displayed_sidebar: referenceSidebar\n';
     frontmatter += 'hide_title: true\n';
     frontmatter += `title: "${title}"\n`;
     frontmatter += `description: ${JSON.stringify(description)}\n`;
@@ -292,6 +292,8 @@ const convertToMdx = function() {
       }))
       // Remove %5C (URL-encoded backslash) and literal backslash before anchor tags
       .pipe(replace(/(%5C|\\)(#[^)\s"']*)/g, '$2'))
+      // Fix breadcrumb "Home" link to point to the overview page
+      .pipe(replace(/\[Home\]\(\/reference\/index\)/g, '[Home](/reference/blockly)'))
       // Convert <code>text</code> to markdown backtick code
       .pipe(replace(/<code>([^<]*)<\/code>/g, '`$1`'))
       // Convert paragraph breaks to spaces (for table cells) and remove remaining p tags
@@ -382,8 +384,8 @@ const parseHtmlTables = function(fileContent) {
 
     if (!sectionName || sectionName === 'blockly package') continue;
 
-    // Find table rows in HTML - match links with or without ./ prefix
-    const tableRowRegex = /<tr><td>\s*\[([^\]]+)\]\((?:\/reference\/)?([^\)]+)\)/g;
+    // Match links in markdown pipe tables: |  [Name](/reference/path) | ...
+    const tableRowRegex = /\|\s*\[([^\]]+)\]\(\/reference\/([^\)]+)\)/g;
     const items = [];
 
     let match;

packages/docs/.gitignore

@@ -1,5 +1,4 @@
 # Autogenerated reference docs, do not check in
-docs/reference/*
-!docs/reference/_reference.js
+docs/reference/
 .docusaurus
 build/

packages/docs/docs/reference/_reference.js

@@ -1,7 +1,13 @@
-import { referenceSidebar } from './docs/reference/_reference';
-
 // @ts-nocheck
 
+let referenceSidebar = [];
+try {
+  ({ referenceSidebar } = await import('./docs/reference/_reference.js'));
+} catch {
+  console.warn('Reference sidebar not found — run "npm run docs" in packages/blockly to generate it.');
+}
+
+
 // This runs in Node.js - Don't use client-side code here (browser APIs, JSX...)
 
 /**