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

Enhance code block formatting #621

Open
4 tasks
felker opened this issue Jan 14, 2025 · 0 comments
Open
4 tasks

Enhance code block formatting #621

felker opened this issue Jan 14, 2025 · 0 comments

Comments

@felker
Copy link
Member

felker commented Jan 14, 2025

Following up from some of the changes I made to the Cerebras CSL page: #601 (comment)
Some of the above changes, and other enhancements to code blocks, should be considered and applied more broadly across our docs:

The "copy to clipboard" button just gets in the way for these types of blocks; I cant imagine any situation in which a reader would want to copy/paste the whole thing:
image

image

It could be useful to condense and make a more readable example script, when combined with explanations for each line, e.g.
image
Would move the below list to code line annotations directly in the script:
image

  • Remove $ prefixes when used for command line instructions
    • Some authors are in the habit of manually adding these for every command line. But for commands that are intended to be copied from our docs for users to run directly, the $ breaks the usefulness of copy-button, and make it harder to manually highlight and copy individual lines.
image

Long term: add a custom code superfence to prefix $ in the left margin, suggested here: squidfunk/mkdocs-material#3427
image

For long example sequences of shell commands and sample output intertwined, it would be messy to enable the copy button to only copy the command lines, excluding the "sample output", without breaking into separate blocks. For example:

image
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