Skip to content

fix(docs): load the live demo locally and explain when it is missing - #1164

Merged
lcottercertinia merged 1 commit into
certinia:mainfrom
lukecotter:bug-docs-demo-fallback
Oct 8, 2026
Merged

lcottercertinia merged 1 commit into
certinia:mainfrom
lukecotter:bug-docs-demo-fallback

Conversation

@lukecotter

Copy link
Copy Markdown
Collaborator

📝 PR Overview

The homepage live demo never loaded under docusaurus start, even after build:demo. The frame asked for /demo/viewer, which GitHub Pages and docusaurus serve map to viewer.html, but the dev server does not. When the demo files are missing, the server still answers 200 with the site's own page, so the frame showed a 404 page and no reason.

The frame now loads viewer.html, which works on all three servers. Before it opens, a check confirms the demo is built. If it is not, the preview image stays and a message says what to do.

🛠️ Changes made

  • Load /demo/viewer.html - the dev server does not map an extension-less path to a file.
  • A HEAD request to demo/settings.json must return JSON before the demo opens - a missing file returns the site's HTML page with 200, so the status alone cannot tell.
  • If the check fails, the preview stays and a role="status" message replaces the button. It does not time out, so no one misses it.
    • Local dev: "Demo not built. Run pnpm build, then pnpm --filter docs-site build:demo, and reload."
    • The site: "The live demo is not available right now." with a link to the Marketplace.

🧩 Type of change (check all applicable)

  • 🐛 Bug fix - something not working as expected
  • ✨ New feature – adds new functionality
  • ♻️ Refactor - internal changes with no user impact
  • ⚡ Performance Improvement
  • 📝 Documentation - README or documentation site changes
  • 🔧 Chore - dev tooling, CI, config
  • 💥 Breaking change

📷 Screenshots / gifs / video [optional]

N/A

🔗 Related Issues

related #1140

✅ Tests added?

  • 👍 yes
  • 🙅 no, not needed
  • 🙋 no, I need help

📚 Docs updated?

  • 🔖 README.md
  • 🔖 CHANGELOG.md
  • 📖 help site
  • 🧪 Marked any pre-release-only features (README 🧪 badge — see RELEASING.md)
  • 🙅 not needed

Anything else we need to know? [optional]

  • Test plan: pnpm lint and pnpm exec jest --selectProjects docs (31 tests, 3 new) pass. The new tests cover the dev message, the site message on an HTML answer, and the site message on a network error. With the content-type check removed, the 2 HTML-answer tests fail.
  • Manual: pnpm build, pnpm --filter docs-site build:demo, pnpm --filter docs-site start, then click Open demo. To see the fallback, move lana-docs/static/demo away and click it again.

…sing

docusaurus start does not map /demo/viewer to viewer.html, so the local demo showed the site's 404 page in the frame. The frame now loads viewer.html. Before it opens, a HEAD request checks that the demo is built. If not, the preview stays and a message gives the build steps in dev, or links to the Marketplace on the site.
@lcottercertinia
lcottercertinia merged commit efcfcb6 into certinia:main Oct 8, 2026
9 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants