In Quoting constructs§

See primary documentation in context for Heredocs: :to

A convenient way to write a multi-line string literal is by using a heredoc, which lets you choose the delimiter yourself:

say q:to/END/;
Here is
some multi-line
string
END

The contents of the heredoc always begin on the next line, so you can (and should) finish the line.

my $escaped = my-escaping-function(q:to/TERMINATOR/, language => 'html');
Here are the contents of the heredoc.
Potentially multiple lines.
TERMINATOR

If the terminator is indented, that amount of indention is removed from the string literals. Therefore this heredoc

say q:to/END/;
    Here is
    some multi line
        string
    END

produces this output:

Here is
some multi line
    string

Heredocs include the newline from before the terminator.

To allow interpolation of variables use the qq form, but you will then have to escape metacharacters \{ as well as $ if it is not the sigil for a defined variable. For example:

my $f = 'db.7.3.8';
my $s = qq:to/END/;
option \{
    file "$f";
};
END
say $s;

would produce:

option {
    file "db.7.3.8";
};

Some other situations to pay attention to are innocent-looking ones where the text looks like a Raku expression. For example, the following generates an error:

my $title = 'USAFA Class of 1965';
say qq:to/HERE/;
<a href='https://usafa-1965.org'>$title</a>
HERE
# Output:
Type Str does not support associative indexing.
  in block <unit> at here.raku line 2

The angle bracket to the right of '$title' makes it look like a hash index to Raku when it is actually a Str variable, hence the error message. One solution is to enclose the scalar with curly braces which is one way to enter an expression in any interpolating quoting construct:

say qq:to/HERE/;
<a href='https://usafa-1965.org'>{$title}</a>
HERE

Another option is to escape the `<` character to avoid it being parsed as the beginning of an indexing operator:

say qq:to/HERE/;
<a href='https://usafa-1965.org'>$title\</a>
HERE

Because a heredoc can be very long but is still interpreted by Raku as a single line, finding the source of an error can sometimes be difficult. One crude way to debug the error is by starting with the first visible line in the code and treating is as a heredoc with that line only. Then, until you get an error, add each line in turn. (Creating a Raku program to do that is left as an exercise for the reader.)

You can begin multiple Heredocs in the same line. If you do so, the second heredoc will not start until after the first heredoc has ended.

my ($first, $second) = qq:to/END1/, qq:to/END2/;
  FIRST
  MULTILINE
  STRING
  END1
   SECOND
   MULTILINE
   STRING
   END2
say $first;  # OUTPUT: «FIRST␤MULTILINE␤STRING␤»
say $second; # OUTPUT: «SECOND␤MULTILINE␤STRING␤»