Skip to content

Commit 3cbcd7e

Browse files
authored
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.
1 parent 31a8af3 commit 3cbcd7e

File tree

1 file changed

+16
-0
lines changed

1 file changed

+16
-0
lines changed

STYLE.md

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -192,6 +192,22 @@ displayed:
192192
avoid distracting warnings. Use this annotation only when a warning is part of
193193
the lesson.
194194

195+
### `mdbook` and `mdbook-course` Conventions
196+
197+
The project uses `mdbook` features in specific ways, as well as a custom
198+
preprocessor, `mdbook-course`. The following conventions are mandatory:
199+
200+
- **YAML Frontmatter:** Every slide file **must** include YAML frontmatter at
201+
the top. At a minimum, this must include the `minutes` field to specify the
202+
estimated teaching time.
203+
- **Outline Helpers:** Pages that serve as an index for a session or segment
204+
**must** use the `{{%session outline%}}` or `{{%segment outline%}}` helpers.
205+
- **File Includes:** Code for exercises and their solutions **must** be included
206+
from external files using the standard `mdbook` `{{#include ...}}` helper.
207+
208+
For a complete explanation of the custom helpers and all available frontmatter
209+
fields, please refer to the [`mdbook-course` README](mdbook-course/README.md).
210+
195211
### Language and Tone
196212

197213
The courses are written in American English, so write "initialize", not

0 commit comments

Comments
 (0)