diff --git a/contributing/markup-format.md b/contributing/markup-format.md
index 2358dce45f..5cde0ae670 100644
--- a/contributing/markup-format.md
+++ b/contributing/markup-format.md
@@ -259,6 +259,26 @@ web:
 Keep the top-level key visible so readers can understand the code in context.
 (For example, don't leave out `web:` in the example above.)
 
+### Multiline strings
+
+When writing multiline strings in YAML, known as scalar content,
+examples often use a literal style as shown with a `|`.
+In such cases, the string that comes needs to span multiple lines.
+Otherwise, the parser doesn't accept it as a scalar and the spacing and highlighting is wrong.
+
+To resolve this, either put the comment on a single line without the `|`
+or add an ellipsis to indicate content is missing, as in the following example:
+
+```yaml
+hooks:
+    build: |
+        ...
+        git pull
+```
+
+The highlighter also adds extra whitespace at the end of multiline strings.
+These are [known issues](https://github.com/alecthomas/chroma/issues/475).
+
 ### Note when low-level items are missing
 
 If there's a complicated block (such as `web.locations`) with many settings not relevant to the current idea,