rust/comprehensive-rust
1
0
Fork 0
mirror of https://github.com/google/comprehensive-rust.git synced 2025-10-09 10:55:26 +02:00
Code Issues Releases Activity

docs(style): Add mdbook and mdbook-course conventions (#2926)

Browse Source 
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:
Dmitri Gribenko
2025-09-24 10:08:28 +02:00
committed by GitHub
parent 31a8af33a1
commit 3cbcd7e0b5
1 changed files with 16 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

16
STYLE.md
View File

@@ -192,6 +192,22 @@ displayed:
avoid distracting warnings. Use this annotation only when a warning is part of
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
The courses are written in American English, so write "initialize", not