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/
2026-04-28 16:10:21 +02:00 · 2026-03-31 14:28:54 +01:00
parent 50591e03e0
commit eb6f6c30e5
52 changed files with 211 additions and 21246 deletions
@@ -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';
      }
    }
@@ -1,4 +1,5 @@
 # Autogenerated reference docs, do not check in
-docs/docs/reference/*
-
+docs/reference/*
+!docs/reference/_reference.js
 .docusaurus
+build/
@@ -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/.

-## Deployment
+## Generating reference docs

-TODO
+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:
+
+```bash
+cd packages/blockly
+npm run build && npm run package
+npm run docs
+```
+
+This generates MDX files into `packages/docs/docs/reference/`. These files are gitignored, so this needs to be run locally (and / or in CI).
@@ -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()`

@@ -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.

@@ -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`:

@@ -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
@@ -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
@@ -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
@@ -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

@@ -47,6 +47,6 @@ Blockly.Blocks['my_block'] = {

 [draggable]: /guides/configure/web/dragging/draggable
 [draggable-implementation]: /guides/configure/web/dragging/draggable#implementation
-[setDragStrategy]: /reference/js/blockly.blocksvg_class.setdragstrategy_1_method
-[IDraggable]: /reference/js/blockly.idraggable_interface
-[IDragStrategy]: /reference/js/blockly.idragstrategy_interface
+[setDragStrategy]: /reference/blockly.blocksvg_class.setdragstrategy_1_method
+[IDraggable]: /reference/blockly.idraggable_interface
+[IDragStrategy]: /reference/blockly.idragstrategy_interface
@@ -231,12 +231,12 @@ For more information about copying pasting see [Copy paste][copy-paste].
 [multiselect-plugin]: https://www.npmjs.com/package/@mit-app-inventor/blockly-plugin-workspace-multiselect
 {/* This doesn't exist yet */}
 [events]: /guides/configure/web/events
-[IRenderedElement]: /reference/js/blockly.irenderedelement_interface
-[IDraggable]: /reference/js/blockly.idraggable_interface
-[IDeletable]: /reference/js/blockly.ideletable_interface
-[ISelectable]: /reference/js/blockly.iselectable_interface
-[setSelected]: /reference/js/blockly.common_namespace.setselected_2_function
+[IRenderedElement]: /reference/blockly.irenderedelement_interface
+[IDraggable]: /reference/blockly.idraggable_interface
+[IDeletable]: /reference/blockly.ideletable_interface
+[ISelectable]: /reference/blockly.iselectable_interface
+[setSelected]: /reference/blockly.common_namespace.setselected_2_function
 [svg-group]: https://developer.mozilla.org/en-US/docs/Web/SVG/Element/g
-[Coordinate]: /reference/js/blockly.utils_namespace.coordinate_class
-[drag-target]: /reference/js/blockly.dragtarget_class
+[Coordinate]: /reference/blockly.utils_namespace.coordinate_class
+[drag-target]: /reference/blockly.dragtarget_class
 [copy-paste]: /guides/configure/web/copy-paste
