Skip to content

chore(docs): migrate to Docusaurus and GitHub Pages#9671

Open
grega wants to merge 43 commits intoRaspberryPiFoundation:mainfrom
grega:docs
Open

chore(docs): migrate to Docusaurus and GitHub Pages#9671
grega wants to merge 43 commits intoRaspberryPiFoundation:mainfrom
grega:docs

Conversation

@grega
Copy link
Copy Markdown
Member

@grega grega commented Mar 31, 2026 •
edited
Loading

The basics

The details

Resolves

Fixes #9543

Proposed Changes

Demo site: https://grega.github.io/blockly/

I've copied the task list from 9543 below, for clarity.

Test Coverage

n/a

Documentation

This is that 🙂

Tasks completed

  • GitHub Action updated (grega@2b0e4c8)
    • docs uploaded to a subdirectory of the GitHub pages
    • manual deployment of docs site (through GitHub Action workflow dispatch config)
    • hasn't been updated for monorepo structure and uses wrong branch name
  • toc.yaml removed (grega@15307fd)
  • ClassBlock removed (grega@8ae5974)
    • CodelabImages migrated to use Image component (grega@50edae1)
    • fix displayTableHeader class application (grega@ec19340)
    • compareBetter / compareWorse replaced with Docusaurus admonitions (grega@97a3e41)
  • CodelabsCards component moved to own dir (grega@ec0b74b)
  • general CSS clean up (grega@9273512)
  • custom.css cleanup and correct setting / use of color varialbes (grega@3504048)
  • /js removed from reference docs path (grega@eb6f6c3)
  • update docusaurus.config.js to correct values for repo and branch names, consider removing irrelevant comments (grega@50591e0)
  • update robots.txt to allow search engines to index it (grega@ef3cea8)
  • update .prettierignore and add prettier config so that handwritten md files get formatted but reference docs don't. all the code and config files in docs/ package should also be formatted (grega@231a9b1 and grega@45168a6)
  • de-duplicate static/img and static/images (grega@8839c16)
  • fix sidebar rendering for generated reference docs
    • also gitignore the _reference.js file generated by the reference docs build task
  • set up GitHub pages to be served at blockly.com/docs (handled through env var) (grega@bb89514)

Tasks remaining

Are these best handled in this PR, or can / should they be done separately?

  • set up redirects from devsite
  • make sure google analytics works (in particular we might need to configure the gtag info. Maribeth/Joe can give access to ga site)
  • make sure the algolia search works
  • consider converting all this code to typescript (might not be worth it, but at least deserves some consideration)

maribethb and others added 30 commits January 20, 2026 16:12
@maribethb
chore(docs): add guides and codelabs
b7269dd
@maribethb
chore(docs): add docs static resources
2aa1aa8
@maribethb
chore(docs): add google analytics tracking code
f4c6a27
@maribethb
chore(docs): move docs to packages dir
27b4d86
@maribethb
chore(docs): add docs workspace basic files
5b22be3
@grega
chore(docs): GitHub Actions Workflow for deploying docs to Pages
2b0e4c8 
Allows for manual Actions Workflow run for deployment, not automatic. Can be run against a given release/tag.
@grega
chore(docs): update docs config and paths (removing blockly/)
f5d792b 
Also setting correct GitHub org name
@grega
chore(docs): add Docusaurus components
89d608d 
For:
- Class blocks
- Codelab cards
- Homepage features
- Images
@grega
chore(docs): add custom styles
28fe803
@grega
chore(docs): add Docusaurus supporting elements
4b921fb 
Sidebar, index page, ToCs
@grega
chore(docs): add Gulp tasks
beb7a14
@grega
chore(docs): remove unneeded toc.yaml
15307fd 
This was leftover from the previous docs site / build process
@grega
chore(docs): remove unused CSS
bba5468
@grega
chore(docs): fix incorrect image paths in Markdown and Image component
f6a9020 
Both images declared through ![]() in Markdown, and using the Image component had output paths that were incorrect
@grega
chore(docs): allow all search engine indexing
ef3cea8
@grega
chore(docs): update theme colours, remove unneeded style declarations
3504048
@grega
chore(docs): remove unused custom styles
9273512
@grega
chore(docs): tidy Docusaurus config
50591e0
@grega
chore(docs): change path from /js/reference/ to /reference/
eb6f6c3 
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/
@grega
chore(docs): clarify deployment / workflow comment
8b2ea01
@grega
chore(docs): remove ClassBlack component, add individual components i…
8ae5974 
…nstead

Adds:
- CodelabImage
- CompareBlock
- TableHeader
@grega
chore(docs): move all Docusuarus-related images into single dir
8839c16 
Removing duplicate docs/img/ dir

Adds correct favicon

