Skip to content

Commit bd0c1ac

Browse files
tonytony
committed
mcp(docs[_static]): restore prompt / agent-thought / server-prompt styling lost in gp-sphinx migration
Commit ``c822f02`` deleted ``docs/_static/css/custom.css`` when adopting gp-sphinx, which dropped 618 lines of CSS — including the project-specific admonition classes that make ``docs/recipes.md`` and ``docs/topics/prompting.md`` readable: * ``.admonition.prompt`` — speech-bubble prompt block (💬 icon, accent border, italicized body) * ``.admonition.agent-thought`` — muted gray-bar "narration" aesthetic * ``span.prompt`` — inline italic with curly quotes * ``div.system-prompt`` / ``div.server-prompt`` — labeled dark code panels The behavior piece (``prompt-copy.js`` + ``copybutton_selector``) survived the migration, so copy-on-prompt still worked; only the *visual cue* that made these blocks look distinct was gone. Every ``:class: prompt`` admonition and every ``[...]{.prompt}`` inline span was rendering as a plain admonition / plain italics. Restored the rules verbatim from ``git show c822f02^:docs/_static/css/custom.css`` into a new ``docs/_static/css/project-admonitions.css`` — named to signal intent (these are libtmux-mcp-specific classes, not theme overrides) — and registered via ``app.add_css_file()`` in ``conf.py::setup`` alongside the existing ``app.add_js_file("js/prompt-copy.js")`` registration so order is deterministic (project CSS loads after ``_gp_setup(app)`` runs). gp-sphinx's ``merge_sphinx_config`` does not set ``html_css_files`` and its ``setup()`` only adds ``js/spa-nav.js``, so there is no collision risk with upstream theme CSS. ``DEFAULT_HTML_STATIC_PATH = ["_static"]`` already covers serving files from ``docs/_static/``.
1 parent 68cb272 commit bd0c1ac

2 files changed

Lines changed: 185 additions & 1 deletion

File tree

‎docs/_static/css/project-admonitions.css‎

