Skip to content

fix(docs): align code block styles for shell snippets #15661

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

Open
wants to merge 1 commit into
base: master
Choose a base branch
from

Conversation

motorailgun
Copy link
Contributor

What does this PR try to resolve?

Current contributor document has inconsistent styles for shell-command snippets, like with or without leading $. This PR removes all leading $ and specify bash for syntax highlighting, for the ease of copy-pasting commands.

@rustbot
Copy link
Collaborator

rustbot commented Jun 13, 2025

r? @weihanglo

rustbot has assigned @weihanglo.
They will have a look at your PR within the next two weeks and either review your PR or reassign to another reviewer.

Use r? to explicitly pick a reviewer

@rustbot rustbot added A-documenting-cargo-itself Area: Cargo's documentation S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Jun 13, 2025
Comment on lines +11 to 14
```bash
# Outputs all logs with levels debug and higher
CARGO_LOG=debug cargo generate-lockfile

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I tend to lean towards console blocks for commands

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fair point as it feels shell-independent. Will fix those!

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Umm, I thought so, but seems like bash blocks works better (in terms of syntax highlighting) for multi-line commands with comments like this. How do you think about that...?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've tended to do $ #. Not great but I feel its more semantically correct than describing these as bash scripts (which is what bash means). Unsure if others have other opinions.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That sounds fair, however for especially one-liner like this, I'd prefer the ease of copy-pasting by removing leading $:

```console
$ SNAPSHOTS=overwrite cargo test
```

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I see that as a tooling limitation and I personally still lean towards console

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
A-documenting-cargo-itself Area: Cargo's documentation S-waiting-on-review Status: Awaiting review from the assignee but also interested parties.
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants