Code and keys¶
Use inline code for literal file names, attributes and values. Use a code block when the reader needs to copy several lines. Keyboard keys describe input; they are not interactive buttons.
A literal name inside prose¶
Put component markup inside .fltheme-components. Add du- to daisyUI
component classes, as in du-btn and du-btn-outline.
<p>Put component markup inside <code>.fltheme-components</code>. Add <code>du-</code> to daisyUI
component classes, as in <code>du-btn</code> and <code>du-btn-outline</code>.</p>Put component markup inside `.fltheme-components`. Add `du-` to daisyUI
component classes, as in `du-btn` and `du-btn-outline`.A copyable code sample¶
The specimen is a rendered code block, so its compiled HTML includes the code block's markup. Copy Markdown to author the same block in another document.
<div class="language-html highlight"><pre><span></span><code><span id="__span-0-1"><a href="#__codelineno-0-1" id="__codelineno-0-1" name="__codelineno-0-1"></a><span class="p"><</span><span class="nt">div</span> <span class="na">class</span><span class="o">=</span><span class="s">"fltheme-components"</span><span class="p">></span>
</span><span id="__span-0-2"><a href="#__codelineno-0-2" id="__codelineno-0-2" name="__codelineno-0-2"></a> <span class="p"><</span><span class="nt">a</span> <span class="na">class</span><span class="o">=</span><span class="s">"du-btn"</span> <span class="na">href</span><span class="o">=</span><span class="s">"https://www.fontlab.com/"</span><span class="p">></span>FontLab<span class="p"></</span><span class="nt">a</span><span class="p">></span>
</span><span id="__span-0-3"><a href="#__codelineno-0-3" id="__codelineno-0-3" name="__codelineno-0-3"></a><span class="p"></</span><span class="nt">div</span><span class="p">></span>
</span></code></pre></div>```html
<div class="fltheme-components">
<a class="du-btn" href="https://www.fontlab.com/">FontLab</a>
</div>
``` This distinction matters in a reference page: the HTML copy reproduces what you see, including displayed code, rather than executing the displayed sample.
Describe keyboard input¶
MaterialX's key notation suits a sentence. Keep the surrounding verb so the reader knows what to do with the key.
Press Tab to move to the next control. Press Shift+Tab to move back.
<p>Press <span class="keys"><kbd class="key-tab">Tab</kbd></span> to move to the next control. Press <span class="keys"><kbd class="key-shift">Shift</kbd><span>+</span><kbd class="key-tab">Tab</kbd></span> to move back.</p>Press ++tab++ to move to the next control. Press ++shift+tab++ to move back.Keep keycaps consistent with nearby controls¶
Basecoat and daisyUI keycaps can appear beside their respective controls. The examples describe browser focus navigation, not a product-specific shortcut.
Next control: Tab
Previous control: Shift + Tab
<div class="fltheme-components fl-pattern-grid">
<p>Next control: <kbd class="kbd">Tab</kbd></p>
<p>Previous control: <kbd class="du-kbd">Shift</kbd> + <kbd class="du-kbd">Tab</kbd></p>
</div>Use text labels in addition to unfamiliar symbols. Avoid presenting a platform-specific shortcut as universal when the two operating systems differ.
Code blocks · MaterialX¶
MaterialX renders this pattern from Markdown. The source panel contains the actual authoring syntax, including attribute lists where they apply. Keep the renderer extensions enabled on the destination.
<div class="language-yaml highlight"><table class="highlighttable"><tbody><tr><th class="filename" colspan="2"><span class="filename">mkdocs.yml</span></th></tr><tr><td class="linenos"><div class="linenodiv"><pre><span></span><span class="normal"><a href="#__codelineno-1-1">1</a></span>
<span class="normal"><a href="#__codelineno-1-2">2</a></span>
<span class="normal"><a href="#__codelineno-1-3">3</a></span></pre></div></td><td class="code"><div><pre><span></span><code><span id="__span-1-1"><a id="__codelineno-1-1" name="__codelineno-1-1"></a><span class="nt">markdown_extensions</span><span class="p">:</span>
</span><span id="__span-1-2"><a id="__codelineno-1-2" name="__codelineno-1-2"></a><span class="hll"><span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">attr_list</span>
</span></span><span id="__span-1-3"><a id="__codelineno-1-3" name="__codelineno-1-3"></a><span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">md_in_html</span>
</span></code></pre></div></td></tr></tbody></table></div>``` yaml title="mkdocs.yml" linenums="1" hl_lines="2"
markdown_extensions:
- attr_list
- md_in_html
``` Syntax and variants in MaterialX
Kbd · Basecoat¶
Use a keyboard element for literal input. Keep the action in the surrounding sentence so the key does not become an unexplained symbol.
Press Tab to move to the next control.
<div class="fltheme-components">
<p>Press <kbd class="kbd">Tab</kbd> to move to the next control.</p>
</div>Syntax and variants in Basecoat
Kbd · daisyUI¶
Use a keyboard element for literal input. Keep the action in the surrounding sentence so the key does not become an unexplained symbol.
Press Tab to move to the next control.
<div class="fltheme-components">
<p>Press <kbd class="du-kbd">Tab</kbd> to move to the next control.</p>
</div>Syntax and variants in daisyUI
Code blocks: authoring details¶
A titled, annotated, downloadable block¶
This one block combines copy, line selection, download, folding, a title, line numbers and a highlighted line. The annotation explains the changed setting. Expand it before copying if you want to inspect every line; copying and downloading retain the complete source regardless of the folded view.
``` yaml title="renderer.yml" linenums="1" hl_lines="5" data-download="blob" data-fold="3" theme: name: materialx code: fold: enabled: true # (1)! lines: 8
1. Fold long examples to shorten a page while retaining their source.
<pre data-example-source="``` yaml title="renderer.yml" linenums="1" hl_lines="5" data-download="blob" data-fold="3"
theme:
name: materialx
code:
fold:
enabled: true # (1)!
lines: 8
- Fold long examples to shorten a page while retaining their source." hidden>
<p>``` yaml title="renderer.yml" linenums="1" hl_lines="5" data-download="blob" data-fold="3"
theme:
name: materialx
code:
fold:
enabled: true # (1)!
lines: 8
</p><div class="language-text highlight"><pre><span></span><code><span id="__span-2-1"><a href="#__codelineno-2-1" id="__codelineno-2-1" name="__codelineno-2-1"></a>1. Fold long examples to shorten a page while retaining their source.
</span><span id="__span-2-2"><a href="#__codelineno-2-2" id="__codelineno-2-2" name="__codelineno-2-2"></a>
</span><span id="__span-2-3"><a href="#__codelineno-2-3" id="__codelineno-2-3" name="__codelineno-2-3"></a><pre data-example-source="``` yaml title=&quot;renderer.yml&quot; linenums=&quot;1&quot; hl_lines=&quot;5&quot; data-download=&quot;blob&quot; data-fold=&quot;3&quot;
</span><span id="__span-2-4"><a href="#__codelineno-2-4" id="__codelineno-2-4" name="__codelineno-2-4"></a>theme:
</span><span id="__span-2-5"><a href="#__codelineno-2-5" id="__codelineno-2-5" name="__codelineno-2-5"></a> name: materialx
</span><span id="__span-2-6"><a href="#__codelineno-2-6" id="__codelineno-2-6" name="__codelineno-2-6"></a> code:
</span><span id="__span-2-7"><a href="#__codelineno-2-7" id="__codelineno-2-7" name="__codelineno-2-7"></a> fold:
</span><span id="__span-2-8"><a href="#__codelineno-2-8" id="__codelineno-2-8" name="__codelineno-2-8"></a> enabled: true # (1)!
</span><span id="__span-2-9"><a href="#__codelineno-2-9" id="__codelineno-2-9" name="__codelineno-2-9"></a> lines: 8
</span></code></pre></div><p></p>
<ol>
<li>Fold long examples to shorten a page while retaining their source." hidden></li>
</ol>Highlight a literal inside prose¶
range(3) produces the indexes 0, 1 and 2.
<p><code class="language-python highlight"><span class="nb">range</span><span class="p">(</span><span class="mi">3</span><span class="p">)</span></code> produces the indexes 0, 1 and 2.</p>`#!python range(3)` produces the indexes 0, 1 and 2.Include tracked source¶
The Markdown snippet refers to a tracked source file. The compiled HTML contains the included code, so it is independent of that file after building.
This sentence is supplied by the local, tracked snippets contract.
<p>This sentence is supplied by the local, tracked snippets contract.</p>--8<-- "includes/renderer-snippet.md:renderer"Show a platform shortcut¶
A macOS command shortcut can be written as ⌘ + K. Use the equivalent named shortcut for other platforms.
<div class="fltheme-components"><p>A macOS command shortcut can be written as <kbd class="kbd">⌘</kbd> + <kbd class="kbd">K</kbd>. Use the equivalent named shortcut for other platforms.</p></div>Code copy button¶
Supported/live: content.code.copy; see
copy action.
Code selection button¶
Adapted/live: content.code.select; see
line selection.
Code download button¶
Adapted/live: material.extensions.code_download; see
download action.
Enable button¶
Enable downloads once in the renderer, then opt a block in with tracked attributes. The button must have a useful accessible name.
Enhanced extension¶
The locked download extension supports blob, local-file, and URL strategies. Use brace-wrapped attributes where Markdown parsing would otherwise be ambiguous.
Code collapse & expand¶
Adapted/live: theme.code.fold.enabled; see
code folding. Keep the first
visible lines sufficient to identify the example.
Change default threshold¶
Set theme.code.fold.lines centrally when most examples need the same
threshold. A threshold changes presentation, never the copied source.
Set individual threshold¶
Use data-fold="N" for an exceptional block. Prefer the shared threshold so
pages do not develop arbitrary folding behaviour.
Disable folding for specific blocks¶
Use data-fold="0" when every line is necessary for comparison or safe use.
Code annotations¶
Supported/live: content.code.annotate; see
code annotations.
Place markers in valid comments for the selected language.
Custom selectors¶
Adapted/live: custom annotation selectors are a renderer-level exception. Prefer ordinary comments; a custom selector must not alter executable text.
Adding a title¶
Supported/live: use title="filename.ext" after the language. A title adds
context but does not replace the surrounding explanation.
Adding annotations¶
Supported/live: put (1) in a language comment and follow the fence with
the matching ordered list.
Stripping comments¶
Supported/live: append ! to a marker when the renderer should remove the
comment characters. Only one stripped annotation may occupy a comment.
Adding line numbers¶
Supported/live: linenums="1" sets the visible starting number. Do not use
line numbers as the only way to identify a statement in prose.
Highlighting specific lines¶
Supported/live: hl_lines="2 4-6" emphasizes lines while keeping all code
available. Explain the significance outside the colour highlight.
Highlighting inline code blocks¶
Supported/live: prefix an inline literal with a lexer shortcode, for
example range(). Use plain inline code when syntax colour adds no
information.
Embedding external files¶
Supported/live: snippets use the tracked --8<-- include notation; see
the canonical include.
Includes must stay inside the documentation source and must build offline.
Custom syntax theme¶
Adapted/live: syntax tokens derive from the active theme. Change token roles in the shared bridge; never add literal per-page colours.
Annotation tooltip width¶
Adapted/live: the shared MaterialX bridge owns tooltip width. If a note outgrows it, edit the note before widening the global component.