Warning: This project is in archive mode. The ability to highlight placeholder variables in code blocks is much better addressed either by custom JavaScript or by post-processing the syntax-highlighted block. If you want to see an example of the latter, see the Awesome Sphinx theme.
The awesome sampdirective
extension can be used to highlight placeholder variables in code blocks,
much like Sphinx's samp
interpreted text role.
Install the extension:
pip install sphinxawesome-sampdirective
This Sphinx extension works with Python versions newer than 3.6 and recent Sphinx releases.
To enable this extension in Sphinx, add it to the list of extensions in the Sphinx
configuration file conf.py
:
extensions = ["sphinxawesome.sampdirective"]
Include the directive in your documents:
.. samp::
$ echo {USERNAME}
USERNAME
becomes an emphasized node. In many outputs, it will be rendered as
USERNAME
. For example, in HTML, the above example is rendered as:
<pre>
<span class="gp">$</span> echo <em class="var">USERNAME</em>
</pre>
You can then style the emphasized element with the .var
class in CSS.
If the code block begins with a prompt character (#
, $
, or ~
), they are higlighted as well.
This extension does not provide full syntax highlighting. It is currently not possible to have code blocks with both markup and syntax highlighting. You have to choose between the following:
- If you need to render markup, for example links, bold, or italic text, choose the
parsed-literal
directive. - If you just want to highlight a placeholder variable, use the
samp
directive provided by this extension. - If you need full syntax highlighting, use the
code-block
directive.