Skip to content

Commit 4671b34

Browse files
authored
docs(style): Reorganize code block and formatting sections (#2928)
- Consolidates all guidance related to code block mechanics under a new top-level heading, "Code Blocks Mechanics". - Moves the "Rust Code Formatting" guidance to be a subsection under this new heading. - The rest of the former "Rust Code" section is now directly under "Course Slides". This restructuring improves the logical flow of the style guide by grouping all code-related formatting and tooling conventions into a single, easy-to-find section.
1 parent a6e18b6 commit 4671b34

File tree

1 file changed

+52
-52
lines changed

1 file changed

+52
-52
lines changed

STYLE.md

Lines changed: 52 additions & 52 deletions
Original file line numberDiff line numberDiff line change
@@ -129,33 +129,14 @@ When introducing a new concept, start with a simple, relatable, and concrete
129129
example. A good opening example grounds the concept for the learner and provides
130130
motivation for the more detailed explanation that will follow.
131131

132-
### Rust Code
133-
134-
When showing Rust code inline, please use the same spacing as `rustfmt`: `3 * x`
135-
instead of `3*x`. However, feel free to remove newlines when it can make the
136-
code more compact and easier to understand, e.g., you can define a struct on one
137-
line if it is not the focus of your example:
138-
139-
<!-- dprint-ignore-start -->
140-
141-
```rust
142-
struct Person { name: String }
143-
```
144-
145-
<!-- dprint-ignore-end -->
146-
147-
Enclose the code block in `<!-- dprint-ignore-start -->` and
148-
`<!-- dprint-ignore-end -->` to suppress the automatic formatting. Please use
149-
this sparingly.
150-
151-
#### Use Meaningful Examples
132+
### Use Meaningful Examples
152133

153134
Code samples on the slides should be short and do something meaningful. Avoid
154135
using generic placeholders like `Foo`, `Bar`, and `Baz`. Using descriptive names
155136
from a real-world, even if simplified, domain makes the code easier to
156137
understand and relate to.
157138

158-
#### Interactive Code Snippets
139+
### Plan Interactive Code Snippets
159140

160141
All Rust code blocks in the course are not static text but are live, editable
161142
playgrounds. An important teaching method is for the instructor to edit these
@@ -166,37 +147,6 @@ Contributors should design their slides with this interactivity in mind. The
166147
initial state of the code should be a good starting point for a live
167148
demonstration.
168149

169-
### Code Blocks
170-
171-
Code blocks are a critical part of the course. To ensure they are consistent and
172-
behave as expected, please follow these conventions.
173-
174-
#### Language Identifiers
175-
176-
Use the following language identifiers for fenced code blocks:
177-
178-
- **`rust`**: For Rust code examples.
179-
- **`shell`**: For shell commands. Use a `$` prompt for consistency. Omit the
180-
prompt for multi-line commands or when the output is shown.
181-
- **`bob`**: For ASCII art diagrams generated by `mdbook-bob`.
182-
- **`ignore`**: For code snippets that are not complete, self-contained programs
183-
or are for illustrative purposes only and should not be compiled.
184-
185-
#### mdbook Annotations
186-
187-
You can add annotations to Rust code blocks to control how they are tested and
188-
displayed:
189-
190-
- **`editable`**: Makes the code block an interactive playground where users can
191-
edit and run the code. This should be used for most Rust examples.
192-
- **`compile_fail`**: Indicates that the code is expected to fail compilation.
193-
This is used to demonstrate specific compiler errors.
194-
- **`should_panic`**: Indicates that the code is expected to panic when run.
195-
- **`warnunused`**: Re-enables `unused` lints for a code block. By default, the
196-
course's test runner disables lints for unused variables, imports, etc., to
197-
avoid distracting warnings. Use this annotation only when a warning is part of
198-
the lesson.
199-
200150
### `mdbook` and `mdbook-course` Conventions
201151

202152
The project uses `mdbook` features in specific ways, as well as a custom
@@ -318,6 +268,56 @@ explanation of what the resource contains and why it is relevant. A vague
318268
reference is not helpful, but a specific one can be a great tool for
319269
self-learners.
320270

271+
## Code Blocks Mechanics
272+
273+
Code blocks are a critical part of the course. To ensure they are consistent and
274+
behave as expected, please follow these conventions.
275+
276+
### Language Identifiers
277+
278+
Use the following language identifiers for fenced code blocks:
279+
280+
- **`rust`**: For Rust code examples.
281+
- **`shell`**: For shell commands. Use a `$` prompt for consistency. Omit the
282+
prompt for multi-line commands or when the output is shown.
283+
- **`bob`**: For ASCII art diagrams generated by `mdbook-bob`.
284+
- **`ignore`**: For code snippets that are not complete, self-contained programs
285+
or are for illustrative purposes only and should not be compiled.
286+
287+
### mdbook Annotations
288+
289+
You can add annotations to Rust code blocks to control how they are tested and
290+
displayed:
291+
292+
- **`editable`**: Makes the code block an interactive playground where users can
293+
edit and run the code. This should be used for most Rust examples.
294+
- **`compile_fail`**: Indicates that the code is expected to fail compilation.
295+
This is used to demonstrate specific compiler errors.
296+
- **`should_panic`**: Indicates that the code is expected to panic when run.
297+
- **`warnunused`**: Re-enables `unused` lints for a code block. By default, the
298+
course's test runner disables lints for unused variables, imports, etc., to
299+
avoid distracting warnings. Use this annotation only when a warning is part of
300+
the lesson.
301+
302+
### Rust Code Formatting
303+
304+
When showing Rust code inline, please use the same spacing as `rustfmt`: `3 * x`
305+
instead of `3*x`. However, feel free to remove newlines when it can make the
306+
code more compact and easier to understand, e.g., you can define a struct on one
307+
line if it is not the focus of your example:
308+
309+
<!-- dprint-ignore-start -->
310+
311+
```rust
312+
struct Person { name: String }
313+
```
314+
315+
<!-- dprint-ignore-end -->
316+
317+
Enclose the code block in `<!-- dprint-ignore-start -->` and
318+
`<!-- dprint-ignore-end -->` to suppress the automatic formatting. Please use
319+
this sparingly.
320+
321321
## Translations
322322

323323
This section is about what you write in the translation. We describe

0 commit comments

Comments
 (0)