Improve shell syntax highlighting - #47
Open
adesso-os wants to merge 1 commit into
Open
Conversation
✅ Deploy Preview for getsops ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
adesso-os
force-pushed
the
feat/code-blocks
branch
from
July 30, 2026 13:25
1b945bb to
31c0f3d
Compare
As is, there are several code blocks with lines prefixed with `$`, indicating to me that they want to mimic a shell session. These code blocks are marked with either `sh` or `bash` tags, to suggest syntax highlighting appropriate for such shell sessions. This doesn't seem ideal, because command output is highlighted just as if it was another shell command. Hugo uses the Chroma syntax highlighter, which provides a dedicated lexer specifically for such scenarios. This change makes use of that lexer to improve the formatting. There were several cases where lines in these code blocks wanted to indicate comments using `#`, which indicates a comment in a shell script. However, because `#` commonly indicates the prompt of a root shell, such lines had to be adjusted to correctly reflect shell usage, where the comment would be entered on the prompt. The type `console` was specifically chosen in favor over other tags (like `bash-session`), because the docsy theme specifically supports this language tag to improve the user experience on such code blocks. The copy-to-clipboard behavior will not copy command output, or the prompt character, in these cases. Signed-off-by: Oliver Salzburg <oliver.salzburg@adesso.de>
adesso-os
force-pushed
the
feat/code-blocks
branch
from
July 30, 2026 13:27
31c0f3d to
f40de40
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
As is, there are several code blocks with lines prefixed with
$, indicating to me that they want to mimic a shell session. These code blocks are marked with eithershorbashtags, to suggest syntax highlighting appropriate for such shell sessions.This doesn't seem ideal, because command output is highlighted just as if it was another shell command.
Before
Hugo uses the Chroma syntax highlighter, which provides a dedicated lexer specifically for such scenarios. This change makes use of that lexer to improve the formatting.
After
There were several cases where lines in these code blocks wanted to indicate comments using
#, which indicates a comment in a shell script. However, because#commonly indicates the prompt of a root shell, such lines had to be adjusted to correctly reflect shell usage, where the comment would be entered on the prompt. This felt weird initially, but the consistent behavior and correctness ultimately made me prefer it.The type
consolewas specifically chosen in favor over other tags (likebash-session), because the docsy theme specifically supports this language tag to improve the user experience on such code blocks. The copy-to-clipboard behavior will not copy command output, or the prompt character, in these cases.https://github.com/google/docsy/blob/62f3ca81a9e4f7fb683e1f94a7ac25cb9236430d/theme/assets/scss/td/_code.scss#L93-L104
Clipboard Content Before
Clipboard Content After
For the more complex usage scenarios in the Advanced Usage section, I switched the prompt prefix to
%to use$for the sub-shell, to align with Chroma expectations.I also applied the
consoletag consistently throughout the code base to encourage adopting this approach, instead of using the other shell types that might feel more appropriate when not used to this specific behavior. It also makes the copy-to-clipboard feature consistently not copy the prompt prefix.