Lines changed: 183 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,183 @@
1+
/* Project-specific admonition styling for libtmux-mcp docs.
2+
*
3+
* These classes are *semantic* extensions added by the project and are not
4+
* shipped by the gp-sphinx theme, so they live here rather than upstream.
5+
* Restored from the pre-gp-sphinx-migration ``custom.css`` (commit c822f02^).
6+
*
7+
* .admonition.prompt — chat-bubble prompts (user → LLM)
8+
* .admonition.agent-thought — gray-bar agent chain-of-thought narration
9+
* span.prompt — inline italic prompt with curly quotes
10+
* div.system-prompt,
11+
* div.server-prompt — labeled dark code panels for AGENTS.md /
12+
* server-emitted prompts
13+
*/
14+
15+
/* ── Prompt blocks (user → LLM) ───────────────────────────
16+
* Styled admonition for copy-paste prompts. Chat-bubble
17+
* aesthetic with speech icon. Says "type this into your LLM."
18+
* ────────────────────────────────────────────────────────── */
19+
div.admonition.prompt {
20+
border: 1px solid color-mix(in srgb, var(--color-link) 25%, transparent);
21+
border-left: 3px solid var(--color-link);
22+
background: color-mix(in srgb, var(--color-link) 4%, var(--color-background-primary));
23+
border-radius: 6px;
24+
padding: 0.75rem 1rem 0.75rem 2.2rem;
25+
margin: 1.25rem 0;
26+
box-shadow: none;
27+
position: relative;
28+
}
29+
30+
/* Speech bubble icon */
31+
div.admonition.prompt::before {
32+
content: "\1F4AC";
33+
position: absolute;
34+
left: 0.65rem;
35+
top: 0.7rem;
36+
font-size: 0.85rem;
37+
line-height: 1;
38+
opacity: 0.45;
39+
}
40+
41+
div.admonition.prompt > .admonition-title {
42+
display: none;
43+
}
44+
45+
div.admonition.prompt > p {
46+
font-size: 0.95rem;
47+
font-style: italic;
48+
color: var(--color-foreground-primary);
49+
}
50+
51+
div.admonition.prompt > p:last-of-type {
52+
margin-bottom: 0;
53+
}
54+
55+
/* Copy button — inserted afterend of p:last-child, so it
56+
* lands inside the prompt div. position:relative on the
57+
* prompt div provides the positioning context. */
58+
div.admonition.prompt > button.copybtn {
59+
background: transparent !important;
60+
cursor: pointer;
61+
border: none !important;
62+
}
63+
64+
div.admonition.prompt:hover > button.copybtn,
65+
div.admonition.prompt > button.copybtn.success {
66+
opacity: 1;
67+
}
68+
69+
div.admonition.prompt > p:last-child {
70+
margin-bottom: 0;
71+
}
72+
73+
/* ── Agent reasoning blocks ──────────────────────────────
74+
* Styled admonition for agent chain-of-thought. Neutral
75+
* gray bar + italic + muted opacity = "internal narration,
76+
* not something you do."
77+
* ────────────────────────────────────────────────────────── */
78+
div.admonition.agent-thought {
79+
border: none;
80+
border-left: 3px solid var(--color-foreground-border);
81+
background: transparent;
82+
padding: 0.6rem 1rem;
83+
margin: 1rem 0;
84+
box-shadow: none;
85+
}
86+
87+
div.admonition.agent-thought > .admonition-title {
88+
display: none;
89+
}
90+
91+
div.admonition.agent-thought > p {
92+
font-style: italic;
93+
color: var(--color-foreground-secondary);
94+
font-size: 0.9rem;
95+
}
96+
97+
div.admonition.agent-thought > p:last-child {
98+
margin-bottom: 0;
99+
}
100+
101+
/* ── Inline prompt dialog ────────────────────────────────
102+
* Inline styled span for user-to-LLM prompts. Supports
103+
* full nested markup via MyST attrs_inline extension:
104+
* [Run `pytest` in my build pane]{.prompt}
105+
* No line-height or word-wrap disruption. WCAG AA contrast.
106+
* ────────────────────────────────────────────────────────── */
107+
span.prompt {
108+
font-style: italic;
109+
color: var(--color-foreground-primary);
110+
}
111+
112+
span.prompt::before {
113+
content: "\201C";
114+
color: var(--color-foreground-muted);
115+
}
116+
117+
span.prompt::after {
118+
content: "\201D";
119+
color: var(--color-foreground-muted);
120+
}
121+
122+
/* ── Labeled code panels ─────────────────────────────────
123+
* Copyable prose in labeled dark panels. Two variants:
124+
* .system-prompt — user-authored fragments for AGENTS.md
125+
* .server-prompt — libtmux-mcp's built-in instructions
126+
* Keeps sphinx-copybutton via .highlight > pre selector.
127+
* ────────────────────────────────────────────────────────── */
128+
div.system-prompt,
129+
div.server-prompt {
130+
margin: 1.25rem 0;
131+
position: relative;
132+
}
133+
134+
div.system-prompt > div.highlight,
135+
div.server-prompt > div.highlight {
136+
background: #1f2329 !important;
137+
border: 1px solid color-mix(in srgb, var(--color-link) 20%, transparent);
138+
border-left: 3px solid var(--color-link);
139+
border-radius: 6px;
140+
position: relative;
141+
padding-top: 1.3rem;
142+
}
143+
144+
div.system-prompt > div.highlight > pre,
145+
div.server-prompt > div.highlight > pre {
146+
background: transparent;
147+
font-size: 13px;
148+
line-height: 1.6;
149+
white-space: pre-wrap;
150+
word-break: break-word;
151+
}
152+
153+
/* Internal label — quiet uppercase whisper */
154+
div.system-prompt > div.highlight::before,
155+
div.server-prompt > div.highlight::before {
156+
position: absolute;
157+
top: 0.45rem;
158+
left: 0.85rem;
159+
font-family: var(--font-stack);
160+
font-size: 0.55rem;
161+
font-weight: 500;
162+
letter-spacing: 0.05em;
163+
text-transform: uppercase;
164+
color: #9590b8;
165+
background: transparent;
166+
padding: 0;
167+
line-height: 1;
168+
opacity: 0.8;
169+
}
170+
171+
div.system-prompt > div.highlight::before {
172+
content: "System prompt";
173+
}
174+
175+
div.server-prompt > div.highlight::before {
176+
content: "Built-in server prompt";
177+
}
178+
179+
/* Fix copy button background to match panel */
180+
div.system-prompt .copybtn,
181+
div.server-prompt .copybtn {
182+
background: #1f2329 !important;
183+
}

‎docs/conf.py‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -125,10 +125,11 @@ def _convert_md_xrefs(
125125

126126

127127
def setup(app: Sphinx) -> None:
128-
"""Configure Sphinx app hooks and register project-specific JS."""
128+
"""Configure Sphinx app hooks and register project-specific JS/CSS."""
129129
_gp_setup(app)
130130
app.connect("autodoc-process-docstring", _convert_md_xrefs)
131131
app.add_js_file("js/prompt-copy.js", loading_method="defer")
132+
app.add_css_file("css/project-admonitions.css")
132133

133134

134135
globals().update(conf)

0 commit comments

Comments
 (0)