Removes unneeded default Docusaurus images/assets
@grega
chore(docs): remove TableHeader component, simplify tables in Markdown
ec19340 
Component was superfluous, we can achieve the same with regular Markdown table syntax and a very small amount of CSS
@grega
chore(docs): CSS syntax fixes
f5dcfb9
@grega
chore(docs): add Prettier config (and ignore) for docs
231a9b1
@grega
chore(docs): run prettier --write on docs
45168a6
@grega
chore(docs): switch to eslint for mdx linting/formatting
8982178 
Due to poor Prettier support

https://github.com/orgs/mdx-js/discussions/2127
@grega
chore(docs): run eslint on docs
e864021
@grega
chore(docs): update README docs on formatting and linting
87718a5
@grega
Merge branch 'docs'
2851979
@grega grega force-pushed the docs branch 3 times, most recently from 1ef3093 to 8c6d273 Compare April 7, 2026 10:29
@grega grega changed the title WIP: Documentation migration chore(docs): migrate to Docusaurus and GitHub Pages Apr 8, 2026
@github-actions github-actions bot added the PR: chore General chores (dependencies, typos, etc) label Apr 8, 2026
grega added 10 commits April 8, 2026 16:51
@grega
Merge branch 'main' of github.com:grega/blockly
062c403
@grega
chore(docs): fix Actions workflow to correctly build reference docs
363edf0 
Before generating the site, also gracefully handle the missing "references" sidebar config. Remove the, now generated, _reference.js sidebar config file
@grega
chore(docs): generate just typings for docs build Workflow
cca97ed 
ie. no need to build the entire Blockly package, with Closure compiler, just for the docs
@grega
chore(docs): set Docusaurus base_url in env var
b3fc849
@grega
chore(docs): add api documenter patch
e0cb73d
@grega
chore(docs): replace CodelabImage with standard Image component
703991e
@grega
chore(docs): remove index.html path requirement for all Code Labs p…
d44f955 
…aths/URLs
@grega
chore(docs): move CodelabCards component into own dir
541c8d6
@grega
chore(docs): replace CompareBlock component with admonition syntax
059a9c7
@grega
chore(docs): fix broken links
7a8f646 
Primarily to reference docs, also links to the GitHub repo prior to the monorepo reshuffle.
@grega grega marked this pull request as ready for review April 8, 2026 16:22
@grega grega requested a review from a team as a code owner April 8, 2026 16:22
@grega grega requested a review from mikeharv April 8, 2026 16:22
@grega
Copy link
Copy Markdown
Member Author

grega commented Apr 8, 2026

@mikeharv might be best for Maribeth and I to review where this is at first, there's quite a bit going on 🙂

@mikeharv mikeharv requested a review from maribethb April 8, 2026 16:28
@github-actions github-actions bot added PR: chore General chores (dependencies, typos, etc) and removed PR: chore General chores (dependencies, typos, etc) labels Apr 8, 2026
@maribethb
Copy link
Copy Markdown
Contributor

maribethb commented Apr 9, 2026

Overall this looks really great, thank you for your work on this! The things left in remaining tasks can def wait until after this is merged (also some of them will be handled outside github)

Remaining thoughts/questions:

  • I'm also stumped by the QA failures. It seems like mocha couldn't even load the test file? I have no idea... I'm assuming these commands work locally?
  • Will probably file a follow up bug to tackle the reference docs section of this bug, you got it working well enough with api-documenter, but I am still skeptical of how much work it is to translate these all into mdx and I don't really understand why they're doing all of this manual transformation. Worth looking at how much work it would be to switch to TypeDoc but can happen later
  • The biggest question I have is about how deploying to github pages works when we already deploy something else there. Will pages like the playground continue to work? We have a different workflow that pushes directly to the gh-pages branch, I don't know how that interacts with also using the gh-pages action. I think ideally the docs would be at raspberrypifoundation.github.io/blockly/docs and the other existing stuff would be at its current location. you could test this locally by running npm run updateGithubPages:staging from packages/blockly in your fork which will deploy our normal github pages to your fork

@maribethb
Copy link
Copy Markdown
Contributor

maribethb commented Apr 10, 2026

I realized that I know these two different publishing processes will not work together because the gulp script we currently use for gh-pages force pushes to that branch and overwrites the existing contents there. So this will definitely need some more thought to reconcile those two processes

but we could submit the rest of this PR and work on that as a follow up especially if i need to pick this back up

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@mikeharv mikeharv Awaiting requested review from mikeharv mikeharv is a code owner automatically assigned from RaspberryPiFoundation/blockly-collaborators

@maribethb maribethb Awaiting requested review from maribethb

At least 1 approving review is required to merge this pull request.

Assignees

@maribethb maribethb

@mikeharv mikeharv

Labels

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

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Migrate documentation site

3 participants

@grega @maribethb @mikeharv