You've already forked comprehensive-rust
mirror of
https://github.com/google/comprehensive-rust.git
synced 2025-11-27 16:28:48 +02:00
docs(style): Add mdbook and mdbook-course conventions (#2926)
Adds a new section to STYLE.md to document mandatory conventions for using `mdbook` and the custom `mdbook-course` preprocessor. This section mandates the use of YAML frontmatter, outline helpers, and file includes for exercises, and links to the `mdbook-course` README for more detailed technical explanations.
This commit is contained in:
16
STYLE.md
16
STYLE.md
@@ -192,6 +192,22 @@ displayed:
|
|||||||
avoid distracting warnings. Use this annotation only when a warning is part of
|
avoid distracting warnings. Use this annotation only when a warning is part of
|
||||||
the lesson.
|
the lesson.
|
||||||
|
|
||||||
|
### `mdbook` and `mdbook-course` Conventions
|
||||||
|
|
||||||
|
The project uses `mdbook` features in specific ways, as well as a custom
|
||||||
|
preprocessor, `mdbook-course`. The following conventions are mandatory:
|
||||||
|
|
||||||
|
- **YAML Frontmatter:** Every slide file **must** include YAML frontmatter at
|
||||||
|
the top. At a minimum, this must include the `minutes` field to specify the
|
||||||
|
estimated teaching time.
|
||||||
|
- **Outline Helpers:** Pages that serve as an index for a session or segment
|
||||||
|
**must** use the `{{%session outline%}}` or `{{%segment outline%}}` helpers.
|
||||||
|
- **File Includes:** Code for exercises and their solutions **must** be included
|
||||||
|
from external files using the standard `mdbook` `{{#include ...}}` helper.
|
||||||
|
|
||||||
|
For a complete explanation of the custom helpers and all available frontmatter
|
||||||
|
fields, please refer to the [`mdbook-course` README](mdbook-course/README.md).
|
||||||
|
|
||||||
### Language and Tone
|
### Language and Tone
|
||||||
|
|
||||||
The courses are written in American English, so write "initialize", not
|
The courses are written in American English, so write "initialize", not
|
||||||
|
|||||||
Reference in New Issue
Block a user