Article

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 would be both in italics and bold.

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

Markdown:

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

Result:

In this example, the word sentence (the apostrophe or the letter s that follow it) would be italics and bold, as is the word more (but not the parentheses). The volved portion of the word involved would also be italic and bold, while the in part of the word would be italic 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 will be crossed out.

Links

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 to be formatted and put the name of the text style you want to use in curly brackets ({}). The text style you refer to must be defined 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.

Markdown paragraph and line separators (\n or \n\n) are not supported at the beginning or end of components and will cause undesirable effects. To add space in these locations within a component, use layout margins.

Markdown paragraph and line separators are not supported at the beginning or end of components. Use layout margins to add space in these locations within a component. Using \n or \n\n at the beginning or end of a component will cause undesirable effects.

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 a list must be separated 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, the link is converted to a map that you can manipulate the same way as a map component. (If your URL does not start with https://maps.apple.com/, then only a link to the map is displayed.)

Markdown:

Apple's main campus occupies 32 acres in six buildings on [Infinite Loop](https://maps.apple.com?sll=37.3303991,-122.03233&t=standard&spn=0.009,0.009&q=Apple%20Inc).

Result:

Apple's main campus occupies 32 acres in six buildings on Infinite Loop.

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

Using HTML with Apple News Format

Use HTML formatting for text components.

object Body

The component for adding body text.

object Title

The component for adding an article title.

object Heading

The text component for adding a heading.

object Intro

The component for adding introductory text.

object Caption

The component for adding caption text.

object Author

The component for adding the name of the author.

object Byline

The component for adding contributor credits, especially for articles with multiple contributors.

object Illustrator

The component for adding illustrator credit.

object Photographer

The component for adding a photographer credit.

object Quote

The component for including a quote.

object PullQuote

The component for including a pull quote.

object Text

Properties shared by all text component types.