Skip to content

Commit a870456

Browse files
localdenlocalden
authored
fix(readme): use picture element for theme-aware logo (#545)
* fix(readme): use picture element for theme-aware logo 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. * ci: add Cloudflare Pages preview for docs PRs 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). * fix(docs): sync README logo with TypeDoc theme switcher 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).
1 parent a2d2d8c commit a870456

4 files changed

Lines changed: 190 additions & 81 deletions

File tree

‎.github/workflows/docs-preview.yml‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
name: Docs Preview
2+
3+
on:
4+
pull_request:
5+
types: [opened, synchronize, reopened, closed]
6+
paths:
7+
- "docs/**"
8+
- "src/**"
9+
- "README.md"
10+
- "typedoc.config.mjs"
11+
- "scripts/typedoc-*.mjs"
12+
- ".github/workflows/docs-preview.yml"
13+
14+
permissions:
15+
contents: read
16+
pull-requests: write
17+
18+
concurrency:
19+
group: docs-preview-${{ github.event.pull_request.number }}
20+
cancel-in-progress: true
21+
22+
jobs:
23+
build-and-deploy:
24+
# Refuse to run for fork PRs — forks do not have access to the Cloudflare
25+
# secrets, so deploys would fail anyway.
26+
if: >-
27+
github.event.action != 'closed' &&
28+
github.event.pull_request.head.repo.full_name == github.repository
29+
runs-on: ubuntu-latest
30+
steps:
31+
- uses: actions/checkout@v6
32+
33+
- uses: actions/setup-node@v6
34+
with:
35+
node-version: "22"
36+
cache: npm
37+
38+
- run: npm ci
39+
40+
- run: npm run build
41+
42+
- run: npm run docs
43+
44+
- name: Deploy preview
45+
uses: modelcontextprotocol/actions/cloudflare-pages-preview/deploy@main
46+
with:
47+
directory: docs
48+
project-name: mcp-ext-apps-docs-preview
49+
api-token: ${{ secrets.CF_PAGES_PREVIEW_API_TOKEN }}
50+
account-id: ${{ secrets.CF_PAGES_PREVIEW_ACCOUNT_ID }}
51+
comment-title: "📖 Docs Preview Deployed"
52+
comment-marker: "<!-- docs-preview-comment -->"
53+
54+
cleanup:
55+
if: >-
56+
github.event.action == 'closed' &&
57+
github.event.pull_request.head.repo.full_name == github.repository
58+
runs-on: ubuntu-latest
59+
steps:
60+
- uses: modelcontextprotocol/actions/cloudflare-pages-preview/cleanup@main
61+
with:
62+
project-name: mcp-ext-apps-docs-preview
63+
api-token: ${{ secrets.CF_PAGES_PREVIEW_API_TOKEN }}
64+
account-id: ${{ secrets.CF_PAGES_PREVIEW_ACCOUNT_ID }}
65+
comment-marker: "<!-- docs-preview-comment -->"

‎README.md‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,10 @@
11
<!-- LOGO -->
22
<div align="center">
3-
<img src="media/mcp.svg#gh-light-mode-only" alt="MCP Apps" width="128">
4-
<img src="media/mcp-white.svg#gh-dark-mode-only" alt="MCP Apps" width="128">
3+
<picture>
4+
<source media="(prefers-color-scheme: dark)" srcset="media/mcp-white.svg">
5+
<source media="(prefers-color-scheme: light)" srcset="media/mcp.svg">
6+
<img src="media/mcp.svg" alt="MCP Apps" width="128">
7+
</picture>
58
<h1>MCP Apps</h1>
69
<p>
710
Build interactive UIs for MCP tools — charts, forms, dashboards — that render inline in Claude, ChatGPT and any other compliant chat client.

‎docs/mcp-theme.css‎

Lines changed: 106 additions & 79 deletions
Original file line numberDiff line numberDiff line change
@@ -2,169 +2,196 @@
22
* MCP Apps custom theme — aligns TypeDoc styling with modelcontextprotocol.io
33
*/
44

5-
@import url('https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500&display=swap');
5+
@import url("https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500&display=swap");
66

77
/* ------------------------------------------------------------------ */
88
/* Fonts */
99
/* ------------------------------------------------------------------ */
1010

1111
:root {
12-
--font-family-text: 'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
13-
--font-family-code: 'JetBrains Mono', ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
12+
--font-family-text:
13+
"Inter", -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
14+
--font-family-code:
15+
"JetBrains Mono", ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
1416
}
1517

1618
body {
17-
font-family: var(--font-family-text);
18-
-webkit-font-smoothing: antialiased;
19-
-moz-osx-font-smoothing: grayscale;
19+
font-family: var(--font-family-text);
20+
-webkit-font-smoothing: antialiased;
21+
-moz-osx-font-smoothing: grayscale;
2022
}
2123

