From c740a5d10ad9892b9c9500f03a546e29b9721d78 Mon Sep 17 00:00:00 2001 From: Aaron Collier Date: Tue, 20 Dec 2022 11:07:13 +0000 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9D=20Update=20guidance=20for=20upstre?= =?UTF-8?q?am=20issues=20(#2759)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- contributing/markup-format.md | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) 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,