Skip to content

Commit 9274290

Browse files
pawamoypawamoy
committed
docs: Document ANSI support
1 parent 27743c2 commit 9274290

File tree

3 files changed

+320
-2
lines changed

3 files changed

+320
-2
lines changed

‎docs/usage/shell.md

Lines changed: 313 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -53,3 +53,316 @@ If the exit code is different than the one specified
5353
with `returncode`, it will be considered a failure,
5454
its output will be renderer anyway (stdout and stderr combined),
5555
and a warning will be logged in the MkDocs output.
56+
57+
## Support for ANSI colors
58+
59+
If you installed Markdown Exec with the `ansi` extra (`pip install markdown-exec[ansi]`),
60+
the ANSI colors in the output of shell commands will be translated to HTML/CSS,
61+
allowing to render them naturally in your documentation pages.
62+
63+
64+
To enable ANSI colors in the output of a code block, use the
65+
[`result="ansi"` option](http://localhost:8000/markdown-exec/usage/#wrap-result-in-a-code-block).
66+
67+
````md exec="true" source="tabbed-left" title="ANSI terminal output"
68+
```bash exec="true" result="ansi"
69+
--8<-- "gallery/ansi.sh"
70+
```
71+
````
72+
73+
/// admonition
74+
type: warning
75+
76+
Unless you enable Markdown Exec through our MkDocs plugin,
77+
you will need to provide your own CSS rules. How to do that
78+
depends on the tool(s) you use to convert Markdown to HTML,
79+
so we cannot provide generic guidance here.
80+
81+
82+
//// details | CSS rules used by our MkDocs plugin
83+
type: example
84+
85+
```css
86+
/*
87+
Inspired by https://spec.draculatheme.com/ specification, they should work
88+
decently with both dark and light themes.
89+
*/
90+
:root {
91+
--ansi-red: #ff5555;
92+
--ansi-green: #50fa7b;
93+
--ansi-blue: #265285;
94+
--ansi-yellow: #ffb86c;
95+
--ansi-magenta: #bd93f9;
96+
--ansi-cyan: #8be9fd;
97+
--ansi-black: #282a36;
98+
--ansi-white: #f8f8f2;
99+
}
100+
101+
.-Color-Green,
102+
.-Color-Faint-Green,
103+
.-Color-Bold-Green {
104+
color: var(--ansi-green);
105+
}
106+
107+
.-Color-Red,
108+
.-Color-Faint-Red,
109+
.-Color-Bold-Red {
110+
color: var(--ansi-red);
111+
}
112+
113+
.-Color-Yellow,
114+
.-Color-Faint-Yellow,
115+
.-Color-Bold-Yellow {
116+
color: var(--ansi-yellow);
117+
}
118+
119+
.-Color-Blue,
120+
.-Color-Faint-Blue,
121+
.-Color-Bold-Blue {
122+
color: var(--ansi-blue);
123+
}
124+
125+
.-Color-Magenta,
126+
.-Color-Faint-Magenta,
127+
.-Color-Bold-Magenta {
128+
color: var(--ansi-magenta);
129+
}
130+
131+
.-Color-Cyan,
132+
.-Color-Faint-Cyan,
133+
.-Color-Bold-Cyan {
134+
color: var(--ansi-cyan);
135+
}
136+
137+
.-Color-White,
138+
.-Color-Faint-White,
139+
.-Color-Bold-White {
140+
color: var(--ansi-white);
141+
}
142+
143+
.-Color-Black,
144+
.-Color-Faint-Black,
145+
.-Color-Bold-Black {
146+
color: var(--ansi-black);
147+
}
148+
149+
.-Color-Faint {
150+
opacity: 0.5;
151+
}
152+
153+
.-Color-Bold {
154+
font-weight: bold;
155+
}
156+
157+
.-Color-BGBlack,
158+
.-Color-Black-BGBlack,
159+
.-Color-Blue-BGBlack,
160+
.-Color-Bold-BGBlack,
161+
.-Color-Bold-Black-BGBlack,
162+
.-Color-Bold-Green-BGBlack,
163+
.-Color-Bold-Cyan-BGBlack,
164+
.-Color-Bold-Blue-BGBlack,
165+
.-Color-Bold-Magenta-BGBlack,
166+
.-Color-Bold-Red-BGBlack,
167+
.-Color-Bold-White-BGBlack,
168+
.-Color-Bold-Yellow-BGBlack,
169+
.-Color-Cyan-BGBlack,
170+
.-Color-Green-BGBlack,
171+
.-Color-Magenta-BGBlack,
172+
.-Color-Red-BGBlack,
173+
.-Color-White-BGBlack,
174+
.-Color-Yellow-BGBlack {
175+
background-color: var(--ansi-black);
176+
}
177+
178+
.-Color-BGRed,
179+
.-Color-Black-BGRed,
180+
.-Color-Blue-BGRed,
181+
.-Color-Bold-BGRed,
182+
.-Color-Bold-Black-BGRed,
183+
.-Color-Bold-Green-BGRed,
184+
.-Color-Bold-Cyan-BGRed,
185+
.-Color-Bold-Blue-BGRed,
186+
.-Color-Bold-Magenta-BGRed,
187+
.-Color-Bold-Red-BGRed,
188+
.-Color-Bold-White-BGRed,
189+
.-Color-Bold-Yellow-BGRed,
190+
.-Color-Cyan-BGRed,
191+
.-Color-Green-BGRed,
192+
.-Color-Magenta-BGRed,
193+
.-Color-Red-BGRed,
194+
.-Color-White-BGRed,
195+
.-Color-Yellow-BGRed {
196+
background-color: var(--ansi-red);
197+
}
198+
199+
.-Color-BGGreen,
200+
.-Color-Black-BGGreen,
201+
.-Color-Blue-BGGreen,
202+
.-Color-Bold-BGGreen,
203+
.-Color-Bold-Black-BGGreen,
204+
.-Color-Bold-Green-BGGreen,
205+
.-Color-Bold-Cyan-BGGreen,
206+
.-Color-Bold-Blue-BGGreen,
207+
.-Color-Bold-Magenta-BGGreen,
208+
.-Color-Bold-Red-BGGreen,
209+
.-Color-Bold-White-BGGreen,
210+
.-Color-Bold-Yellow-BGGreen,
211+
.-Color-Cyan-BGGreen,
212+
.-Color-Green-BGGreen,
213+
.-Color-Magenta-BGGreen,
214+
.-Color-Red-BGGreen,
215+
.-Color-White-BGGreen,
216+
.-Color-Yellow-BGGreen {
217+
background-color: var(--ansi-green);
218+
}
219+
220+
.-Color-BGYellow,
221+
.-Color-Black-BGYellow,
222+
.-Color-Blue-BGYellow,
223+
.-Color-Bold-BGYellow,
224+
.-Color-Bold-Black-BGYellow,
225+
.-Color-Bold-Green-BGYellow,
226+
.-Color-Bold-Cyan-BGYellow,
227+
.-Color-Bold-Blue-BGYellow,
228+
.-Color-Bold-Magenta-BGYellow,
229+
.-Color-Bold-Red-BGYellow,
230+
.-Color-Bold-White-BGYellow,
231+
.-Color-Bold-Yellow-BGYellow,
232+
.-Color-Cyan-BGYellow,
233+
.-Color-Green-BGYellow,
234+
.-Color-Magenta-BGYellow,
235+
.-Color-Red-BGYellow,
236+
.-Color-White-BGYellow,
237+
.-Color-Yellow-BGYellow {
238+
background-color: var(--ansi-yellow);
239+
}
240+
241+
.-Color-BGBlue,
242+
.-Color-Black-BGBlue,
243+
.-Color-Blue-BGBlue,
244+
.-Color-Bold-BGBlue,
245+
.-Color-Bold-Black-BGBlue,
246+
.-Color-Bold-Green-BGBlue,
247+
.-Color-Bold-Cyan-BGBlue,
248+
.-Color-Bold-Blue-BGBlue,
249+
.-Color-Bold-Magenta-BGBlue,
250+
.-Color-Bold-Red-BGBlue,
251+
.-Color-Bold-White-BGBlue,
252+
.-Color-Bold-Yellow-BGBlue,
253+
.-Color-Cyan-BGBlue,
254+
.-Color-Green-BGBlue,
255+
.-Color-Magenta-BGBlue,
256+
.-Color-Red-BGBlue,
257+
.-Color-White-BGBlue,
258+
.-Color-Yellow-BGBlue {
259+
background-color: var(--ansi-blue);
260+
}
261+
262+
.-Color-BGMagenta,
263+
.-Color-Black-BGMagenta,
264+
.-Color-Blue-BGMagenta,
265+
.-Color-Bold-BGMagenta,
266+
.-Color-Bold-Black-BGMagenta,
267+
.-Color-Bold-Green-BGMagenta,
268+
.-Color-Bold-Cyan-BGMagenta,
269+
.-Color-Bold-Blue-BGMagenta,
270+
.-Color-Bold-Magenta-BGMagenta,
271+
.-Color-Bold-Red-BGMagenta,
272+
.-Color-Bold-White-BGMagenta,
273+
.-Color-Bold-Yellow-BGMagenta,
274+
.-Color-Cyan-BGMagenta,
275+
.-Color-Green-BGMagenta,
276+
.-Color-Magenta-BGMagenta,
277+
.-Color-Red-BGMagenta,
278+
.-Color-White-BGMagenta,
279+
.-Color-Yellow-BGMagenta {
280+
background-color: var(--ansi-magenta);
281+
}
282+
283+
.-Color-BGCyan,
284+
.-Color-Black-BGCyan,
285+
.-Color-Blue-BGCyan,
286+
.-Color-Bold-BGCyan,
287+
.-Color-Bold-Black-BGCyan,
288+
.-Color-Bold-Green-BGCyan,
289+
.-Color-Bold-Cyan-BGCyan,
290+
.-Color-Bold-Blue-BGCyan,
291+
.-Color-Bold-Magenta-BGCyan,
292+
.-Color-Bold-Red-BGCyan,
293+
.-Color-Bold-White-BGCyan,
294+
.-Color-Bold-Yellow-BGCyan,
295+
.-Color-Cyan-BGCyan,
296+
.-Color-Green-BGCyan,
297+
.-Color-Magenta-BGCyan,
298+
.-Color-Red-BGCyan,
299+
.-Color-White-BGCyan,
300+
.-Color-Yellow-BGCyan {
301+
background-color: var(--ansi-cyan);
302+
}
303+
304+
.-Color-BGWhite,
305+
.-Color-Black-BGWhite,
306+
.-Color-Blue-BGWhite,
307+
.-Color-Bold-BGWhite,
308+
.-Color-Bold-Black-BGWhite,
309+
.-Color-Bold-Green-BGWhite,
310+
.-Color-Bold-Cyan-BGWhite,
311+
.-Color-Bold-Blue-BGWhite,
312+
.-Color-Bold-Magenta-BGWhite,
313+
.-Color-Bold-Red-BGWhite,
314+
.-Color-Bold-White-BGWhite,
315+
.-Color-Bold-Yellow-BGWhite,
316+
.-Color-Cyan-BGWhite,
317+
.-Color-Green-BGWhite,
318+
.-Color-Magenta-BGWhite,
319+
.-Color-Red-BGWhite,
320+
.-Color-White-BGWhite,
321+
.-Color-Yellow-BGWhite {
322+
background-color: var(--ansi-white);
323+
}
324+
325+
.-Color-Black,
326+
.-Color-Bold-Black,
327+
.-Color-Black-BGBlack,
328+
.-Color-Bold-Black-BGBlack,
329+
.-Color-Black-BGGreen,
330+
.-Color-Red-BGRed,
331+
.-Color-Bold-Red-BGRed,
332+
.-Color-Bold-Blue-BGBlue,
333+
.-Color-Blue-BGBlue {
334+
text-shadow: 0 0 1px var(--ansi-white);
335+
}
336+
337+
.-Color-Bold-Cyan-BGCyan,
338+
.-Color-Bold-Magenta-BGMagenta,
339+
.-Color-Bold-White,
340+
.-Color-Bold-Yellow-BGYellow,
341+
.-Color-Bold-Green-BGGreen,
342+
.-Color-Cyan-BGCyan,
343+
.-Color-Cyan-BGGreen,
344+
.-Color-Green-BGCyan,
345+
.-Color-Green-BGGreen,
346+
.-Color-Magenta-BGMagenta,
347+
.-Color-White,
348+
.-Color-White-BGWhite,
349+
.-Color-Yellow-BGYellow {
350+
text-shadow: 0 0 1px var(--ansi-black);
351+
}
352+
```
353+
354+
////
355+
356+
///
357+
358+
359+
> IMPORTANT: We also recommend setting `ansi: required` in `mkdocs.yml`
360+
> when using our MkDocs plugin and enabling ANSI support,
361+
> to help tools like MkDocs and its `get-deps` command
362+
> know that the `ansi` extra dependency is required.
363+
>
364+
> ```yaml
365+
> plugins:
366+
> - markdown-exec:
367+
> ansi: required
368+
> ```

‎mkdocs.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -93,6 +93,8 @@ markdown_extensions:
9393
strip_period: false
9494
- footnotes
9595
- md_in_html
96+
- pymdownx.blocks.admonition
97+
- pymdownx.blocks.details
9698
- pymdownx.emoji:
9799
emoji_index: !!python/name:material.extensions.emoji.twemoji
98100
emoji_generator: !!python/name:material.extensions.emoji.to_svg

‎src/markdown_exec/mkdocs_plugin.py

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -49,9 +49,12 @@ def _get_logger(name: str) -> _LoggerAdapter:
4949
class MarkdownExecPluginConfig(Config):
5050
"""Configuration of the plugin (for `mkdocs.yml`)."""
5151

52-
ansi: str | bool = config_options.Choice(("auto", "off", "required", True, False), default="auto")
52+
ansi = config_options.Choice(("auto", "off", "required", True, False), default="auto")
5353
"""Whether the `ansi` extra is required when installing the package."""
54-
languages: list[str] = config_options.ListOfItems(config_options.Choice(formatters.keys()), default=list(formatters.keys()))
54+
languages = config_options.ListOfItems(
55+
config_options.Choice(formatters.keys()),
56+
default=list(formatters.keys()),
57+
)
5558
"""Which languages to enabled the extension for."""
5659

5760

0 commit comments

Comments
 (0)