Skip to content

chore: fix some problems with docs site#9928

Merged
maribethb merged 5 commits into
RaspberryPiFoundation:mainfrom
maribethb:ref-docs
May 22, 2026
Merged

chore: fix some problems with docs site#9928
maribethb merged 5 commits into
RaspberryPiFoundation:mainfrom
maribethb:ref-docs

Conversation

@maribethb
Copy link
Copy Markdown
Contributor

The basics

The details

Resolves

Fixes 2 problems with docs site:

  • the reference docs are broken because api-extractor lets namespaces and classes with the same name clobber each other. we previously had a patch that fixed this problem so i need to investigate if the patch isn't working or if it was accidentally removed.

  • there's also a problem with the index pages. any page called index.md works for client side navigation but not for server side rendering. if you click on the "contribute to blockly" section of the guides, it loads. but when you refresh, you get a 404. i think this is related to the fact that they're index.md files and somewhere we have that configured to resolve to the path without that in the name

Proposed Changes

Probably easiest to review this change commit-wise:

  • Updates the api-documenter and api-extractor versions (pinned because they keep changing the output version of various files which breaks our setup even though they don't call them breaking changes, and to keep the patch working)
  • Recreates the patch for api-documenter and makes sure patch-package is run at the correct point in the lifecycle
  • Updates the reference docs sidebar generation to account for the fact that api-documenter switched from markdown tables to html tables
  • Updates the docusaurus config to add trailingSlashes: true which is the recommended configuration for deploying on Cloudflare Pages because that host always tries to add one if there's not an extension specified. you can see this in action even before this change because if you navigate to page on docs.blockly.com, the page won't have the trailing slash but if you refresh, it will. this is because cf is adding the slash but docusaurus isn't generating the files with one. this update always adds the trailing slash so that when you refresh, the url does not change.
  • Fixes the URL for the deployed docs site and default base url in docusaurus config
  • Removes the hardcoded slugs from the codelabs pages because they just matched the default ones that would be generated anyway
  • Removes the hardcoded slugs from a few index.mdx files because they were incorrect, just relying on the automatically generated ones results in the correct behavior. manually adding index to the slug was throwing off the url and causing the second problem above. also updated relevant links to these files.
  • Updates the redirects file CF pages uses to account for the fact that some of the google reference docs pages ended in .md and some didn't. also adds the trailing slash.

Reason for Changes

see above

Test Coverage

Tested locally in production mode (npm run build and npm run serve).

Manually verified:

  • the new trailing slash behavior
  • the new slug behavior for index files
  • reference docs and sidebar

Unable to verify:

  • the redirects behavior until we deploy this to CF pages

Documentation

Additional Information

@maribethb maribethb requested a review from a team as a code owner May 22, 2026 19:18
@maribethb maribethb requested a review from gonfunko May 22, 2026 19:18
@github-actions github-actions Bot added the PR: chore General chores (dependencies, typos, etc) label May 22, 2026
@maribethb maribethb merged commit 00cacc4 into RaspberryPiFoundation:main May 22, 2026
11 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

PR: chore General chores (dependencies, typos, etc)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants