fix: theme-aware README logo + docs preview CI#545
Merged
Conversation
The #gh-light-mode-only / #gh-dark-mode-only URL fragments only work on github.com. On npm, VS Code preview, and other markdown renderers both img tags render, showing two stacked logos. Switch to <picture> with prefers-color-scheme, which GitHub recommends and which degrades gracefully to a single logo elsewhere.
@modelcontextprotocol/ext-apps
@modelcontextprotocol/server-basic-preact
@modelcontextprotocol/server-basic-react
@modelcontextprotocol/server-basic-solid
@modelcontextprotocol/server-basic-svelte
@modelcontextprotocol/server-basic-vanillajs
@modelcontextprotocol/server-basic-vue
@modelcontextprotocol/server-budget-allocator
@modelcontextprotocol/server-cohort-heatmap
@modelcontextprotocol/server-customer-segmentation
@modelcontextprotocol/server-debug
@modelcontextprotocol/server-map
@modelcontextprotocol/server-pdf
@modelcontextprotocol/server-scenario-modeler
@modelcontextprotocol/server-shadertoy
@modelcontextprotocol/server-sheet-music
@modelcontextprotocol/server-system-monitor
@modelcontextprotocol/server-threejs
@modelcontextprotocol/server-transcript
@modelcontextprotocol/server-video-resource
@modelcontextprotocol/server-wiki-explorer
commit: |
Deploys a per-PR preview of the TypeDoc site to Cloudflare Pages project mcp-ext-apps-docs-preview when docs, src JSDoc, README, or typedoc config change. Uses the shared modelcontextprotocol/actions composite action that injects noindex headers, posts a sticky PR comment with preview URLs, and cleans up deployments on PR close. Fork PRs are skipped (no secret access).
Contributor
PreviewPreview deployments for this PR have been cleaned up. |
The README <picture> logo uses prefers-color-scheme, which only follows the OS setting. TypeDoc's theme switcher sets data-theme on <html>, so manually picking Light/Dark would show the wrong logo (e.g. white logo on light background if OS is dark but user picked Light). Rewrite the <picture> in the generated docs into two class-tagged <img>s via the mcpstyle plugin, and hide the inactive one via CSS keyed on both data-theme (explicit selection) and prefers-color-scheme (OS mode). The README source is unchanged so GitHub/npm still get <picture>. Also: prettier normalized mcp-theme.css (tabs to spaces, quote style).
ochafik
approved these changes
Mar 10, 2026
localden
changed the title
ochafik
added a commit
that referenced
this pull request
Mar 10, 2026
Changes since 1.2.0: - fix: bundle SDK+zod in react-with-deps (was byte-identical to ./react) (#539) - fix(build): copy schema.json to dist and externalize zod (#534) - fix: skip debug log for high-frequency tool-input-partial notifications (#546) - fix(deps): drop @hono/node-server override to patch GHSA-wc8c-qw6v-h7f6 (#535) - fix(readme): use picture element for theme-aware logo (#545) - fix(ci): require maintainer association for /update-snapshots trigger (#532) - fix: pre-commit stages only originally-staged files; add .npmrc (#538) - ci: use npm ci with caching, validate typedoc links, align Node versions (#533) - test: exclude screenshot-gen from default E2E run; wire pdf-server tests (#537)
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.
Summary
Three related changes around README/docs theming:
<picture>element — fix double-logo rendering on npm/VS Code1. README: use
<picture>instead of URL-fragment hackThe README used GitHub's legacy
#gh-light-mode-only/#gh-dark-mode-onlyURL fragments. That only works when github.com's stylesheet is loaded — on npm, VS Code markdown preview, and other renderers the fragments are ignored and both<img>tags render, showing two stacked logos.Switched to
<picture>withprefers-color-schemesources (GitHub's recommended approach). Degrades gracefully to the light logo where<picture>isn't supported.2. Docs site: make the logo follow the TypeDoc theme switcher
<picture>withprefers-color-schemeonly tracks the OS setting. TypeDoc's theme switcher writesdata-theme="light"|"dark"|"os"on<html>, so manually picking Light while the OS is dark would show the white logo on a light background.Fixed in the docs build only (README source unchanged):
typedoc-plugin-mcpstyle.mjsrewrites the<picture>into two class-tagged<img>elementsmcp-theme.csshides the inactive one keyed ondata-theme(explicit selection) andprefers-color-scheme(for"os"mode)Also applied prettier to
mcp-theme.css(tabs → spaces, quote normalization) — it hadn't been formatted before.3. CI: Cloudflare Pages preview for docs PRs
New
.github/workflows/docs-preview.ymldeploys the built TypeDoc site to Cloudflare Pages projectmcp-ext-apps-docs-previewon PRs touchingdocs/**,src/**,README.md, or typedoc config. Uses the sharedmodelcontextprotocol/actions/cloudflare-pages-previewcomposite action:noindexheaders so previews aren't crawledRequires repo secrets:
CF_PAGES_PREVIEW_API_TOKENandCF_PAGES_PREVIEW_ACCOUNT_ID.