chore(docs): change path from /js/reference/ to /reference/

Update docs build script to reflect this, and fix some mdx generation errors

Add .gitignore to docs/reference/ to keep generated md/mdx out of version control

Add Docusaurus redirect config for /reference/js/ -> /reference/

Author: grega

packages/blockly/scripts/gulpfiles/docs_tasks.mjs

@@ -5,8 +5,8 @@ import * as gulp from 'gulp';
 import replace from 'gulp-replace';
 import rename from 'gulp-rename';
 
-const DOCS_DIR = 'docs/docs/reference/js';
-const REFERENCE_SIDEBAR_DIR = 'docs/docs/reference';
+const DOCS_DIR = '../docs/docs/reference';
+const REFERENCE_SIDEBAR_DIR = DOCS_DIR;
 
 /**
  * Run API Extractor to generate the intermediate json file.
@@ -31,9 +31,7 @@ const removeRenames = function() {
  */
 const generateDocs = function(done) {
   if (!fs.existsSync(DOCS_DIR)) {
-    // Create the directory if it doesn't exist.
-    // If it already exists, the contents will be deleted by api-documenter.
-    fs.mkdirSync(DOCS_DIR);
+    fs.mkdirSync(DOCS_DIR, {recursive: true});
   }
   execSync(
       `api-documenter markdown --input-folder temp --output-folder ${DOCS_DIR}`,
@@ -237,83 +235,35 @@ const fixMdxIssues = function(done) {
     const filePath = path.join(DOCS_DIR, file);
     let content = fs.readFileSync(filePath, 'utf8');
 
-    // Split content into lines for line-by-line processing
     const lines = content.split('\n');
     let inCodeBlock = false;
-    let inTableCell = false;
 
     for (let i = 0; i < lines.length; i++) {
-      const line = lines[i];
-      
-      // Track code blocks
-      if (line.trim().startsWith('```')) {
+      if (lines[i].trim().startsWith('```')) {
         inCodeBlock = !inCodeBlock;
         continue;
       }
-      
-      // Skip processing inside code blocks
       if (inCodeBlock) continue;
 
-      // Track if we're entering a table cell (opening tag without closing on same line)
-      if (line.includes('<td>') && !line.includes('</td>')) {
-        inTableCell = true;
-      }
-      
-      // Remove empty MDX comments
-      lines[i] = lines[i].replace(/\{\/\*\s*\*\/\}/g, '');
+      // Remove all MDX comments (artifacts from HTML comment conversion)
+      lines[i] = lines[i].replace(/\{\/\*[\s\S]*?\*\/\}/g, '');
 
       // Remove unnecessary markdown escapes for underscores and brackets
-      // These are not needed in MDX and can cause display issues
       lines[i] = lines[i].replace(/\\_/g, '_');
       lines[i] = lines[i].replace(/\\\[/g, '[');
       lines[i] = lines[i].replace(/\\\]/g, ']');
 
-      // Escape standalone HTML tags (not in tables or code)
-      if (!lines[i].includes('<table>') && !lines[i].includes('</table>') && 
-          !lines[i].includes('<thead>') && !lines[i].includes('<tbody>') &&
-          !lines[i].includes('<tr>') && !lines[i].includes('<th>') && !lines[i].includes('<td>')) {
-        lines[i] = lines[i].replace(/<([a-z]+)>/g, '`<$1>`');
+      // Escape HTML tags (with or without attributes) outside of table markup
+      const isTableMarkup = /^<\/?(table|thead|tbody|tr|th|td)[\s>]/.test(lines[i].trim());
+      if (!isTableMarkup) {
+        lines[i] = lines[i].replace(/<([a-z]+)(\s[^>]*)?>/g, '`$&`');
+        lines[i] = lines[i].replace(/<\/([a-z]+)>/g, '`$&`');
       }
 
-      // Handle curly braces ANYWHERE (in tables or outside)
-      // If the line has curly braces with type-like content, wrap in backticks
-      const trimmed = lines[i].trim();
-      if (trimmed && (trimmed.includes('{') || trimmed.includes('\\{')) && 
-          (trimmed.includes('}') || trimmed.includes('\\}'))) {
-        
-        // Skip if it's an MDX comment, table/code tag line, or already in backticks
-        if (trimmed.includes('{/*') || trimmed.includes('*/}') ||
-            trimmed.includes('<td>') || trimmed.includes('</td>') || 
-            trimmed.includes('<table>') || trimmed.includes('<tr>') ||
-            trimmed.startsWith('```') || trimmed.startsWith('`') && trimmed.endsWith('`')) {
-          // Process table cell content specifically
-          if (inTableCell && !lines[i].includes('<td>') && !lines[i].includes('</td>')) {
-            // Remove any existing escaping first
-            let cleaned = trimmed.replace(/\\\{/g, '{').replace(/\\\}/g, '}');
-            // Only remove trailing semicolons for nested object type patterns
-            if (cleaned.match(/\{\s*\[.*\]:\s*\{.*\};\s*\}/)) {
-              cleaned = cleaned.replace(/;\s*}/g, ' }');
-            }
-            if (!cleaned.startsWith('`') || !cleaned.endsWith('`')) {
-              lines[i] = lines[i].replace(trimmed, '`' + cleaned + '`');
-            }
-          }
-        } else {
-          // Not in a tag line - wrap curly brace content in backticks
-          let cleaned = trimmed.replace(/\\\{/g, '{').replace(/\\\}/g, '}');
-          // Remove trailing semicolons for type patterns
-          if (cleaned.match(/\{\s*\[.*\]:\s*\{.*\};\s*\}/)) {
-            cleaned = cleaned.replace(/;\s*}/g, ' }');
-          }
-          // Wrap in backticks
-          lines[i] = lines[i].replace(trimmed, '`' + cleaned + '`');
-        }
-      }
-      
-      // Track if we're exiting a table cell (must be after processing)
-      if (line.includes('</td>')) {
-        inTableCell = false;
-      }
+      // Escape curly braces so MDX doesn't parse them as JSX expressions.
+      // First undo any backslash-escaping from api-documenter, then re-escape.
+      lines[i] = lines[i].replace(/\\\{/g, '{').replace(/\\\}/g, '}');
+      lines[i] = lines[i].replace(/\{/g, '\\{').replace(/\}/g, '\\}');
     }
 
     content = lines.join('\n');
@@ -329,8 +279,8 @@ const convertToMdx = function() {
       .pipe(replace(/<!--\s*([\s\S]*?)\s*-->/g, '{/* $1 */}'))
       // Fix malformed markdown links: [text][/path](https://developers.google.com/path) -> [text](/path)
       .pipe(replace(/\[([^\]]+)\]\[([^\]]+)\]\(https:\/\/developers\.google\.com([^)]+)\)/g, '[$1]($2)'))
-      // Fix all internal links: remove .md extension and convert ./filename to /reference/js/filename
-      .pipe(replace(/\]\(\.\/([^)]+)\.md\)/g, '](/reference/js/$1)'))
+      // Fix all internal links: remove .md extension and convert ./filename to /reference/filename
+      .pipe(replace(/\]\(\.\/([^)]+)\.md\)/g, '](/reference/$1)'))
       // Replace developers.google.com links with relative paths
       .pipe(replace(/https:\/\/developers\.google\.com(\/blockly\/[^)\s"']+)/g, '$1'))
       // Replace developers.devsite.google.com links with relative paths
@@ -342,6 +292,11 @@ const convertToMdx = function() {
       }))
       // Remove %5C (URL-encoded backslash) and literal backslash before anchor tags
       .pipe(replace(/(%5C|\\)(#[^)\s"']*)/g, '$2'))
+      // 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
+      .pipe(replace(/<\/p><p>/g, ' '))
+      .pipe(replace(/<\/?p>/g, ''))
       .pipe(rename({ extname: '.mdx' }))
       .pipe(gulp.dest(DOCS_DIR));
 }
@@ -428,7 +383,7 @@ 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\/js\/)?([^\)]+)\)/g;
+    const tableRowRegex = /<tr><td>\s*\[([^\]]+)\]\((?:\/reference\/)?([^\)]+)\)/g;
     const items = [];
 
     let match;
