How do I break a string in YAML over multiple lines?

Question

I have a very long string:

Key: 'this is my very very very very very very long string'

I would like to express it over multiple shorter lines, e.g.,

Key: 'this is my very very very ' +
     'long string'

I would like to use quotes as above, so that I don't need to escape anything within the string.

Clisthenes

Quick tip: you cannot place comment inside scalar, so you cannot comment part of multiline key or value. Have to move required lines out of declaration. #20890945 – Statesman

Use this reference: yaml-multiline.info – Cineraria

Answer 1

Using yaml folded style. The indention in each line will be ignored. A line break will be inserted at the end.

Key: >
  This is a very long sentence
  that spans several lines in the YAML
  but which will be rendered as a string
  with only a single carriage return appended to the end.

http://symfony.com/doc/current/components/yaml/yaml_format.html

You can use the "block chomping indicator" to eliminate the trailing line break, as follows:

Key: >-
  This is a very long sentence
  that spans several lines in the YAML
  but which will be rendered as a string
  with NO carriage returns.

In either case, each line break is replaced by a space.

There are other control tools available as well (for controlling indentation for example).

See https://yaml-multiline.info/

Patrinapatriot

Thanks, but you can't wrap this syntax in quotes, it seems: the quotes appear as literals in the resulting string. – Clisthenes

Somehow a carriage return is added right after the end of the translation in my app. That way Javascript sees it as multiple lines and fails. {{- 'key'|trans -}} does not work either. – Misbeliever

In my experience, this syntax appends a \n at the end of the string. This may or may not be what you are looking for. – Fullgrown

each line break is replaced by a space <-- but a double-line-break will be a line break. – Ethbinium

@Misbeliever and @rich-remer Use the block chomper to avoid the newline at the end: >- – Draftee

I attempted some edits to reduce ambiguity, but then realized the ambiguity is too great for me to be certain I am making the right edits, so I rolled back my edits. Please look at my edits and help fix them to reduce ambiguity. Are the line breaks at the end of each line, the whole string, in the lines? I don't understand. Thanks. – Broadsword

And all these >- and |- won't help you pass URL like blabla.com/search.php?keywords="bla bla" or command line string like -A "111 222" -B "333 444" as is without double quotes suppressing. Suprisingly yaml is not for programmers to store URLs and command lines as is :-[ ] – Scruffy

I found the provided link yaml-multiline.info useful. – Madisonmadlen

Answer 2

There are 5 6 NINE (or 63*, depending how you count) different ways to write multi-line strings in YAML.

TL;DR

• Use > most of the time: interior line breaks are stripped out, although you get one at the end:

    key: >
      Your long
      string here.
  

• Use | if you want those linebreaks to be preserved as \n (for instance, embedded markdown with paragraphs).

    key: |
      ### Heading
  
      * Bullet
      * Points
  

• Use >- or |- instead if you don't want a linebreak appended at the end.

• Use "..." if you need to split lines in the middle of words or want to literally type linebreaks as \n:

    key: "Antidisestab\
     lishmentarianism.\n\nGet on it."
  

• YAML is crazy.

Block scalar styles (>, |)

These allow characters such as \ and " without escaping, and add a new line (\n) to the end of your string.

> Folded style removes single newlines within the string (but adds one at the end, and converts double newlines to singles):

Key: >
  this is my very very very
  long string

→ this is my very very very long string\n

Extra leading space is retained and causes extra newlines. See note below.

Advice: Use this. Usually this is what you want.

| Literal style turns every newline within the string into a literal newline, and adds one at the end:

Key: |
  this is my very very very 
  long string

→ this is my very very very\nlong string\n

Here's the official definition from the YAML Spec 1.2

Scalar content can be written in block notation, using a literal style (indicated by “|”) where all line breaks are significant. Alternatively, they can be written with the folded style (denoted by “>”) where each line break is folded to a space unless it ends an empty or a more-indented line.

Advice: Use this for inserting formatted text (especially Markdown) as a value.

