fix: vendor mermaid#154
Merged
Merged
Conversation
Mermaid diagrams render as raw text on docs.aws.amazon.com because
the site's Content Security Policy blocks Zensical's default load
of mermaid from unpkg.com. The same pages work on localhost only
because localhost has no CSP.
Switch to self-hosting the @mermaid-js/tiny UMD build, which ships
as a single file with no lazy-loaded chunks and supports all
diagram types currently in use (flowchart, sequence, state, class,
entity-relationship).
- Add scripts/vendor_mermaid.py, which reads version and expected
sha256 from scripts/vendor_mermaid.toml, downloads the pinned
tiny build from cdn.jsdelivr.net, and verifies the sha256. The
script supports --check (CI-safe) and --latest modes.
- Vendor @mermaid-js/tiny@11.14.0 into
docs/assets/javascripts/mermaid.tiny.js.
- Add docs/javascripts/mermaid-init.js, which initializes the
vendored build with startOnLoad: false and securityLevel: strict.
- Register both files under extra_javascript in zensical.toml.
- Add .gitattributes marking docs/assets/javascripts/** as binary
so PR diffs for vendored files stay readable.
- Add a "Verify vendored Mermaid" step to the docs workflow so
drift between the committed file and the pinned sha256 fails CI.
- Document the vendoring convention and upgrade procedure in
CONTRIBUTING.md under "Vendored dependencies".
Affected pages: getting-started/development-environment,
sdk-reference/operations/{invoke,wait-for-condition,callback},
testing/runner.
Closes #152
wangyb-A
approved these changes
Apr 28, 2026
github-project-automation
Bot
moved this from In review
to Done
in aws-durable-execution
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description of changes:
Mermaid diagrams render as raw text on docs.aws.amazon.com because the site's Content Security Policy blocks Zensical's default load of mermaid from unpkg.com. The same pages work on localhost only because localhost has no CSP.
Switch to self-hosting the @mermaid-js/tiny UMD build, which ships as a single file with no lazy-loaded chunks and supports all diagram types currently in use (flowchart, sequence, state, class, entity-relationship).
Affected pages: getting-started/development-environment, sdk-reference/operations/{invoke,wait-for-condition,callback}, testing/runner.
Issue #, if available:
Closes #152
By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.