In YAML, I have a string that's very long. I want to keep this within the 80-column (or so) view of my editor, so I'd like to break the string. What's the syntax for this?

In other words, I have this:

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

and I'd like to have this (or something to this effect):

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

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

share|improve this question
up vote 443 down vote accepted

Using yaml folded style, each line break is replaced by a space. The indention in each line will be ignored.

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

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

share|improve this answer
    
Thanks, but you can't wrap this syntax in quotes, it seems: the quotes appear as literals in the resulting string. – jjkparker Sep 27 '10 at 16:55
25  
I don't think you add the quotes. The > infers it is a string. – Matt Williamson Sep 28 '10 at 4:31
59  
s/infers/implies/ – Justin Force Sep 4 '13 at 18:23
    
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. – Rvanlaak May 6 '15 at 14:48
    
How would you get this same effect as a value in a list? – Mikhail Jun 2 '15 at 2:17

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

Block scalar styles (>, |)

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

> Folded style removes the newlines within the string (but adds one at the end):

Key: >
  this is my very very very
  long string

this is my very very very long string\n

| Literal style turns newlines within the string into literal newlines, 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.

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.

plain style (no escaping, no # or : combinations, limits on first character):

Key: this is my very very very 
  long string

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."

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."

Summary

In this table, _ means space character. \n means "newline character" (\n in JavaScript), except for the "in-line newlines" row, where it means literally a backslash and an n).

                      >     |            "     '     >-     >+     |-     |+
-------------------------|------|-----|-----|-----|------|------|------|------  
Trailing spaces   | Kept | Kept |     |     |     | Kept | Kept | Kept | Kept
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 dbl nl's => |      |      |     |     |     |      | Kept |      | Kept  
In-line newlines  | No   | No   | No  | \n  | No  | No   | No   | No   | No
Spaceless newlines| No   | No   | No  | \   | No  | No   | No   | No   | No 
Single quote      | '    | '    | '   | '   | ''  | '    | '    | '    | '
Double quote      | "    | "    | "   | \"  | "   | "    | "    | "    | "
Backslash         | \    | \    | \   | \\  | \   | \    | \    | \    | \
" #", ": "        | Ok   | Ok   | No  | Ok  | Ok  | Ok   | Ok   | Ok   | Ok
Can start on same | No   | No   | Yes | Yes | Yes | No   | No   | No   | No
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."
]

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

*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

share|improve this answer
    
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. – udondan Mar 15 '16 at 7:38
    
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. – Robert Jack Will Mar 31 '16 at 13:02
5  
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. – Tobia Jul 28 '16 at 15:33
3  
@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== – Tobia Aug 26 '16 at 8:56
1  
Ah, thanks - that (trailing backslash => no space) is a behaviour I missed. Seems to be unique to double quoted strings. – Steve Bennett ㄹ Aug 26 '16 at 9:11

To preserve newlines use |, for example:

|
  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."

share|improve this answer
    
This seems to work fine for me with two lines but not with three? – cboettig Oct 23 '13 at 22:09
9  
@cboettig Try it here: nodeca.github.io/js-yaml – Ali Shakiba Oct 24 '13 at 19:12
    
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 – cboettig Oct 24 '13 at 19:48
1  
This example does NOT convert to new lines in rails 4! – Rubytastic Nov 13 '13 at 16:03
    
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... – Alain1405 Jan 14 '14 at 16:52

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

?
 >
 multi
 line
 key
:
  value
share|improve this answer
2  
Explanation needed (what is "?"). – ilyaigpetrov Sep 26 '17 at 11:38
    
@ilyaigpetrov 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 – goFrendiAsgard Oct 9 '17 at 1:33
2  
Any example of a real-world use-case for this? – RichouHunter Dec 11 '17 at 14:49

In case you're using yml 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.";
share|improve this answer
    
This looks like a bug. Did you have a chance to file a bug report? – dreftymac Jan 20 '16 at 4:45

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

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

(Thanks @Tobia)

share|improve this answer
    
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 – Mike Mitterer Aug 3 '17 at 10:05
    
Excellent, works perfectly with Ansible. – gertas Aug 31 '17 at 9:58
    
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. – Martijn Heemels Nov 30 '17 at 9:53

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.

share|improve this answer

protected by jtbandes Jan 25 '17 at 23:42

Thank you for your interest in this question. Because it has attracted low-quality or spam answers that had to be removed, posting an answer now requires 10 reputation on this site (the association bonus does not count).

Would you like to answer one of these unanswered questions instead?

Not the answer you're looking for? Browse other questions tagged or ask your own question.