From 00c90eae95c5987a8352dd786d9687f3d213f54a Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Wed, 25 Oct 2023 12:01:17 +0200
Subject: [PATCH] add note on highlighting examples and syntax definitions

---
 doc/manual/src/contributing/documentation.md | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)

diff --git a/doc/manual/src/contributing/documentation.md b/doc/manual/src/contributing/documentation.md
index f73ab2149..e35a29d93 100644
--- a/doc/manual/src/contributing/documentation.md
+++ b/doc/manual/src/contributing/documentation.md
@@ -151,6 +151,24 @@ Please observe these guidelines to ease reviews:
   > This is a note.
   ```
 
+  Highlight examples as such:
+
+  ````
+  > **Example**
+  >
+  > ```console
+  > $ nix --version
+  > ```
+  ````
+
+  Highlight syntax definiions as such, using [EBNF](https://en.wikipedia.org/wiki/Extended_Backus%E2%80%93Naur_form) notation:
+
+  ````
+  > **Syntax**
+  >
+  > *attribute-set* = `{` [ *attribute-name* `=` *expression* `;` ... ] `}`
+  ````
+
 ### The `@docroot@` variable
 
 `@docroot@` provides a base path for links that occur in reusable snippets or other documentation that doesn't have a base path of its own.