[ << Musical notation ]	[Top][Contents][Index]	[ Specialist notation >> ]
[ < Formatting text ]	[ Up : Formatting text ]	[ Selecting font and font size > ]

---

Text markup introduction

A \markup or \markuplist block is used to typeset text with an extensible syntax called “markup mode”. Such blocks can be used in many contexts (see section Text objects overview).

In markup mode, words are written as-is. A single word does not need any quotes.

\markup intenso

Several words can be grouped together by enclosing them in quotes.

\markup "molto intenso"

Apart from grouping, quoting also allows writing special characters such as ‘\’ and ‘#’ without affecting the formatting of the text. Double quotation marks themselves may be printed by preceding them with backslashes.

\relative {
  a'1^"\italic markup..."
  a_\markup { \italic "... prints \"italic\" letters!" }
  a a
}

Formatting is achieved through markup commands. Their name is written preceded by a backslash. They expect a number of arguments specific to the command. For an exhaustive list of \markup-specific commands, see section Text markup commands.

\markup \italic "string. assai"
\markup \with-color "red" intenso

Markup commands can be nested. The markup block ends when all commands have received their arguments.

\markup \with-color "red" \italic intenso

Several markup expressions can be grouped together within braces to form a so-called markup list. Without further formatting, the elements of a markup list are typeset in a row.

\markup { molto \italic intenso }

Some commands do not expect a markup but a markup list, allowing for more complex text arrangements than printing in a row.

\markup \center-column {
  \bold "Des Simplicius Simplicissimus Jugend"
  "Karl Amadeus Hartmann"
}

Also, some commands do not return a markup but a markup list. The result can then be used where a markup list is expected. For a list of these commands, see section Text markup list commands.

\markup \string-lines
    "Twinkle, twinkle, little star,
     How I wonder what you are!"

\markup \center-column \string-lines
    "Twinkle, twinkle, little star,
     How I wonder what you are!"

Elements of a nested markup list are simply treated as elements of the main markup list.

\markup \center-column {
  \bold "Des Simplicius Simplicissimus Jugend"
  { Karl Amadeus \smallCaps Hartmann }
}

To group elements of a nested markup list in a row, apply the \line command to the markup list. This stacks elements from the markup list horizontally into a single markup.

\markup \center-column {
  \bold "Des Simplicius Simplicissimus Jugend"
  \line { Karl Amadeus \smallCaps Hartmann }
}

A special feature is the handling of commands taking markups when applied to markup lists. When a command expects a markup as its last argument, and a markup list is given for this argument, the markup command is applied to each of the individual markups in the list.

\markup \box { Karl Amadeus \smallCaps Hartmann }

In this case, the result is in turn a markup list, which can be passed to a command expecting a markup list, or to one expecting a markup, with again the mapping behavior described above in the latter case.

\markup \center-column \box { Karl Amadeus \smallCaps Hartmann }
\markup \rotate #30 \box { Karl Amadeus \smallCaps Hartmann }

Apply \line to a markup list in order to make it treated as a single markup argument.

\markup \box { Karl Amadeus \smallCaps Hartmann }
\markup \box \line { Karl Amadeus \smallCaps Hartmann }

When the entire content of a \markup expression is a markup list, it is implicitly typeset using the \line command. Thus, elements are stacked horizontally and grouped as a single, unbreakable text block. The \markuplist command acts differently: it expects a markup list, and prints the individual markups on the page, stacking them vertically, and allowing page breaks. The following example illustrates this difference.

\markup \box \wordwrap {
  Lorem ipsum dolor sit amet, consectetur
  adipisicing elit, sed do eiusmod tempor incididunt
  ut labore et dolore magna aliqua.  Ut enim ad minim
  veniam, quis nostrud exercitation ullamco laboris
  nisi ut aliquip ex ea commodo consequat.
}

\markuplist \box \wordwrap-lines {
  Lorem ipsum dolor sit amet, consectetur
  adipisicing elit, sed do eiusmod tempor incididunt
  ut labore et dolore magna aliqua.  Ut enim ad minim
  veniam, quis nostrud exercitation ullamco laboris
  nisi ut aliquip ex ea commodo consequat.
}

Markups can be stored in variables, to be reused in any context where a markup is accepted. For example, such a variable can be directly attached to notes:

allegro = \markup \bold \large Allegro

{
  d''8.^\allegro
  d'16 d'4 r2
}

The \etc syntax allows to define custom shorthands usable as markup commands.

\markup reddish = \markup \with-color "tomato" \etc

\markup { molto \reddish intenso }

The inner workings of markup commands and how to implement more complex ones is explained in Markup functions.

See also

Notation Reference: Text objects overview, Text markup commands, Text markup list commands.

Extending LilyPond: Markup functions.

Installed Files: scm/markup.scm, scm/define-markup-commands.scm.

Snippets: Text.

Internals Reference: TextScript.

Known issues and warnings

Syntax error messages for markup mode can be confusing.

---

[ << Musical notation ]	[Top][Contents][Index]	[ Specialist notation >> ]
[ < Formatting text ]	[ Up : Formatting text ]	[ Selecting font and font size > ]

<< Back to Documentation Index

LilyPond Notation Reference v2.25.15 (development-branch).