Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Standardize use of Pygments lexers for code block syntax highlighting #676

Open
5 tasks
felker opened this issue Jan 23, 2025 · 1 comment
Open
5 tasks

Comments

@felker
Copy link
Member

felker commented Jan 23, 2025

(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

We should be consistent in our application of syntax highlighting, using the correct lexer for all blocks of the same type, etc.

  • minor nitpick: authors are starting to use { .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 code

Also 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:

Image Image

For example, this following block in our docs:

```python
>>> import torch
>>> torch.__version__
'2.3.1+cxx11.abi'

Renders as the following, and should be switched to python-console:
Image

Related #621

  • Consider changing some of the current loaded extension options, e.g. 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 sense
  • this needs fixing:
./polaris/applications-and-libraries/applications/vasp.md:154:``` example-script.sh
@felker
Copy link
Member Author

felker commented Jan 23, 2025

strangely, python-console applied to the above example is categorically worse:

Image

felker added a commit that referenced this issue Jan 23, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

1 participant