Block styles with block chomping indicator (>-, |-, >+, |+)

You can control the handling of the final new line in the string, and any trailing blank lines (\n\n) by adding a block chomping indicator character:

• >, |: "clip": keep the line feed, remove the trailing blank lines.
• >-, |-: "strip": remove the line feed, remove the trailing blank lines.
• >+, |+: "keep": keep the line feed, keep trailing blank lines.

"Flow" scalar styles ( , ", ')

These have limited escaping, and construct a single-line string with no new line characters. They can begin on the same line as the key, or with additional newlines first, which are stripped. Doubled newline characters become one newline.

plain style (no escaping, no # or : combinations, first character can't be ", ' or many other punctuation characters ):

Key: this is my very very very 
  long string

Advice: Avoid. May look convenient, but you're liable to shoot yourself in the foot by accidentally using forbidden punctuation and triggering a syntax error.

double-quoted style (\ and " must be escaped by \, newlines can be inserted with a literal \n sequence, lines can be concatenated without spaces with trailing \):

Key: "this is my very very \"very\" loooo\
  ng string.\n\nLove, YAML."

→ "this is my very very \"very\" loooong string.\n\nLove, YAML."

Advice: Use in very specific situations. This is the only way you can break a very long token (like a URL) across lines without adding spaces. And maybe adding newlines mid-line is conceivably useful.

single-quoted style (literal ' must be doubled, no special characters, possibly useful for expressing strings starting with double quotes):

Key: 'this is my very very "very"
  long string, isn''t it.'

→ "this is my very very \"very\" long string, isn't it."

Advice: Avoid. Very few benefits, mostly inconvenience.

Block styles with indentation indicators

Just in case the above isn't enough for you, you can add a "block indentation indicator" (after your block chomping indicator, if you have one):

- >8
        My long string
        starts over here
- |+1
 This one
 starts here

Note: Leading spaces in Folded style (>)

If you insert extra spaces at the start of not-the-first lines in Folded style, they will be kept, with a bonus newline. (This doesn't happen with flow styles.) Section 6.5:

In addition, folding does not apply to line breaks surrounding text lines that contain leading white space. Note that such a more-indented line may consist only of such leading white space.

- >
    my long
      string
                    
    many spaces above
- my long
      string
                    
    many spaces above
    

→ ["my long\n string\n \nmany spaces above\n","my long string\nmany spaces above"]

Summary

In this table: _ means space character, \n means "newline character" except were noted. "Leading space" refers to an additional space character on the second line, when the first is only spaces (which establishes the indent).

	>	|	>-	|-	>+	|+		"	'
Spaces/newlines converted to:
Trailing space →	_	_	_	_	_	_
Leading space →	\n_	\n_	\n_	\n_	\n_	\n_
Single newline →	_	\n	_	\n	_	\n	_	_	_
Double newline →	\n	\n\n	\n	\n\n	\n	\n\n	\n	\n	\n
Final newline →	\n	\n			\n	\n
Final double newline →	\n	\n			\n\n	\n\n
How to create a literal:
Single quote	'	'	'	'	'	'	'	'	''
Double quote	"	"	"	"	"	"	"	\"	"
Backslash	\	\	\	\	\	\	\	\\	\
Other features
In-line newlines with literal \n	🚫	🚫	🚫	🚫	🚫	🚫	🚫	✅	🚫
Spaceless newlines with \	🚫	🚫	🚫	🚫	🚫	🚫	🚫	✅	🚫
# or : in value	✅	✅	✅	✅	✅	✅	🚫	✅	✅
Can start on same line as key	🚫	🚫	🚫	🚫	🚫	🚫	✅	✅	✅

Examples

Note the trailing spaces on the line before "spaces."

- >
  very "long"
  'string' with

  paragraph gap, \n and        
  spaces.
- | 
  very "long"
  'string' with

  paragraph gap, \n and        
  spaces.
- very "long"
  'string' with

  paragraph gap, \n and        
  spaces.
- "very \"long\"
  'string' with

  paragraph gap, \n and        
  s\
  p\
  a\
  c\
  e\
  s."
- 'very "long"
  ''string'' with

  paragraph gap, \n and        
  spaces.'
- >- 
  very "long"
  'string' with

  paragraph gap, \n and        
  spaces.

[
  "very \"long\" 'string' with\nparagraph gap, \\n and         spaces.\n", 
  "very \"long\"\n'string' with\n\nparagraph gap, \\n and        \nspaces.\n", 
  "very \"long\" 'string' with\nparagraph gap, \\n and spaces.", 
  "very \"long\" 'string' with\nparagraph gap, \n and spaces.", 
  "very \"long\" 'string' with\nparagraph gap, \\n and spaces.", 
  "very \"long\" 'string' with\nparagraph gap, \\n and         spaces."
]

*2 block styles, each with 2 possible block chomping indicators (or none), and with 9 possible indentation indicators (or none), 1 plain style and 2 quoted styles: 2 x (2 + 1) x (9 + 1) + 1 + 2 = 63

Some of this information has also been summarised here.

Aneroid

There are even more options when you look at the block chomping indicator. |2+ will preserve whitespaces at the beginning of the line which exceed 2 whitespaces. – Cinquain

Note that apparently not all YAML parsers implement this completely. We use Jackson (2.5.3) in Java and >- does not remove all the newlines. We switched to a "plain style" overflow and that does what we need. – Saddleback

Among the 63 syntaxes, do you think there is a single one that allows you to spell in multiple lines a string that should not have newlines nor spaces? I mean what one would write as "..." + "..." in most programming languages, or backslash before newline in Bash. – Hillari

@pepoluan I tried every possible combination and found only one that allows for spaceless concatenation: put double quotes around the string and a backslash before newline (and indentation.) Example: data:text/plain;base64,dGVzdDogImZvb1wKICBiYXIiCg== – Hillari

pyyaml appears to preserve newlines on > style strings :\ I ended up escaping the newlines with backslashes – Authority

This is ultimately the most bestests format for organizing structured data I've ever seen! What I think this answer is sorely missing though is the list of YAML parser implementations and what features they support. In my experience, most don't support chomping indicators at all, but the way they will handle them is different. – Failing

@Failing on the contrary, I think YAML is the worst format for many common use-cases (e.g., config files), not least because most people are drawn in by its apparent simplicity only to realize much later that it's an extremely complex format. YAML makes wrong things look right - for example, an innocuous colon : within one string in a string array makes YAML interpret it as an array of objects. It violates the principle of least astonishment. – Anima

@VickyChijwani We are lost in translation. My comment was sarcastic, but sarcasm doesn't translate well. I very much agree with you. – Failing

@Failing sorry, yes, I too find that it's tricky to convey sarcasm in writing. Especially in a case like this because I know people who really do think YAML is a great format :). Cheers! – Anima

"These allow escaping" Block Scalars don't allow escape sequences. Only double quotes support it. – Jennine

Yet Another Multi Line string syntax – Yearly

@Hillari Can you please give an example for the "spaceless concatenation"? I am not able to grok Example: data:text/plain;base64,dGVzdDogImZvb1wKICBiYXIiCg== – Gaff

@Gaff That's just a way to share a literal snippet of text through the comment system's limitations. It's a data URI, you just paste into the browser's address bar. – Hillari

If you use >1 or |1, then some of the indentation will be kept. For instance if the > is in the 3rd column (indented two spaces) then X-3 characters of indentation will be kept. – Aneroid

I always struggled to remember which one of '|' or '>' keeps or removes the line feeds. At some point I realized that, if read from left to right, the operators tell you how they transform the string. '|' has the same height on both sides meaning that the string will also stay the same height; while '>' is smaller on the right than on the left, meaning it will "compress" the string from many to just one line. Just wanted to leave that mnemonic here for those who haven't discovered it yet. – Bathtub

For anyone struggling in remembering the different ways to use YAML multiline strings, you can find here (github.com/paolodenti/yaml-multiline) a simple test docker image, showing the different results with different syntaxes (in docker-compose.yaml). Just clone and docker compose up --build – Tova

Or, um, just use yaml-online-parser.appspot.com – Aneroid

"Use "..." if you need to split lines in the middle of words or want to literally type linebreaks as \n" <— I'm confused by the ellipses. Shouldn't that be a backslash, given the example? "Use "\" if you need to split lines in the middle of words". Or am I missing something? – Possum

I sort of get what you mean, but I think the example makes it pretty clear how you use it. The ellipsis isn't literal - it's saying, use double quotes around a string if you have any of the following two needs. – Aneroid

YAML spec goal #7: "YAML should be easy to implement and use." So much for easy implementation... – Rugg

I keep coming back to this answer, and the number increases every time. – Ventre

We need Yet Another YAML Language – Chair

Answer 3

To preserve newlines use |, for example:

Key: |
  This is a very long sentence
  that spans several lines in the YAML
  but which will be rendered as a string
  with newlines preserved.

is translated to "This is a very long sentence‌**\n** that spans several lines in the YAML‌**\n** but which will be rendered as a string‌**\n** with newlines preserved.\n"

Pentavalent

This seems to work fine for me with two lines but not with three? – Strephonn

Thanks, works fine there just like you say. For some reason in Pandoc's yaml headers I need to repeat the | on each line, for reasons that are not obvious to me: groups.google.com/forum/#!topic/pandoc-discuss/xuqEmhWgf9A – Strephonn

Isn't an issue the fact that if I write: - field1: | one two - field1: | three for' I get: one\ntwo\n and three\nfor? I would aspect the \n after 2 to do not be there... – Alva

When using multiline cat with delimiter this causes leading spaces (which are necessary for YAML) to be added to output. – Aphid

@Rubytastic to have those break lines also in your HTML page generated by Rails, you need some precautions. I already answered here: #10983206 – Imidazole

@AliShakiba You missed the final newline in the translation. And it is also not necessary to indent the lines of the scalar if it is at the root of document. – Javier

Answer 4

1. Block Notation(plain, flow-style, scalar): Newlines become spaces and extra newlines after the block are removed

---
# Note: It has 1 new line after the string
content:
    Arbitrary free text
    over multiple lines stopping
    after indentation changes...

...

Equivalent JSON

{
 "content": "Arbitrary free text over multiple lines stopping after indentation changes..."
}

2. Literal Block Scalar: A Literal Block Scalar | will include the newlines and any trailing spaces. but removes extra

newlines after the block.

---
# After string we have 2 spaces and 2 new lines
content1: |
 Arbitrary free text
 over "multiple lines" stopping
 after indentation changes...  


...

Equivalent JSON

{
 "content1": "Arbitrary free text\nover \"multiple lines\" stopping\nafter indentation changes...  \n"
}

3. + indicator with Literal Block Scalar: keep extra newlines after block

---
# After string we have 2 new lines
plain: |+
 This unquoted scalar
 spans many lines.


...

Equivalent JSON

{
 "plain": "This unquoted scalar\nspans many lines.\n\n\n"
}

4. – indicator with Literal Block Scalar: – means that the newline at the end of the string is removed.

---
# After string we have 2 new lines
plain: |-
 This unquoted scalar
 spans many lines.


...

Equivalent JSON

{
 "plain": "This unquoted scalar\nspans many lines."
}

5. Folded Block Scalar(>):

will fold newlines to spaces and but removes extra newlines after the block.

---
folded_newlines: >
 this is really a
 single line of text
 despite appearances


...

Equivalent JSON

{
 "fold_newlines": "this is really a single line of text despite appearances\n"
}

for more you can visit my Blog

Laurent

Did you intend for example #4 to use "|-" after the colon? Also, you can lose the "---" directives end markers here, as you're only showing one document. The document end markers are helpful to highlight the trailing whitespace in the documents. Apart from that, though, there's no need for explicit documents. – Azine

thanks for pointing out. that was a typo. A have fixed that. I have provided starting and ending marker so that everyone can see new lines after the string. – Laurent

Nr.1 is described as a plain, flow-style, scalar in the YAML specification. Calling it block-style is misleading. – Javier

Changes Nr.1 as a plain, flow-style, scalar. – Laurent

This site can’t be reached. Check if there is a typo in interviewbubble.com. DNS_PROBE_FINISHED_NXDOMAIN. Thanks. 👍 – Filibeg

Answer 5

To concatenate long lines without whitespace, use double quotes and escape the newlines with backslashes:

key: "Loremipsumdolorsitamet,consecteturadipiscingelit,seddoeiusmodtemp\
  orincididuntutlaboreetdoloremagnaaliqua."

Realize

Thanks, this really helped me to define Docker volumes over multiple lines! If someone has the same problem, here is my solution on an Online YAML Parser – Grandeur

Ah finally. I was trying to wrap long ssh-keys in Puppet's Hiera yaml files over multiple lines but always got unwanted spaces until I used your answer. Thanks. – Purslane

I am looking for this answer. This is silly there is no option in yaml to do something easy in this approach. – Dud

Answer 6

You might not believe it, but YAML can do multi-line keys too:

?
 >
 multi
 line
 key
:
  value

Sardinian

Explanation needed (what is "?"). – Marciemarcile

@Marciemarcile exactly as written, "multi-line" key. Usually you do things like key:value, but if your key contains new-line, you can do it as described above – Mocha

Any example of a real-world use-case for this? – Equinox

@Marciemarcile the ? is the key indicator (as in key in a mapping). In many situations you may leave out the key indicator, when the (required) value indicator : after the key makes parsing unambiguous. But that is not the case, you'll have to use this to explicitly mark the key. – Javier

PROPOSAL: any team members that do this must buy coffee for the team for 1 week - per offense :) – Lyns

Answer 7

In case you're using YAML and Twig for translations in Symfony, and want to use multi-line translations in Javascript, a carriage return is added right after the translation. So even the following code:

var javascriptVariable = "{{- 'key'|trans -}}";

Which has the following yml translation:

key: >
    This is a
    multi line 
    translation.

Will still result into the following code in html:

var javascriptVariable = "This is a multi line translation.
";

So, the minus sign in Twig does not solve this. The solution is to add this minus sign after the greater than sign in yml:

key: >-
    This is a
    multi line 
    translation.

Will have the proper result, multi line translation on one line in Twig:

var javascriptVariable = "This is a multi line translation.";

Misbeliever

This looks like a bug. Did you have a chance to file a bug report? – Borroff

Answer 8

For situations were the string might contain spaces or not, I prefer double quotes and line continuation with backslashes:

key: "String \
  with long c\
  ontent"

But note about the pitfall for the case that a continuation line begins with a space, it needs to be escaped (because it will be stripped away elsewhere):

key: "String\
  \ with lon\
  g content"

If the string contains line breaks, this needs to be written in C style \n.

See also this question.

Chemiluminescence

If it is stripped away elsewhere, i.e. not in that position, can you update your answer with information about where it will be stripped away. Please also write which parser (for which language) does that? I have only seen parsers strip such leading/trailing spaces in multiline quotes strings in place. – Javier

Answer 9

None of the above solutions worked for me, in a YAML file within a Jekyll project. After trying many options, I realized that an HTML injection with <br> might do as well, since in the end everything is rendered to HTML:

name: | In a village of La Mancha <br> whose name I don't <br> want to remember.

At least it works for me. No idea on the problems associated to this approach.

Nygaard

Your solution refers to a different problem: in your case you want linebreaks to appear in rendered HTML as result of processing YAML. HTML and YAML don't have an implicit relationship with each other. And even if YAML would pass regular linebreaks HTML would ignore them. Eventually the op's question is related to using linebreaks in YAML itself just to prevent very long lines. It doesn't care about how the data might be rendered in the end. Why telling this? Because this explains why all the other solutions given here don't work in your case. – Morey