2224
/* ------------------------------------------------------------------ */
2325
/* Light mode colors */
2426
/* ------------------------------------------------------------------ */
2527

2628
:root {
27-
--light-color-background: #ffffff;
28-
--light-color-background-secondary: #f9fafb;
29-
--light-color-background-navbar: #ffffff;
30-
--light-color-accent: #e5e7eb;
31-
--light-color-text: #111827;
32-
--light-color-text-aside: #6b7280;
29+
--light-color-background: #ffffff;
30+
--light-color-background-secondary: #f9fafb;
31+
--light-color-background-navbar: #ffffff;
32+
--light-color-accent: #e5e7eb;
33+
--light-color-text: #111827;
34+
--light-color-text-aside: #6b7280;
3335
}
3436

3537
/* ------------------------------------------------------------------ */
3638
/* Dark mode colors */
3739
/* ------------------------------------------------------------------ */
3840

3941
:root {
40-
--dark-color-background: #0f1117;
41-
--dark-color-background-secondary: #161b22;
42-
--dark-color-background-navbar: #0f1117;
43-
--dark-color-accent: #30363d;
44-
--dark-color-text: #f0f6fc;
45-
--dark-color-text-aside: #8b949e;
42+
--dark-color-background: #0f1117;
43+
--dark-color-background-secondary: #161b22;
44+
--dark-color-background-navbar: #0f1117;
45+
--dark-color-accent: #30363d;
46+
--dark-color-text: #f0f6fc;
47+
--dark-color-text-aside: #8b949e;
4648
}
4749

4850
/* ------------------------------------------------------------------ */
4951
/* Header — taller, frosted glass */
5052
/* ------------------------------------------------------------------ */
5153

5254
:root {
53-
--dim-toolbar-contents-height: 3.5rem;
55+
--dim-toolbar-contents-height: 3.5rem;
5456
}
5557

5658
.tsd-page-toolbar {
57-
backdrop-filter: blur(12px);
58-
-webkit-backdrop-filter: blur(12px);
59+
backdrop-filter: blur(12px);
60+
-webkit-backdrop-filter: blur(12px);
5961
}
6062

6163
@media (prefers-color-scheme: light) {
62-
.tsd-page-toolbar {
63-
background-color: rgba(255, 255, 255, 0.85);
64-
}
64+
.tsd-page-toolbar {
65+
background-color: rgba(255, 255, 255, 0.85);
66+
}
6567
}
6668

6769
@media (prefers-color-scheme: dark) {
68-
.tsd-page-toolbar {
69-
background-color: rgba(15, 17, 23, 0.75);
70-
}
70+
.tsd-page-toolbar {
71+
background-color: rgba(15, 17, 23, 0.75);
72+
}
7173
}
7274

