Standardize use of Pygments lexers for code block syntax highlighting #676
Labels
mkdocs enhancement
Changes to mkdocs features, mkdocs-material theme, custom theme overrides, etc.
style
subjective design choices, language conventions, how and when to use mkdocs & theme features
(work in progress)
A follow up from my comments #646 (comment)
Our
mkdocs-material
code blocks have enabled the Highlight extension, which uses Pygments for the default syntax highlighter. See https://pygments.org/languages/ for the list of Pygments supported languages/lexers.Here is a quick survey of the fenced triple-backtick code blocks in our current docs source code
bash
=shell
= ...python
=py
=python3
=py3
output
yaml
fortran
julia
cmake
makefile
C
C++
=cpp
markdown
=md
diff
We should be consistent in our application of syntax highlighting, using the correct lexer for all blocks of the same type, etc.
{ .bash .no-copy=1 }
for example output blocks, but it might be more appropriate to use{ .output .no-copy=1 }
since the output of a shell command is usually unformatted ASCII, not Bash codeAlso we should decide on if/how to use https://pygments.org/docs/terminal-sessions/ lexers throughout our docs, since we are often mixing short examples of code and expected output within a single fenced block, chiefly:
shell-session
=console
pycon
=python-console
For example, this following block in our docs:
Renders as the following, and should be switched to

python-console
:Related #621
guess_lang
: https://facelessuser.github.io/pymdown-extensions/extensions/highlight/#options./sophia/not_in_nav/data-science/containers/containers.md
has multiple uses of ```singularity, but I don't think that is valid.ai-testbed/
is the only folder that makes extensive use of ```console, and I havent checked if their usage makes senseThe text was updated successfully, but these errors were encountered: