Guides and Sample Code

Developer

Markup Formatting Reference

Markup Functionality

Markup uses simple character-based delimiters to mark formatted text in playgrounds and in Quick Help for Swift symbols.

The different delimiters include functionality for:

  • Formatting a line of text such as a creating a heading

  • Formatting multiple lines of text such as creating a bulleted list

  • Formatting a span of characters such as adding emphasis to a string

  • Inserting links to web based content

  • Inserting assets such as images and videos

  • Inserting callouts such as examples in playgrounds and parameters in Quick Help.

  • Escaping special characters, including markup delimiters

Some of the delimiters are used for both rendered playground documentation and in Quick Help. Other delimiters are used with either playgrounds or with Quick Help. The documentation for each delimiter includes information on where it can be used. In addition, Table 2-1 gives an alphabetical overview of all the delimiters including a brief description.

For information on adding markup, see Using Markup.

Table 2-1Markup delimiters

Delimiter name

Description

Playground

Quick Help

Attention

Adds an Attention callout.

 

Author

Adds an Author callout.

 

Authors

Adds an Authors callout for multiple authors.

 

Block Comment

The comment markers for opening and closing a block of markup.

Bug

Adds a Bug callout.

 

Bulleted Lists

Adds a bulleted list.

Code Block

Renders lines of text as a block of code.

Code Voice

Renders a span of text in the font used for displaying code.

Complexity

Adds a Complexity callout.

 

Copyright

Adds a Copyright callout.

 

Custom Callout

Adds a callout with custom text.

 

Date

Adds a Date callout.

 

Emphasis (Italics)

Renders a span of text with emphasis.

Escapes

Disables any special behaviors for the following character.

Example

Adds an Example callout.

 

Experiment

Adds an Experiment callout.

Headings

Renders a line as a heading.

Horizontal Rules

Adds a horizontal rule.

Images

Shows an image from the web or from a playground project.

Important

Adds an Important callout

Invariant

Adds an Invariant callout.

 

Link Reference

Adds a named reference to a URL that can be used in multiple places.

Links

Adds a link to a text-based resource.

Named Page

Adds a link to a named playground page.

 

Next Page

Adds a link to the next playground page in the project.

 

Note

Adds a Note callout.

Numbered Lists

Adds a numbered list.

Parameter

Adds a Parameter to the parameters section of Quick Help.

 

Parameters

Adds multiple Parameters to the parameters section of Quick Help.

 

Postcondition

Adds a Postcondition callout.

 

Precondition

Adds a Precondition callout.

 

Previous Page

Adds a link to the previous page in a playground project.

 

Remark

Adds a Remark callout.

 

Returns

Adds the Returns section to Quick Help.

 

Requires

Adds a Requires callout.

 

See Also

Adds a See Also callout.

 

Since

Adds a Since callout.

 

Single Line Comment

The comment marker used for a single line of markup.

Strong (Bold)

Renders a span of text in bold.

Throws

Adds the Throws section to Quick Help.

 

To Do

Adds a To Do callout.

 

Version

Adds a Version callout.

 

Videos

Adds a live video player.

 

Warning

Adds a Warning callout.