@@ -170,6 +170,6 @@ const myWorkspace = Blockly.inject('blocklyDiv', {
 ```

 [draggable]: /guides/configure/web/dragging/draggable
-[drag-target]: /reference/js/blockly.dragtarget_class
+[drag-target]: /reference/blockly.dragtarget_class
 [scroll-options-plugin]: https://www.npmjs.com/package/@blockly/plugin-scroll-options
-[IDragger]: /reference/js/blockly.idragger_interface
+[IDragger]: /reference/blockly.idragger_interface
@@ -130,7 +130,7 @@ and causing side effects.

 ## Event types

-Refer to the [reference documentation](/reference/js/blockly.events_namespace)
+Refer to the [reference documentation](/reference/blockly.events_namespace)
 for information about individual events.

 ## Demo
@@ -271,8 +271,8 @@ in an exception.

 If you write a custom component from scratch, you'll need to implement the focus
 interfaces yourself. See the reference documentation for
-[`IFocusableTree`](/reference/js/blockly.ifocusabletree_interface) and
-[`IFocusableNode`](/reference/js/blockly.ifocusablenode_interface) more
+[`IFocusableTree`](/reference/blockly.ifocusabletree_interface) and
+[`IFocusableNode`](/reference/blockly.ifocusablenode_interface) more
 information.

 After you have implemented your class, test it against the keyboard navigation
@@ -367,7 +367,7 @@ manager just changes the actively focused node to passive focus.)

 Positionables are components that are positioned on top of the workspace and
 implement
-[`IPositionable`](/reference/js/blockly.ipositionable_interface).
+[`IPositionable`](/reference/blockly.ipositionable_interface).
 Examples are the trashcan and the backpack in the [backpack
 plugin](https://www.npmjs.com/package/@blockly/workspace-backpack).
 Positionables are not yet integrated into the focus system.
@@ -34,14 +34,14 @@ user presses a key (or combination of keys), Blockly:
 ## Scope

 A
-[`Scope`](/reference/js/blockly.contextmenuregistry_namespace.scope_interface)
+[`Scope`](/reference/blockly.contextmenuregistry_namespace.scope_interface)
 object identifies the Blockly component that currently has focus. Scope objects
 are passed to `preconditionFn` and `callback`, which use them to decide whether
 a shortcut applies to a particular component and, if so, how to apply it.

 To use a `Scope` object, use its `focusedNode` property. This is an object that
 implements
-[`IFocusableNode`](/reference/js/blockly.ifocusablenode_interface). This
+[`IFocusableNode`](/reference/blockly.ifocusablenode_interface). This
 interface is implemented by all Blockly components that the user can focus on,
 including workspaces, blocks, fields, comments, and your own custom components;
 for more information, see [Focus system](/guides/configure/web/focus).
@@ -58,7 +58,7 @@ preconditionFn(workspace, scope) {
 ## The KeyboardShortcut interface

 Objects in the shortcut registry implement the
-[`KeyboardShortcut`](/reference/js/blockly.shortcutregistry_namespace.keyboardshortcut_interface)
+[`KeyboardShortcut`](/reference/blockly.shortcutregistry_namespace.keyboardshortcut_interface)
 interface. This contains the following properties.

 ### name (required)
@@ -135,7 +135,7 @@ it.

 An array of keys (or combinations of keys) that activate this shortcut. To
 identify keys, use the keycodes in
-[`Blockly.utils.KeyCodes`](/reference/js/blockly.utils_namespace.keycodes_enum).
+[`Blockly.utils.KeyCodes`](/reference/blockly.utils_namespace.keycodes_enum).
 For example:

 ```js
@@ -148,7 +148,7 @@ const logFieldsShortcut = {

 If you want map additional keys to an existing shortcut -- for example, you want
 to add keys to a [default shortcut](#default-shortcuts) -- you can call
-[`Blockly.ShortcutRegistry.registry.addKeyMapping`](/reference/js/blockly.shortcutregistry_class.addkeymapping_1_method).
+[`Blockly.ShortcutRegistry.registry.addKeyMapping`](/reference/blockly.shortcutregistry_class.addkeymapping_1_method).
 This is not common.

 #### Key combinations
@@ -86,7 +86,7 @@ the bounding box around any blocks or workspace comments.

 :::note
 Content metrics do not take into account block comments, only [workspace
-comments](/reference/js/blockly.comments_namespace.workspacecomment_class/).
+comments](/reference/blockly.comments_namespace.workspacecomment_class/).
 :::

 <Image alt="The Blockly workspace with a blue box around the contents of the workspace." src="/images/metrics_manager/content_metrics.png" width={300} />
@@ -170,7 +170,7 @@ When you register a serializer you must provide several things:
    order](/guides/configure/web/serialization#deserialization-order).

    You can base the priority of your serializer on the [built-in
-    priorities](/reference/js/blockly.serialization_namespace.priorities_namespace)
+    priorities](/reference/blockly.serialization_namespace.priorities_namespace)

 When `Blockly.serialization.workspaces.save` is called, each serializer's `save`
 function will be called, and its data will be added to the final JSON output:
@@ -215,7 +215,7 @@ For information on how to migrate to JSON, see the [migration guide].
 ### APIs

 For information about the XML system's APIs see the [reference
-documentation](/reference/js/blockly.xml_namespace).
+documentation](/reference/blockly.xml_namespace).

 ### Block hooks

@@ -171,7 +171,7 @@ out.](/images/toolbox-disabled.png)
  </TabItem>
 </Tabs>
 You can also programmatically disable or enable a block by using
-[`setDisabledReason`](/reference/js/blockly.block_class.setdisabledreason_1_method).
+[`setDisabledReason`](/reference/blockly.block_class.setdisabledreason_1_method).

 ## Configure your blocks

@@ -70,15 +70,15 @@ Because the definition functions are mixed in to the block object:

 *   The `this` keyword in definition functions refers to the block object. That
    is, it can be used to access the public methods and properties in the
-    [`Block`](/reference/js/blockly.block_class) (or
-    [`BlockSvg`](/reference/js/blockly.blocksvg_class)) class.
+    [`Block`](/reference/blockly.block_class) (or
+    [`BlockSvg`](/reference/blockly.blocksvg_class)) class.

 Blockly defines a small number of functions you can use to customize blocks. The
 most common of these is `init`, which Blockly calls to initialize a block and
 which is used to define the block's look and feel. For a complete list, see the
 function-valued properties in the