73-
:root[data-theme='light'] .tsd-page-toolbar {
74-
background-color: rgba(255, 255, 255, 0.85);
75+
:root[data-theme="light"] .tsd-page-toolbar {
76+
background-color: rgba(255, 255, 255, 0.85);
7577
}
7678

77-
:root[data-theme='dark'] .tsd-page-toolbar {
78-
background-color: rgba(15, 17, 23, 0.75);
79+
:root[data-theme="dark"] .tsd-page-toolbar {
80+
background-color: rgba(15, 17, 23, 0.75);
81+
}
82+
83+
/* ------------------------------------------------------------------ */
84+
/* Theme-aware logo (rewritten from README <picture> by mcpstyle plugin) */
85+
/* ------------------------------------------------------------------ */
86+
87+
/* Explicit theme selection via TypeDoc switcher — takes precedence */
88+
:root[data-theme="light"] .mcp-logo-dark,
89+
:root[data-theme="dark"] .mcp-logo-light {
90+
display: none;
91+
}
92+
93+
/* "OS" mode (data-theme='os') follows prefers-color-scheme */
94+
@media (prefers-color-scheme: light) {
95+
:root[data-theme="os"] .mcp-logo-dark {
96+
display: none;
97+
}
98+
}
99+
100+
@media (prefers-color-scheme: dark) {
101+
:root[data-theme="os"] .mcp-logo-light {
102+
display: none;
103+
}
79104
}
80105

81106
/* ------------------------------------------------------------------ */
82107
/* Sidebar navigation (matches modelcontextprotocol.io sidebar) */
83108
/* ------------------------------------------------------------------ */
84109

85110
.tsd-navigation a {
86-
padding: 0.375rem 0.75rem;
87-
font-size: 0.875rem;
88-
line-height: 1.5;
89-
border-radius: 0.75rem;
90-
color: var(--color-text-aside);
91-
transition: background-color 0.15s ease, color 0.15s ease;
111+
padding: 0.375rem 0.75rem;
112+
font-size: 0.875rem;
113+
line-height: 1.5;
114+
border-radius: 0.75rem;
115+
color: var(--color-text-aside);
116+
transition:
117+
background-color 0.15s ease,
118+
color 0.15s ease;
92119
}
93120

94121
.tsd-navigation a:hover:not(.current) {
95-
background-color: rgba(107, 114, 128, 0.05);
96-
color: var(--color-text);
122+
background-color: rgba(107, 114, 128, 0.05);
123+
color: var(--color-text);
97124
}
98125

99126
.tsd-navigation a.current {
100-
background-color: rgba(107, 114, 128, 0.15);
101-
color: var(--color-text);
102-
font-weight: 700;
127+
background-color: rgba(107, 114, 128, 0.15);
128+
color: var(--color-text);
129+
font-weight: 700;
103130
}
104131

105132
/* Group headers (Documents, Security, API Documentation) */
106133
.tsd-accordion-summary > h3 {
107-
font-weight: 600;
108-
font-size: 0.875rem;
109-
letter-spacing: 0.01em;
134+
font-weight: 600;
135+
font-size: 0.875rem;
136+
letter-spacing: 0.01em;
110137
}
111138

112139
.site-menu {
113-
padding: 1.25rem 0;
140+
padding: 1.25rem 0;
114141
}
115142

116143
@media (prefers-color-scheme: dark) {
117-
.tsd-navigation a {
118-
color: var(--color-text-aside);
119-
}
144+
.tsd-navigation a {
145+
color: var(--color-text-aside);
146+
}
120147

121-
.tsd-navigation a:hover:not(.current) {
122-
background-color: rgba(229, 231, 235, 0.05);
123-
color: var(--color-text);
124-
}
148+
.tsd-navigation a:hover:not(.current) {
149+
background-color: rgba(229, 231, 235, 0.05);
150+
color: var(--color-text);
151+
}
125152

126-
.tsd-navigation a.current {
127-
background-color: rgba(229, 231, 235, 0.15);
128-
color: var(--color-text);
129-
font-weight: 700;
130-
}
153+
.tsd-navigation a.current {
154+
background-color: rgba(229, 231, 235, 0.15);
155+
color: var(--color-text);
156+
font-weight: 700;
157+
}
131158
}
132159

133-
:root[data-theme='dark'] .tsd-navigation a {
134-
color: var(--color-text-aside);
160+
:root[data-theme="dark"] .tsd-navigation a {
161+
color: var(--color-text-aside);
135162
}
136163

137-
:root[data-theme='dark'] .tsd-navigation a:hover:not(.current) {
138-
background-color: rgba(229, 231, 235, 0.05);
139-
color: var(--color-text);
164+
:root[data-theme="dark"] .tsd-navigation a:hover:not(.current) {
165+
background-color: rgba(229, 231, 235, 0.05);
166+
color: var(--color-text);
140167
}
141168

142-
:root[data-theme='dark'] .tsd-navigation a.current {
143-
background-color: rgba(229, 231, 235, 0.15);
144-
color: var(--color-text);
145-
font-weight: 700;
169+
:root[data-theme="dark"] .tsd-navigation a.current {
170+
background-color: rgba(229, 231, 235, 0.15);
171+
color: var(--color-text);
172+
font-weight: 700;
146173
}
147174

148175
/* ------------------------------------------------------------------ */
149176
/* Content area */
150177
/* ------------------------------------------------------------------ */
151178

152179
.tsd-typography {
153-
line-height: 1.6;
180+
line-height: 1.6;
154181
}
155182

156183
.tsd-panel.tsd-typography h1 {
157-
margin-top: 0;
158-
padding-bottom: 0.4em;
184+
margin-top: 0;
185+
padding-bottom: 0.4em;
159186
}
160187

161188
.tsd-panel.tsd-typography h2 {
162-
margin-top: 2rem;
163-
padding-bottom: 0.3em;
189+
margin-top: 2rem;
190+
padding-bottom: 0.3em;
164191
}
165192

166193
.tsd-panel.tsd-typography h3 {
167-
margin-top: 1.75rem;
194+
margin-top: 1.75rem;
168195
}
169196

170197
/* ------------------------------------------------------------------ */
@@ -173,17 +200,17 @@ body {
173200

174201
code,
175202
pre {
176-
font-family: var(--font-family-code);
177-
font-size: 1em;
203+
font-family: var(--font-family-code);
204+
font-size: 1em;
178205
}
179206

180207
.tsd-typography pre {
181-
padding: 1rem 1.25rem;
182-
border: 1px solid var(--color-accent);
208+
padding: 1rem 1.25rem;
209+
border: 1px solid var(--color-accent);
183210
}
184211

185212
/* Inline code */
186213
.tsd-typography code:not(pre code) {
187-
padding: 0.15em 0.35em;
188-
font-size: 1em;
214+
padding: 0.15em 0.35em;
215+
font-size: 1em;
189216
}

0 commit comments

Comments
 (0)