@@ -465,7 +420,7 @@ const createReferenceSidebar = function(done) {
   sidebarContent += '  {\n';
   sidebarContent += '    "type": "doc",\n';
   sidebarContent += '    "label": "Overview",\n';
-  sidebarContent += '    "id": "reference/js/blockly"\n';
+  sidebarContent += '    "id": "reference/blockly"\n';
   sidebarContent += '  },\n';
 
   // Process each section (Classes, Interfaces, Functions, etc.)
@@ -494,7 +449,7 @@ const createReferenceSidebar = function(done) {
         sidebarContent += `        "label": "${itemName}",\n`;
         sidebarContent += '        "link": {\n';
         sidebarContent += '          "type": "doc",\n';
-        sidebarContent += `          "id": "reference/js/${itemPath}"\n`;
+        sidebarContent += `          "id": "reference/${itemPath}"\n`;
         sidebarContent += '        },\n';
         sidebarContent += '        "items": [\n';
 
@@ -504,7 +459,7 @@ const createReferenceSidebar = function(done) {
           sidebarContent += '          {\n';
           sidebarContent += '            "type": "doc",\n';
           sidebarContent += `            "label": "${subPage}",\n`;
-          sidebarContent += `            "id": "reference/js/${subPage}"\n`;
+          sidebarContent += `            "id": "reference/${subPage}"\n`;
           sidebarContent += '          },\n';
         }
 
@@ -520,7 +475,7 @@ const createReferenceSidebar = function(done) {
         sidebarContent += '      {\n';
         sidebarContent += '        "type": "doc",\n';
         sidebarContent += `        "label": "${itemName}",\n`;
-        sidebarContent += `        "id": "reference/js/${itemPath}"\n`;
+        sidebarContent += `        "id": "reference/${itemPath}"\n`;
         sidebarContent += '      },\n';
       }
     }

packages/docs/.gitignore

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

packages/docs/README.md

@@ -2,7 +2,6 @@
 
 This website is built using [Docusaurus](https://docusaurus.io/), a modern static website generator.
 
-
 ## Installation
 
 Run `npm install` at the root of the blockly repo, then all other commands from the `packages/docs` directory.
@@ -12,7 +11,7 @@ npm install
 cd packages/docs
 ```
 
-## Local Development
+## Local development
 
 ```bash
 npm start
@@ -28,14 +27,22 @@ npm run build
 
 This command generates static content into the `build` directory and can be served using any static contents hosting service.
 
-## Test your production build locally
+## Test your build locally
 
 ```bash
 npm run serve
 ```
 
-The  build folder is now served at http://localhost:3000/.
+The build folder is now served at http://localhost:3000/.
+
+## Generating reference docs
+
+The API reference pages are auto-generated from the Blockly TypeScript source using `@microsoft/api-extractor` and `@microsoft/api-documenter`. This is a separate step from the Docusaurus build and must be run from the `packages/blockly` directory:
 
-## Deployment
+```bash
+cd packages/blockly
+npm run build && npm run package
+npm run docs
+```
 
-TODO
+This generates MDX files into `packages/docs/docs/reference/`. These files are gitignored, so this needs to be run locally (and / or in CI).

packages/docs/docs/codelabs/custom-renderer/understand-connection-shapes.mdx

@@ -15,7 +15,7 @@ The outline of the block is a single [SVG path](https://developer.mozilla.org/en
 
 Each sub-path is a string of [path commands](https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/d#path_commands) that describe the appropriate shape. These commands must use relative (rather than absolute) coordinates.
 
-SVG path commands can be written as strings, but Blockly provides a set of [utility functions](/reference/js/blockly.utils_namespace.svgpaths_namespace) to make writing and reading paths easier.
+SVG path commands can be written as strings, but Blockly provides a set of [utility functions](/reference/blockly.utils_namespace.svgpaths_namespace) to make writing and reading paths easier.
 
 ### `init()`
 

packages/docs/docs/guides/configure/web/appearance/block-colour.mdx

@@ -53,7 +53,7 @@ see [Colour formats](/guides/configure/web/appearance/colour-formats).
 Note the British spelling. Failure to set the colour results in a black block.
 
 You can also set the block color using the
-[`Block.setColour(..)`](/reference/js/blockly.block_class.setcolour_1_method)
+[`Block.setColour(..)`](/reference/blockly.block_class.setcolour_1_method)
 function, or by using [themes](/guides/configure/web/appearance/themes)
 and defining a block style.
 

packages/docs/docs/guides/configure/web/appearance/colour-formats.mdx

@@ -77,7 +77,7 @@ toolbox categories, plus a distinct colour for dynamic variables:
 ```
 
 These string values can be used in both the JSON definitions and
-[`block.setColour(..)`](/reference/js/blockly.block_class.setcolour_1_method).
+[`block.setColour(..)`](/reference/blockly.block_class.setcolour_1_method).
 
 You can add your own colour constants by adding to `Blockly.Msg`:
 

packages/docs/docs/guides/configure/web/configuration_struct.mdx

@@ -38,7 +38,7 @@ directly.
 ## Configuration options{#the-options-dictionary}
 
 The configuration object implements
-[`Blockly.BlocklyOptions`](/reference/js/blockly.blocklyoptions_interface)
+[`Blockly.BlocklyOptions`](/reference/blockly.blocklyoptions_interface)
 and has the following options. Note that several of these options change their
 default value based on whether the provided toolbox has categories or not.
 
@@ -72,8 +72,8 @@ default value based on whether the provided toolbox has categories or not.
 [Grid]: /guides/configure/web/grid
 [media]: /guides/configure/web/media
 [Move]: /guides/configure/web/move
-[setIsReadOnly]: /reference/js/blockly.workspace_class.setisreadonly_1_method
-[isReadOnly]: /reference/js/blockly.workspace_class.isreadonly_1_method
+[setIsReadOnly]: /reference/blockly.workspace_class.setisreadonly_1_method
+[isReadOnly]: /reference/blockly.workspace_class.isreadonly_1_method
 [renderer]: /guides/create-custom-blocks/renderers/create-custom-renderers/basic-implementation
 [RTL demo]: https://raspberrypifoundation.github.io/blockly-samples/examples/rtl-demo/
 [Themes]: /guides/configure/web/appearance/themes

packages/docs/docs/guides/configure/web/context-menus.mdx

@@ -455,15 +455,15 @@ steps:
 
 [block-default-menu-image]: /images/context-menus/block-default-menu.png
 [context-menu-items-source]: https://github.com/RaspberryPiFoundation/blockly/blob/main/core/contextmenu_items.ts
-[i-context-menu]: /reference/js/blockly.icontextmenu_interface
-[i-focusable-node]: /reference/js/blockly.ifocusablenode_interface
-[RegistryItem]: /reference/js/blockly.contextmenuregistry_namespace.registryitem_typealias
+[i-context-menu]: /reference/blockly.icontextmenu_interface
+[i-focusable-node]: /reference/blockly.ifocusablenode_interface
+[RegistryItem]: /reference/blockly.contextmenuregistry_namespace.registryitem_typealias
 [Scope]: #scope
 [enabled-image]: /images/context-menus/enabled-option.png
 [disabled-image]: /images/context-menus/disabled-option.png
-[customContextMenu]: /reference/js/blockly.blocksvg_class.customcontextmenu_property
-[configureContextMenu]: /reference/js/blockly.workspacesvg_class.configurecontextmenu_property
-[ContextMenuOption]: /reference/js/blockly.contextmenuregistry_namespace.contextmenuoption_typealias
-[LegacyContextMenuOption]: /reference/js/blockly.contextmenuregistry_namespace.legacycontextmenuoption_interface
+[customContextMenu]: /reference/blockly.blocksvg_class.customcontextmenu_property
+[configureContextMenu]: /reference/blockly.workspacesvg_class.configurecontextmenu_property
+[ContextMenuOption]: /reference/blockly.contextmenuregistry_namespace.contextmenuoption_typealias
+[LegacyContextMenuOption]: /reference/blockly.contextmenuregistry_namespace.legacycontextmenuoption_interface
 [coordinate-systems]: /guides/configure/web/metrics_manager#coordinate-systems
 [keyboard-navigation-plugin]: /guides/configure/web/keyboard-nav

packages/docs/docs/guides/configure/web/copy-paste.mdx

@@ -153,15 +153,15 @@ Blockly.clipboard.registry.register('MY_PASTER', new MyPaster());
 ```
 
 [implement-paster]: /guides/configure/web/copy-paste#implement-a-paster
-[ICopyable]: /reference/js/blockly.icopyable_interface
-[IDeletable]: /reference/js/blockly.ideletable_interface
-[IDraggable]: /reference/js/blockly.idraggable_interface
-[ICopyData]: /reference/js/blockly.icopyable_namespace.icopydata_interface
-[IPaster]: /reference/js/blockly.ipaster_interface
-[ISelectable]: /reference/js/blockly.iselectable_interface
+[ICopyable]: /reference/blockly.icopyable_interface
+[IDeletable]: /reference/blockly.ideletable_interface
+[IDraggable]: /reference/blockly.idraggable_interface
+[ICopyData]: /reference/blockly.icopyable_namespace.icopydata_interface
+[IPaster]: /reference/blockly.ipaster_interface
+[ISelectable]: /reference/blockly.iselectable_interface
 [default-keyboard-shortcuts]: /guides/configure/web/keyboard-shortcuts#default-shortcuts
 [context-menu-option]: /guides/configure/web/context-menus
 [custom-draggables]: /guides/configure/web/dragging/draggable
 [multiselect-plugin]: https://www.npmjs.com/package/@mit-app-inventor/blockly-plugin-workspace-multiselect
 [cross-tab-copy-paste-plugin]: https://www.npmjs.com/package/@blockly/plugin-cross-tab-copy-paste
-[clipboard-namespace]: /reference/js/blockly.clipboard_namespace
+[clipboard-namespace]: /reference/blockly.clipboard_namespace

packages/docs/docs/guides/configure/web/customization.mdx

@@ -30,23 +30,23 @@ The following Blockly classes can be replaced:
 For information about how to replace a renderer, see [Create custom
 renderers](/guides/create-custom-blocks/renderers/create-custom-renderers/basic-implementation).
 
-[`Blockly.dragging.Dragger`]: /reference/js/blockly.dragging_namespace.dragger_class
-[`Blockly.IDragger`]: /reference/js/blockly.idragger_interface
-[`Blockly.ConnectionChecker`]: /reference/js/blockly.connectionchecker_class
-[`Blockly.IConnectionChecker`]: /reference/js/blockly.iconnectionchecker_interface
-[`Blockly.InsertionMarkerPreviewer`]: /reference/js/blockly.insertionmarkerpreviewer_class
-[`Blockly.IConnectionPreviewer`]: /reference/js/blockly.iconnectionpreviewer_interface
-[`Blockly.HorizontalFlyout`]: /reference/js/blockly.horizontalflyout_class
-[`Blockly.VerticalFlyout`]: /reference/js/blockly.verticalflyout_class
-[`Blockly.IFlyout`]: /reference/js/blockly.iflyout_interface
-[`Blockly.MetricsManager`]: /reference/js/blockly.metricsmanager_class
-[`Blockly.IMetricsManager`]: /reference/js/blockly.imetricsmanager_interface
-[`Blockly.Toolbox`]: /reference/js/blockly.toolbox_class
-[`Blockly.IToolbox`]: /reference/js/blockly.itoolbox_interface
-[`Blockly.VariableMap`]: /reference/js/blockly.variablemap_class
-[`Blockly.IVariableMap`]: /reference/js/blockly.ivariablemap_interface
-[`Blockly.VariableModel`]: /reference/js/blockly.variablemodel_class
-[`Blockly.IVariableModel`]: /reference/js/blockly.ivariablemodel_interface
+[`Blockly.dragging.Dragger`]: /reference/blockly.dragging_namespace.dragger_class
+[`Blockly.IDragger`]: /reference/blockly.idragger_interface
+[`Blockly.ConnectionChecker`]: /reference/blockly.connectionchecker_class
+[`Blockly.IConnectionChecker`]: /reference/blockly.iconnectionchecker_interface
+[`Blockly.InsertionMarkerPreviewer`]: /reference/blockly.insertionmarkerpreviewer_class
+[`Blockly.IConnectionPreviewer`]: /reference/blockly.iconnectionpreviewer_interface
+[`Blockly.HorizontalFlyout`]: /reference/blockly.horizontalflyout_class
+[`Blockly.VerticalFlyout`]: /reference/blockly.verticalflyout_class
+[`Blockly.IFlyout`]: /reference/blockly.iflyout_interface
+[`Blockly.MetricsManager`]: /reference/blockly.metricsmanager_class
+[`Blockly.IMetricsManager`]: /reference/blockly.imetricsmanager_interface
+[`Blockly.Toolbox`]: /reference/blockly.toolbox_class
+[`Blockly.IToolbox`]: /reference/blockly.itoolbox_interface
+[`Blockly.VariableMap`]: /reference/blockly.variablemap_class
+[`Blockly.IVariableMap`]: /reference/blockly.ivariablemap_interface
+[`Blockly.VariableModel`]: /reference/blockly.variablemodel_class
+[`Blockly.IVariableModel`]: /reference/blockly.ivariablemodel_interface
 
 ## Create a replacement class