-[`Block`](/reference/js/blockly.block_class#properties) and
-[`BlockSvg`](/reference/js/blockly.blocksvg_class#properties) classes.
+[`Block`](/reference/blockly.block_class#properties) and
+[`BlockSvg`](/reference/blockly.blocksvg_class#properties) classes.
 These properties effectively form an interface for block definitions to
 implement; all of them are optional.

@@ -160,7 +160,7 @@ This section summarizes the objects and functions used to define custom blocks.

 ### Blockly.Blocks

-[`Blockly.Blocks`](/reference/js/blockly.blocks_variable) is an object
+[`Blockly.Blocks`](/reference/blockly.blocks_variable) is an object
 that stores block definitions. Its keys are block type names and its values are
 block definition objects. Use `Blockly.Blocks` when defining blocks with
 JavaScript:
@@ -188,7 +188,7 @@ Blockly.Blocks['my_block'].setColour(150);

 ### defineBlocksWithJsonArray

-[`defineBlocksWithJsonArray`](/reference/js/blockly.common_namespace.defineblockswithjsonarray_1_function)
+[`defineBlocksWithJsonArray`](/reference/blockly.common_namespace.defineblockswithjsonarray_1_function)
 accepts an array of JSON objects, creates block definitions from them, and adds
 them to `Blockly.Blocks`.

@@ -211,7 +211,7 @@ Blockly.common.defineBlocksWithJsonArray([

 ### createBlockDefinitionsFromJsonArray and defineBlocks

-[`createBlockDefinitionsFromJsonArray`](/reference/js/blockly.common_namespace.createblockdefinitionsfromjsonarray_1_function)
+[`createBlockDefinitionsFromJsonArray`](/reference/blockly.common_namespace.createblockdefinitionsfromjsonarray_1_function)
 accepts an array of JSON objects and returns an object that maps block type
 names to block definitions. This is generally used with `defineBlocks`, which
 adds the block definitions to `Blockly.Blocks`.
@@ -238,7 +238,7 @@ Blockly.common.defineBlocks(myBlockDefinitions);

 ### Block.jsonInit

-[`jsonInit`](/reference/js/blockly.block_class.jsoninit_1_method)
+[`jsonInit`](/reference/blockly.block_class.jsoninit_1_method)
 accepts a JSON object and calls the corresponding methods on `Block`. For
 example, a JSON object with the key-value pair `colour: 150` results in a call
 to `this.setColour(150)`. Use `jsonInit` in an `init` function to load a JSON
@@ -88,7 +88,7 @@ can act like buttons that exist on blocks.

 The on click handler can be set in the [JavaScript Constructor](#creation) or
 using the
-[`setOnClickHandler`](/reference/js/blockly.fieldimage_class.setonclickhandler_1_method)
+[`setOnClickHandler`](/reference/blockly.fieldimage_class.setonclickhandler_1_method)
 function.

 Here is an example of an on click handler that collapses the block when
@@ -74,7 +74,7 @@ collapsed.](/images/fields/label/collapsed.png)
  ```
  </TabItem>
 </Tabs>
-The [`appendField`](/reference/js/blockly.input_class.appendfield_1_method)
+The [`appendField`](/reference/blockly.input_class.appendfield_1_method)
 function accepts both `FieldLabel` objects and, more commonly, strings to create
 labels.

@@ -105,7 +105,7 @@ The `value` should cast to a number. If it does not 0 will be used.
 ## Constraints

 Constraints can be set in the field definition, or by using the
-[setConstraints](/reference/js/blockly.fieldnumber_class.setconstraints_1_method)
+[setConstraints](/reference/blockly.fieldnumber_class.setconstraints_1_method)
 function.

 ### Minimum value
@@ -180,7 +180,7 @@ return a string, `null`, or `undefined`.

 Here's an example of a validator that only accepts some predefined variables as
 options. These variables would need to be defined with the
-[`Workspace.getVariableMap().createVariable`](/reference/js/blockly.ivariablemap_interface.createvariable_1_methodsignature)
+[`Workspace.getVariableMap().createVariable`](/reference/blockly.ivariablemap_interface.createvariable_1_methodsignature)
 function when the workspace is loaded.

 ```js
@@ -107,7 +107,7 @@ You also need to define your `fromJson` function. Your implementation should
 first dereference any [references to localization
 tokens](/guides/configure/web/translations#use-localization-tokens-in-json)
 using
-[`replaceMessageReferences`](/reference/js/blockly.utils_namespace.parsing_namespace.replacemessagereferences_1_function),
+[`replaceMessageReferences`](/reference/blockly.utils_namespace.parsing_namespace.replacemessagereferences_1_function),
 and then pass the values to the constructor.

 ```js
@@ -222,11 +222,11 @@ When overriding `bindEvents_` you should always call the base function.
 :::

 To bind to an event you should generally use the
-[`Blockly.utils.browserEvents.conditionalBind`](/reference/js/blockly.utils_namespace.browserevents_namespace.conditionalbind_1_function)
+[`Blockly.utils.browserEvents.conditionalBind`](/reference/blockly.utils_namespace.browserevents_namespace.conditionalbind_1_function)
 function. This method of binding events filters out secondary touches during
 drags. If you want your handler to run even in the middle of an in-progress drag
 you can use the
-[`Blockly.browserEvents.bind`](/reference/js/blockly.utils_namespace.browserevents_namespace.bind_1_function)
+[`Blockly.browserEvents.bind`](/reference/blockly.utils_namespace.browserevents_namespace.bind_1_function)
 function.

 ## Disposing
@@ -388,7 +388,7 @@ currently there is no way to enforce this pattern.
 ### isDirty_

 `isDirty_` is a flag used in the
-[`setValue`](/reference/js/blockly.field_class.setvalue_1_method)
+[`setValue`](/reference/blockly.field_class.setvalue_1_method)
 function, as well as other parts of the field, to tell if the field needs to be
 re-rendered. If the field's display value has changed, `isDirty_` should usually
 be set to `true`.
@@ -401,7 +401,7 @@ field](/guides/create-custom-blocks/fields/anatomy-of-a-field).

 If the text of your field is different than the value of your field, you should
 override the
-[`getText`](/reference/js/blockly.field_class.gettext_1_method)function
+[`getText`](/reference/blockly.field_class.gettext_1_method)function
 to provide the correct text.

 ```js
@@ -437,7 +437,7 @@ the `DropDownDiv`.

 ![Image of angle picker](/images/angle-picker.png)

-The [`WidgetDiv`](/reference/js/blockly.widgetdiv_namespace) is used to
+The [`WidgetDiv`](/reference/blockly.widgetdiv_namespace) is used to
 provide editors that do not live inside of a box. Number fields use the
 `WidgetDiv` to cover the field with an HTML text input box. While the
 `DropDownDiv` handles positioning for you, the `WidgetDiv` does not. Elements
@@ -545,7 +545,7 @@ property to `true`.
 ### Defaults

 The default `render_` function sets the display text to the result of the
-[`getDisplayText_`](/reference/js/blockly.field_class.getdisplaytext__1_method)
+[`getDisplayText_`](/reference/blockly.field_class.getdisplaytext__1_method)
 function. The `getDisplayText_` function returns the field's `value_` property
 cast to a string, after it has been truncated to respect the maximum text
 length.
@@ -289,9 +289,9 @@ handling](/guides/create-custom-blocks/fields/customizing-fields/creating#value-

 We recommend that you never access or update the `text_` property of your
 field directly. Instead, use the
-[`getText`](/reference/js/blockly.field_class.gettext_1_method) function
+[`getText`](/reference/blockly.field_class.gettext_1_method) function
 to access the user readable text of your field and the
-[`setValue`](/reference/js/blockly.field_class.setvalue_1_method) function
+[`setValue`](/reference/blockly.field_class.setvalue_1_method) function
 to update the stored value of your field.

 For more information about a field's value vs its text see
@@ -79,7 +79,7 @@ Blockly.Blocks['validator_example'] = {
 ```

 + With
-[`setValidator`](/reference/js/blockly.field_class.setvalidator_1_method).
+[`setValidator`](/reference/blockly.field_class.setvalidator_1_method).

 ```js
 Blockly.Blocks['validator_example'] = {
@@ -192,18 +192,18 @@ dispose() {
 ```

 [bubble]: /guides/create-custom-blocks/icons/creating-custom-icons/use-bubbles
-[IIcon]: /reference/js/blockly.iicon_interface
-[Icon]: /reference/js/blockly.icons_namespace.icon_class
-[getType]: /reference/js/blockly.iicon_interface.gettype_1_methodsignature
+[IIcon]: /reference/blockly.iicon_interface
+[Icon]: /reference/blockly.icons_namespace.icon_class
+[getType]: /reference/blockly.iicon_interface.gettype_1_methodsignature
 [registering]: /guides/create-custom-blocks/icons/creating-custom-icons/save-and-load#register-icon-classes
-[getIcon]: /reference/js/blockly.block_class.geticon_1_method
-[initView]: /reference/js/blockly.iicon_interface.initview_1_methodsignature
-[blockly-utils-dom]: /reference/js/blockly.utils_namespace.dom_namespace
-[getSize]: /reference/js/blockly.iicon_interface.getsize_1_methodsignature
+[getIcon]: /reference/blockly.block_class.geticon_1_method
+[initView]: /reference/blockly.iicon_interface.initview_1_methodsignature
+[blockly-utils-dom]: /reference/blockly.utils_namespace.dom_namespace
+[getSize]: /reference/blockly.iicon_interface.getsize_1_methodsignature
 [renderer]: /guides/create-custom-blocks/renderers/overview
-[getWeight]: /reference/js/blockly.iicon_interface.getweight_1_methodsignature
-[onClick]: /reference/js/blockly.iicon_interface.onclick_1_methodsignature
-[updateEditable]: /reference/js/blockly.iicon_interface.updateeditable_1_methodsignature
-[isShownWhenCollapsed]: /reference/js/blockly.iicon_interface.isshownwhencollapsed_1_methodsignature
-[updateCollapsed]: /reference/js/blockly.iicon_interface.updatecollapsed_1_methodsignature
-[dispose]: /reference/js/blockly.iicon_interface.dispose_1_methodsignature
+[getWeight]: /reference/blockly.iicon_interface.getweight_1_methodsignature
+[onClick]: /reference/blockly.iicon_interface.onclick_1_methodsignature
+[updateEditable]: /reference/blockly.iicon_interface.updateeditable_1_methodsignature
+[isShownWhenCollapsed]: /reference/blockly.iicon_interface.isshownwhencollapsed_1_methodsignature
+[updateCollapsed]: /reference/blockly.iicon_interface.updatecollapsed_1_methodsignature
+[dispose]: /reference/blockly.iicon_interface.dispose_1_methodsignature
@@ -79,8 +79,8 @@ dispose() {
 }
 ```

-[built-in-bubbles]: /reference/js/blockly.bubbles_namespace
-[blockly-utils-dom]: /reference/js/blockly.utils_namespace.dom_namespace
-[bubble]: /reference/js/blockly.bubbles_namespace.bubble_class
-[setSize]: /reference/js/blockly.bubbles_namespace.bubble_class.setsize_1_method
-[dispose]: /reference/js/blockly.bubbles_namespace.bubble_class.dispose_1_method
+[built-in-bubbles]: /reference/blockly.bubbles_namespace
+[blockly-utils-dom]: /reference/blockly.utils_namespace.dom_namespace
+[bubble]: /reference/blockly.bubbles_namespace.bubble_class
+[setSize]: /reference/blockly.bubbles_namespace.bubble_class.setsize_1_method
+[dispose]: /reference/blockly.bubbles_namespace.bubble_class.dispose_1_method
@@ -37,7 +37,7 @@ class MyCommentIcon extends Blockly.icons.CommentIcon {

 To customize your icon, you can override methods in `ICommentIcon` (described in
 the following sections) and
-[`Blockly.icons.Icon`](/reference/js/blockly.icons_namespace.icon_class)
+[`Blockly.icons.Icon`](/reference/blockly.icons_namespace.icon_class)
 (described in [Create custom
 icons](/guides/create-custom-blocks/icons/creating-custom-icons/basic-implementation)).
 Do not override `getType`, which must return `Blockly.icons.IconType.COMMENT`.
@@ -152,10 +152,10 @@ After you register your icon, Blockly will use it in place of the built-in
 comment icon, such as when the user clicks "Add Comment" on the context menu or
 you call `myBlock.setCommentText()`.

-[ICommentIcon]: /reference/js/blockly.icommenticon_interface
-[IHasBubble]: /reference/js/blockly.ihasbubble_interface
+[ICommentIcon]: /reference/blockly.icommenticon_interface
+[IHasBubble]: /reference/blockly.ihasbubble_interface
 [use-bubbles]: /guides/create-custom-blocks/icons/creating-custom-icons/use-bubbles
-[ISerializable]: /reference/js/blockly.iserializable_interface
-[CommentState]: /reference/js/blockly.icons_namespace.commentstate_interface
+[ISerializable]: /reference/blockly.iserializable_interface
+[CommentState]: /reference/blockly.icons_namespace.commentstate_interface
 [icon-serialization]: /guides/create-custom-blocks/icons/creating-custom-icons/save-and-load
 [comment-icon-image]: /images/block-icons/comment-icon-outline.png
@@ -100,10 +100,10 @@ Blockly.icons.registry.register(
    new Blockly.icons.IconType('my_icon'), myIcon);
 ```

-[ISerializable]: /reference/js/blockly.iserializable_interface
+[ISerializable]: /reference/blockly.iserializable_interface
 [registering]: /guides/create-custom-blocks/icons/creating-custom-icons/save-and-load#register-icon-classes
-[saveState]: /reference/js/blockly.iserializable_interface.savestate_1_methodsignature
-[loadState]: /reference/js/blockly.iserializable_interface.loadstate_1_methodsignature
-[IconType]: /reference/js/blockly.icons_namespace.icontype_class
-[getType]: /reference/js/blockly.iicon_interface.gettype_1_methodsignature
+[saveState]: /reference/blockly.iserializable_interface.savestate_1_methodsignature
+[loadState]: /reference/blockly.iserializable_interface.loadstate_1_methodsignature
+[IconType]: /reference/blockly.icons_namespace.icontype_class
+[getType]: /reference/blockly.iicon_interface.gettype_1_methodsignature
 [serializer]: /guides/configure/web/serialization#serializer-hooks
@@ -79,8 +79,8 @@ isBubbleVisible() {
 }
 ```

-[IIcon]: /reference/js/blockly.iicon_interface
-[IHasBubble]: /reference/js/blockly.ihasbubble_interface
-[setBubbleVisible]: /reference/js/blockly.ihasbubble_interface.setbubblevisible_1_methodsignature
-[bubbleIsVisible]: /reference/js/blockly.ihasbubble_interface.bubbleisvisible_1_methodsignature
-[onLocationChange]: /reference/js/blockly.iicon_interface.onlocationchange_1_methodsignature
+[IIcon]: /reference/blockly.iicon_interface
+[IHasBubble]: /reference/blockly.ihasbubble_interface
+[setBubbleVisible]: /reference/blockly.ihasbubble_interface.setbubblevisible_1_methodsignature
+[bubbleIsVisible]: /reference/blockly.ihasbubble_interface.bubbleisvisible_1_methodsignature
+[onLocationChange]: /reference/blockly.iicon_interface.onlocationchange_1_methodsignature
@@ -24,4 +24,4 @@ or copyright information in a pop-up bubble.

 [fields-vs-icons]: /guides/create-custom-blocks/fields/fields-vs-icons
 [custom-icons]: /guides/create-custom-blocks/icons/creating-custom-icons/basic-implementation
-[icons-reference]: /reference/js/blockly.icons_namespace
+[icons-reference]: /reference/blockly.icons_namespace
@@ -240,5 +240,5 @@ connection checker.

 [connection-type]: /guides/create-custom-blocks/define/block-anatomy#connections
 [event-system]: /guides/configure/web/events
-[BlockMove]: /reference/js/blockly.events_namespace.blockmove_class
+[BlockMove]: /reference/blockly.events_namespace.blockmove_class
 [custom-connection-checker]: /guides/create-custom-blocks/inputs/connection_checker
@@ -200,7 +200,7 @@ For more information about registration, see
 [built-in-replacement-preview-image]: /images/connections/built-in-replacement-preview.png
 [built-in-insertion-preview-image]: /images/connections/built-in-insertion-preview.png
 [built-in-previewer-image]: /images/connections/built-in-previewer.gif
-[IConnectionPreviewer]: /reference/js/blockly.iconnectionpreviewer_interface
+[IConnectionPreviewer]: /reference/blockly.iconnectionpreviewer_interface
 [insertion-marker]: /guides/get-started/workspace-anatomy#insertion-marker
 [custom-renderer]: /guides/create-custom-blocks/renderers/create-custom-renderers/basic-implementation
 [inject-subclasses]: /guides/configure/web/customization#injecting-subclasses
@@ -50,7 +50,7 @@ unlike [custom fields][custom-fields], you can't override
 built-in inputs, and you can't add custom JSON configuration to them.
 :::

-[Input]: /reference/js/blockly.inputs_namespace.input_class
-[makeConnection]: /reference/js/blockly.inputs_namespace.input_class.makeconnection_1_method
+[Input]: /reference/blockly.inputs_namespace.input_class
+[makeConnection]: /reference/blockly.inputs_namespace.input_class.makeconnection_1_method
 [json-block-def]: /guides/create-custom-blocks/define/json-and-js
 [custom-fields]: /guides/create-custom-blocks/fields/customizing-fields/creating
@@ -227,7 +227,7 @@ Blockly.Blocks['my_procedure_call'] = {

 You can also add the ability for users to modify the procedure model. Calling
 the `insertParameter`, `deleteParameter`, or `setReturnTypes`
-[methods](/reference/js/blockly.procedures_namespace.iproceduremodel_interface)
+[methods](/reference/blockly.procedures_namespace.iproceduremodel_interface)
 will automatically trigger your blocks to rerender (via `doProcedureUpdate`).

 Options for creating UIs to modify the procedure model include using
@@ -126,5 +126,5 @@ class MyParameterModel {
 ```

 [shareable-procedures]: https://www.npmjs.com/package/@blockly/block-shareable-procedures
-[IProcedureModel]: /reference/js/blockly.procedures_namespace.iproceduremodel_interface
-[IParameterModel]: /reference/js/blockly.procedures_namespace.iparametermodel_interface
+[IProcedureModel]: /reference/blockly.procedures_namespace.iproceduremodel_interface
+[IParameterModel]: /reference/blockly.procedures_namespace.iparametermodel_interface
@@ -37,8 +37,8 @@ block, like jagged edges for collapsed blocks.
 And finally, the constant provider also defines various values for things like
 the padding between different elements, or the minimum heights of rows.

-[ConstantProvider]: /reference/js/blockly.blockrendering_namespace.constantprovider_class
-[Notch]: /reference/js/blockly.blockrendering_namespace.constantprovider_class.notch_property
-[PuzzleTab]: /reference/js/blockly.blockrendering_namespace.constantprovider_class.puzzle_tab_property
+[ConstantProvider]: /reference/blockly.blockrendering_namespace.constantprovider_class
+[Notch]: /reference/blockly.blockrendering_namespace.constantprovider_class.notch_property
+[PuzzleTab]: /reference/blockly.blockrendering_namespace.constantprovider_class.puzzle_tab_property
 [connection-check]: /guides/create-custom-blocks/inputs/connection-checks
-[shapeFor]: /reference/js/blockly.blockrendering_namespace.constantprovider_class.shapefor_1_method
+[shapeFor]: /reference/blockly.blockrendering_namespace.constantprovider_class.shapefor_1_method
@@ -16,9 +16,9 @@ Blockly to do this.

 The drawer also updates the offsets of connections within the block.

-[Drawer]: /reference/js/blockly.blockrendering_namespace.drawer_class
+[Drawer]: /reference/blockly.blockrendering_namespace.drawer_class
 [paths]: https://developer.mozilla.org/en-US/docs/Web/SVG/Tutorial/Paths
 [render-info]: /guides/create-custom-blocks/renderers/concepts/info
 [path-object]: /guides/create-custom-blocks/renderers/concepts/path-object
 [constants]: /guides/create-custom-blocks/renderers/concepts/constants
-[svg-path-utils]: /reference/js/blockly.utils_namespace.svgpaths_namespace
+[svg-path-utils]: /reference/blockly.utils_namespace.svgpaths_namespace
@@ -45,8 +45,8 @@ depending on the elements to either side of the spacer.

 [render-info]: /guides/create-custom-blocks/renderers/concepts/info
 [row]: /guides/create-custom-blocks/renderers/concepts/rows
-[field-element]: /reference/js/blockly.blockrendering_namespace.field_class
-[getSize]: /reference/js/blockly.field_class.getsize_1_method
+[field-element]: /reference/blockly.blockrendering_namespace.field_class
+[getSize]: /reference/blockly.field_class.getsize_1_method

 [element-image]: /images/rendering/debug-renderer/element.png
 [element-spacer-image]: /images/rendering/debug-renderer/element-spacer.png
@@ -27,7 +27,7 @@ which are organized into non-overlapping [rows][row], and
 Then the [drawer][drawer] uses that organized layout information to create the
 SVG paths representing the block.

-[RenderInfo]: /reference/js/blockly.blockrendering_namespace.renderinfo_class
+[RenderInfo]: /reference/blockly.blockrendering_namespace.renderinfo_class
 [drawer]: /guides/create-custom-blocks/renderers/concepts/drawer
 [row]: /guides/create-custom-blocks/renderers/concepts/rows
 [element]: /guides/create-custom-blocks/renderers/concepts/elements
@@ -26,7 +26,7 @@ It also handles:
  * Applying [theme colors][theme] to the SVG elements.
  * Applying other styling to the SVG elements.

-[PathObject]: /reference/js/blockly.blockrendering_namespace.pathobject_class
+[PathObject]: /reference/blockly.blockrendering_namespace.pathobject_class
 [theme]: /guides/configure/web/appearance/themes#block-style
 [built-in-renderers]: /guides/create-custom-blocks/renderers/overview#built-in-renderers
 [drawer]: /guides/create-custom-blocks/renderers/concepts/drawer
@@ -16,7 +16,7 @@ And it contains code for wiring them all together when it renders a block.
 If you want to change just one part of an existing renderer (e.g. the constants)
 you can subclass the relevant factory method.

-[Renderer]: /reference/js/blockly.blockrendering_namespace.renderer_class
+[Renderer]: /reference/blockly.blockrendering_namespace.renderer_class
 [constants]: /guides/create-custom-blocks/renderers/concepts/constants
 [render-info]: /guides/create-custom-blocks/renderers/concepts/info
 [path-object]: /guides/create-custom-blocks/renderers/concepts/path-object
@@ -40,8 +40,8 @@ The bounds of the row spacers are determined by the
 [render info][render-info] itself. After measuring all of the rows of the block,
 the [render info][render-info] inserts spaces of its chosen size between rows.

-[Row]: /reference/js/blockly.blockrendering_namespace.row_class
-[RowSpacer]: /reference/js/blockly.blockrendering_namespace.spacerrow_class
+[Row]: /reference/blockly.blockrendering_namespace.row_class
+[RowSpacer]: /reference/blockly.blockrendering_namespace.spacerrow_class
 [render-info]: /guides/create-custom-blocks/renderers/concepts/info
 [external-vs-inline]: /guides/create-custom-blocks/define/inline-vs-external
 [element]: /guides/create-custom-blocks/renderers/concepts/elements
@@ -85,16 +85,16 @@ const workspace = Blockly.inject(blocklyDiv, {
 });
 ```

-[Renderer]: /reference/js/blockly.blockrendering_namespace.renderer_class
+[Renderer]: /reference/blockly.blockrendering_namespace.renderer_class
 [renderer-concept]: /guides/create-custom-blocks/renderers/concepts/renderer
 [base-renderer-image]: /images/rendering/renderers/base-renderer.png
 [built-in-renderers]: /guides/create-custom-blocks/renderers/overview#built-in-renderers
 [renderer-component]: /guides/create-custom-blocks/renderers/concepts/overview
 [connection-shape]: /guides/create-custom-blocks/renderers/create-custom-renderers/connection-shapes
 [constants]: /guides/create-custom-blocks/renderers/concepts/constants
-[makeConstants]: /reference/js/blockly.blockrendering_namespace.renderer_class.makeconstants__1_method
-[makeRenderInfo]: /reference/js/blockly.blockrendering_namespace.renderer_class.makerenderinfo__1_method
-[makePathObject]: /reference/js/blockly.blockrendering_namespace.renderer_class.makepathobject_1_method
-[makeDrawer]: /reference/js/blockly.blockrendering_namespace.renderer_class.makedrawer__1_method
+[makeConstants]: /reference/blockly.blockrendering_namespace.renderer_class.makeconstants__1_method
+[makeRenderInfo]: /reference/blockly.blockrendering_namespace.renderer_class.makerenderinfo__1_method
+[makePathObject]: /reference/blockly.blockrendering_namespace.renderer_class.makepathobject_1_method
+[makeDrawer]: /reference/blockly.blockrendering_namespace.renderer_class.makedrawer__1_method
 [inject-config]: /guides/configure/web/configuration_struct
 [custom-renderer-codelab]: /codelabs/custom-renderer/codelab-overview/index.html
@@ -275,27 +275,27 @@ export class Drawer extends Blockly.blockRendering.Drawer {
 [internal-inputs-image]: /images/rendering/connection-shapes/internal-inputs.png
 [basic-implementation]: /guides/create-custom-blocks/renderers/create-custom-renderers/basic-implementation
 [constants]: /guides/create-custom-blocks/renderers/concepts/constants
-[BaseConstants]: /reference/js/blockly.blockrendering_namespace.constantprovider_class
-[GerasConstants]: /reference/js/blockly.geras_namespace.constantprovider_class
-[ZelosConstants]: /reference/js/blockly.zelos_namespace.constantprovider_class
-[NOTCH_WIDTH]: /reference/js/blockly.blockrendering_namespace.constantprovider_class.notch_width_property
-[NOTCH_HEIGHT]: /reference/js/blockly.blockrendering_namespace.constantprovider_class.notch_height_property
-[TAB_WIDTH]: /reference/js/blockly.blockrendering_namespace.constantprovider_class.tab_width_property
-[TAB_HEIGHT]: /reference/js/blockly.blockrendering_namespace.constantprovider_class.tab_height_property
+[BaseConstants]: /reference/blockly.blockrendering_namespace.constantprovider_class
+[GerasConstants]: /reference/blockly.geras_namespace.constantprovider_class
+[ZelosConstants]: /reference/blockly.zelos_namespace.constantprovider_class
+[NOTCH_WIDTH]: /reference/blockly.blockrendering_namespace.constantprovider_class.notch_width_property
+[NOTCH_HEIGHT]: /reference/blockly.blockrendering_namespace.constantprovider_class.notch_height_property
+[TAB_WIDTH]: /reference/blockly.blockrendering_namespace.constantprovider_class.tab_width_property
+[TAB_HEIGHT]: /reference/blockly.blockrendering_namespace.constantprovider_class.tab_height_property
 [path-object]: /guides/create-custom-blocks/renderers/concepts/path-object
-[makeNotch]: /reference/js/blockly.blockrendering_namespace.constantprovider_class.makenotch_1_method
-[makePuzzleTab]: /reference/js/blockly.blockrendering_namespace.constantprovider_class.makepuzzletab_1_method
+[makeNotch]: /reference/blockly.blockrendering_namespace.constantprovider_class.makenotch_1_method
+[makePuzzleTab]: /reference/blockly.blockrendering_namespace.constantprovider_class.makepuzzletab_1_method
 [connection-check]: /guides/create-custom-blocks/inputs/connection-checks
-[shapeFor]: /reference/js/blockly.blockrendering_namespace.constantprovider_class.shapefor_1_method
+[shapeFor]: /reference/blockly.blockrendering_namespace.constantprovider_class.shapefor_1_method
 [basic-shapes]: #basic-shapes
 [custom-input]: /guides/create-custom-blocks/inputs/creating-custom-inputs
 [measurable]: /guides/create-custom-blocks/renderers/concepts/overview#block-measurables
-[InputConnection]: /reference/js/blockly.blockrendering_namespace.inputconnection_class
+[InputConnection]: /reference/blockly.blockrendering_namespace.inputconnection_class
 [render-info]: /guides/create-custom-blocks/renderers/concepts/info
-[addInput]: /reference/js/blockly.blockrendering_namespace.renderinfo_class.addinput__1_method
+[addInput]: /reference/blockly.blockrendering_namespace.renderinfo_class.addinput__1_method
 [row]: /guides/create-custom-blocks/renderers/concepts/rows
-[shouldStartNewRow]: /reference/js/blockly.blockrendering_namespace.renderinfo_class.shouldstartnewrow__1_method
+[shouldStartNewRow]: /reference/blockly.blockrendering_namespace.renderinfo_class.shouldstartnewrow__1_method
 [drawer]: /guides/create-custom-blocks/renderers/concepts/drawer
-[drawOutline]: /reference/js/blockly.blockrendering_namespace.drawer_class.drawoutline__1_method
-[drawInternals]: /reference/js/blockly.blockrendering_namespace.drawer_class.drawinternals__1_method
+[drawOutline]: /reference/blockly.blockrendering_namespace.drawer_class.drawoutline__1_method
+[drawInternals]: /reference/blockly.blockrendering_namespace.drawer_class.drawinternals__1_method
 [svg-path]: https://developer.mozilla.org/en-US/docs/Web/SVG/Tutorial/Paths
@@ -20,7 +20,7 @@ Some properties may be annotated with `@internal` in their
 [TsDoc](https://api-extractor.com/pages/tsdoc/tag_internal/) comments.

 All `public` and `protected` properties are documented in the
-[References](/reference/js/blockly) section of the Blockly website. You
+[References](/reference/blockly) section of the Blockly website. You
 can also check visibility by reading the code.

 :::warning
@@ -40,6 +40,12 @@ const config = {
      '@docusaurus/plugin-client-redirects',
      {
        fromExtensions: ['md', 'mdx'],
+        createRedirects(existingPath) {
+          if (existingPath.startsWith('/reference/')) {
+            return [existingPath.replace('/reference/', '/reference/js/')];
+          }
+          return undefined;
+        },
      },
    ]
  ],
@@ -176,7 +182,7 @@ const config = {
              },
              {
                label: 'Reference',
-                to: '/reference/js/blockly',
+                to: '/reference',
              },
            ],
          },
@@ -1441,14 +1441,7 @@ const sidebars = {
      ],
    },
  ],
-  //referenceSidebar: referenceSidebar
-  referenceSidebar: [
-    {
-      "type": "doc",
-      "label": "Codelabs",
-      "id": "codelabs/index",
-    },
-  ],
+  referenceSidebar: referenceSidebar,
 };

 export default sidebars;