diff --git a/.github/workflows/deploy-docusaurus.yml b/.github/workflows/deploy-docusaurus.yml
index 91bd4673f..db1745a9f 100644
--- a/.github/workflows/deploy-docusaurus.yml
+++ b/.github/workflows/deploy-docusaurus.yml
@@ -60,6 +60,11 @@ jobs:
       - name: Build the Docusaurus site
         working-directory: ./packages/docs
         run: npm run build
+        env:
+          # when deploying to a subdirectory of the <org>.github.io domain,
+          # we need to set the BASE_URL to the name of the repo, for a custom
+          # domain this could be /docs/
+          BASE_URL: /blockly/
       
       - name: Setup GitHub Pages
         uses: actions/configure-pages@v5
diff --git a/packages/docs/docusaurus.config.js b/packages/docs/docusaurus.config.js
index 2191f79be..d49f1ace8 100644
--- a/packages/docs/docusaurus.config.js
+++ b/packages/docs/docusaurus.config.js
@@ -14,7 +14,7 @@ const config = {
   },
 
   url: 'https://raspberrypifoundation.github.io',
-  baseUrl: '/docs/',
+  baseUrl: process.env.BASE_URL || '/docs/',
 
   // GitHub pages deployment config
   organizationName: 'RaspberryPiFoundation',