Contents

Using Markdown with Apple News Format

Use Markdown formatting for text components.

Overview

Apple News Format supports a subset of Markdown syntax. You can use Markdown in the following components by setting the format property to markdown.

In addition to the components above, you can also use Markdown to format text in CaptionDescriptor, and FormattedText objects.

Example

{
"role": "heading",
"text": "1\\. First list item",
"format": "markdown"
}

To learn more about Markdown, visit the Markdown website.

Text-Level Markdown Syntax

Apple News Format supports these Markdown features within text paragraphs.

Emphasis (Italics)

Use single asterisks (*) or single underscores (_).

Markdown:

A sentence with _emphasis_ and two different types of *emphasis notation*.

Result:

A sentence with emphasis and two different types of emphasis notation.

Markdown:

This _sentence_'s Markdown formatting is (_more_) in_volved_.

Result:

This sentence’s Markdown formatting is (more) involved.

Strong Emphasis (Bold)

To make text bold, use double asterisks (**) or double underscores (__).

Markdown:

A sentence containing something **really important**.

Result:

A sentence containing something really important.

Markdown:

This __sentence__'s Markdown formatting is (__more__) in__volved__.

Result:

This sentence’s Markdown formatting is (more) involved.

Combined Emphasis (Italics) and Strong (Bold)

You can nest emphasis and strong emphasis to use bold-italic font faces by using underscores with double asterisks (or double underscores with single asterisks).

Markdown:

A _**sentence**_ containing **_four_** ways to __*combine*__ strong and *__emphasis__*.
_An emphasized sentence containing a **strong phrase**._

Result:

In the first example, the words sentence, four, combine, and emphasis are in both italics and bold.

In the second example, the entire sentence is displayed in italics with strong phrase in italics and bold.

Markdown:

This _**sentence**_'s Markdown formatting is (__*more*__) *in__volved__*.

Result:

In this example, the word sentence (but not the apostrophe and the letter s that follow it) is in italics and bold, as is the word more (but not the parentheses). The volved portion of the word involved is also italics and bold, while the in part of the word is italics only.

Strikethrough

For strikethrough text, surround with double tildes (~~).

Markdown:

A sentence containing something ~~no longer neeeded~~.

Result:

In this example, the text no longer neeeded is crossed out.

To add a link with Markdown, use brackets for the linked text and parentheses for the link URL. Brackets must contain at least one character; empty brackets are invalid.

Markdown:

This text contains [a link to another page](http:/www.apple.com).
_This emphasized sentence contains [a link to another page] (http://www.apple.com)_.
This text contains an emphasized [_link to another page_](http://www.apple.com).

Result:

The first example contains a simple link.

The second example italicizes the entire sentence, including the link text.

The third example italicizes just the link.

Block-Level Markdown

Headings

To indicate that text is a heading, use the # character.

# Heading 1

## Heading 2

### Heading 3

#### Heading 4

##### Heading 5

###### Heading 6

Inline Text Style

To apply a text style that you have already defined in Apple News Format, use square brackets ([]) to enclose the text you want to format and put the name of the text style you want to use in curly brackets ({}). You must define the text style you refer to using the textStyles property in the article document properties.

For this example, specialTextStyle is predefined to be bold. (Your actual result depends on how you define specialTextStyle.)

Markdown:

The trail passes the [Big Sur Waterfall]{specialTextStyle} before ending in the valley.

Result:

The trail passes the Big Sur Waterfall before ending in the valley.

Paragraphs

To separate text into paragraphs, use two of the Markdown new line tags (\n\n) between the end of one paragraph and the beginning of the next paragraph. In JSON, new lines are encoded as \n.

Markdown:

Last line of paragraph 1.\n\nFirst line of paragraph 2.

Result:

Last line of paragraph 1.

First line of paragraph 2.

Apple News Format doesn’t support Markdown paragraph and line separators (\n or \n\n) at the beginning or end of components. To add space in these locations within a component, use layout margins.

Lists

Bulleted List

To create a bulleted list item, start a new line, then type either a hyphen (-), an asterisk (*), or a plus sign (+) followed by a space.

Markdown:

- First item
- Second item

Result:

  • First item

  • Second item

Numbered List

Use numbers and periods followed by a space (1. ).

Markdown:

1. First numbered item
2. Second numbered item

Result:

  1. First numbered item

  2. Second numbered item

Numbered List in Apple News Format

In a numbered list, Apple News Format restarts at 1 for each new component — no matter what number you provide in your text.

If you need to separate a list into multiple components, remove "format": "markdown" from each component or “escape” the period with two backslashes (\\), as shown in the following JSON example:

Markdown in a JSON file:

{
   "role": "heading",
   "text": "1\\. First list item",
   "format": "markdown"
},
{
   "role": "heading",
   "text": "2\\. Second list item",
   "format": "markdown"
}

Result:

  1. First list item

  2. Second list item

Divider

To create a divider line or horizontal rule, type at least 3 hyphens (---) or 3 asterisks (***) on a new, empty line.

Dividers can separate portions of text.
---
Here's the epilogue to my story.

Maps

To add a map that renders within your article, begin the URL for your map with https://maps.apple.com/. When Apple News Format renders the article, it converts the link to a map that you can manipulate the same way as a map component. If your URL doesn’t start with https://maps.apple.com/, then Apple News Format only displays a link to the map.

Markdown:

Apple's main campus occupies 172 acres at [Apple Park](https://maps.apple.com?sll=37.3327,-122.00533&t=standard&spn=0.02,0.02&q=Apple%20Inc).

Result:

Apple’s main campus occupies 172 acres at Apple Park.

[Image]

Escaping Markdown

To escape special Markdown characters in a JSON document, use two backslashes (one to escape Markdown and one to escape JSON) as shown in the following examples:

Example 1

Markdown:

This is an asterisk: \*\n\nThis is an underscore: \_

Markdown in a JSON document (using two backslashes):

This is an asterisk: \\*\n\nThis is an underscore: \\_

Result:

This is an asterisk: *

This is an underscore: _

Example 2

Markdown:

1. First list item\n1. Second list item\n\n1\. Not a list item

Markdown in a JSON document (using two backslashes):

1. First list item\n1. Second list item\n\n1\\. Not a list item

Result:

  1. First list item

  2. Second list item

1. Not a list item

See Also

Text