Use HTML formatting for text components.
Technologies
- Apple News Format
- Apple News API
Overview
Apple News Format supports a subset of HTML tags. You can use HTML tags in these components by setting their format
property to html
.
In addition to the components above, you can also use HTML tags to format text in CaptionDescriptor and FormattedText objects.
To include an HTML table in your article, see Adding an HTML Table.
Example
{
"role": "body",
"text": "<a href=\"https://www.example.com\">Subscribe to our newsletter for more great stories.</a>",
"format": "html"
}
Supported HTML Tags
This section describes how to use the HTML tags supported by Apple News Format.
Note
Generic containers and autonomous custom elements such as <span>
and <div>
are allowed; however, they will have no effect until styling is applied to them.
Paragraphs
Begin each paragraph block with <p>,
and end each paragraph with </p>
.
For example, this code:
<p>Quis autem vel eum iure reprehenderit qui in ea voluptate velit esse quam nihil molestiae consequatur, vel illum qui dolorem eum fugiat quo voluptas nulla pariatur? At vero eos et accusamus et iusto odio ducimus qui blanditiis.</p><p>Cras ultricies mi eu turpis hendrerit fringilla. Vestibulum ante ipsum primis in faucibus orci luctus et ultrices posuere cubilia Curae; In ac dui quis mi consectetuer.</p><p>Temporibus autem et aut officiis debitis aut rerum necessitatibus saepe eveniet ut et voluptates repudiandae sint et molestiae non recusandae. Itaque rerum hic tenetur.</p>
Results in three paragraphs:
Quis autem vel eum iure reprehenderit qui in ea voluptate velit esse quam nihil molestiae consequatur, vel illum qui dolorem eum fugiat quo voluptas nulla pariatur? At vero eos et accusamus et iusto odio ducimus qui blanditiis.
Cras ultricies mi eu turpis hendrerit fringilla. Vestibulum ante ipsum primis in faucibus orci luctus et ultrices posuere cubilia Curae; In ac dui quis mi consectetuer.
Temporibus autem et aut officiis debitis aut rerum necessitatibus saepe eveniet ut et voluptates repudiandae sint et molestiae non recusandae. Itaque rerum hic tenetur.
Strong (Bold)
Use <strong>
or <b>
tags around the text you want in bold.
Emphasis (Italics)
Use <em>
or <i>
tags around the text you want emphasized.
Hyperlinks
Use the HTML <a href="">
tag.
Note
In URLs, be sure to escape any special characters, such as double quotation marks ("
) or backslashes (\
), using a backslash (\
). For example, <a href=\"http://www
.
To add a hyperlink to another component in the same article, use an anchor link that starts with the hash symbol (#) and is followed by the identifier
property for the component you want to link to.
This example shows a link to a chapter
component with its identifier
set to chapter-1
:
The text continues in <a href=\"#chapter-1\">Chapter One</a>.
To link to a component in another article, you must include an Apple News URL followed by the hash symbol (#) and component identifier as shown here:
The recipe is <a href=\"https://apple.news/A5vHgPPmQSvuIxPjeXLTdGQ#TextComponent-1\">here</a>.
Lists
Use the <ul>
tag to start an unordered (bulleted) list and the <ol>
tag to start an ordered (numbered) list. Use the <li>
tag to indicate each item in a list.
For example, this HTML code:
<ul><li>apples</li><li>oranges</li></ul>
Results in this unordered, bulleted list:
apples
oranges
This HTML code:
<ol><li>apples</li><li>oranges</li></ol>
Results in this numbered list:
apples
oranges
Line Breaks
To create a single line break, use the <br>
or <br/>
tag.
For example, this HTML code:
<p>Apple<br>1 Infinite Loop<br>Cupertino, CA</p>
Results in three lines of text using single line spacing:
Apple
1 Infinite Loop
Cupertino, CA
Subscript and Superscript
Use <sub>
or <sup>
tags around the text.
Strikethrough
Use <del>
or <s>
tags around the text.
Preformatted Text
To represent preformatted blocks of text and preserve their white space, use the <pre>
tag around the block.
For example, this coded text:
<pre>var occupations = [\n\t"Malcolm": "Captain",\n\t"Kaylee": "Mechanic"\n]</pre>
Results in:
var occupations = [
"Malcolm": "Captain",
"Kaylee": "Mechanic"
]
For information on displaying the contents of your <pre>
tag using a monospaced font, see Text Styling.
Code
To add text that represents code to your article, use the HTML <code> or <samp> tags around the text.
For information on displaying the contents of your <code>
or <samp>
tag using a monospaced font, see Text Styling.
Footer
To define a footer that isn’t part of the main story—like an author biography or copyright notice—use <footer>
tags.
Aside
You can use <aside>
tags to define a section of the text that is related to, but not part of, the main story. Using an Aside component has the additional benefit of helping Siri make more informed recommendations.
Block Quote
To set off a long quotation (or any text) in your article, you can use the HTML <blockquote>
tag. However, if you want to use different margins for your block quote, use the Apple News Format Quote component instead.
Text Styling
You can change the appearance of text in your article using styles from Apple News Format, HTML tags, or a combination of both. The following sections show you how to use HTML with Apple News Format text styles.
Default Styles for Tags
You can create text styles that will automatically get applied to HTML-tagged text, by using special names for your text style objects in ArticleDocument.textStyles. Once you define the style for a specific HTML tag, then all occurrences of the HTML tag in your article will receive that same text style.
For example, if you create a text style called default-tag-pre
as shown here, all occurrences of the HTML <pre>
tag in the article will use the monospaced Menlo-Regular font and be dark gray.
"textStyles": {
"default-tag-pre": {
"fontName": "Menlo-Regular",
"textColor": "#333"
}
}
References to Text Styles
You can also refer to any of your text styles by name in supported HTML tags. Within your HTML tag, use the data-anf-textstyle
attribute to refer to the text style you want to use for your HTML-formatted text component.
For example, if you already have a custom text style called author
, you can refer to it from within your HTML code:
"components": [
{
"role": "body",
"format": "html",
"text": "<p>This document is written by <author data-anf-textstyle=\"authorNameStyle\">John Appleseed</author></p>"
}
]
Special Characters
Apple News Format supports special characters that are encoded as HTML entities. This includes named entities like "
; (for a double-quote character) or &infin
; (for an infinity sign (∞)), as well as numeric entities like ©
; (for a copyright symbol (©)).
HTML Attributes
Apple News Format ignores most attributes on your HTML tags, but there are some exceptions. You can use:
The
href
attribute of the<a>
tagThe
data-anf-textstyle
attribute on all supported tags
Unsupported HTML Tags
Following is a list of unsupported HTML tags. An article containing HTML formatting with these tags will be rejected.
Unsupported tag | Replacement tag |
| Use the Photo, Portrait, Figure, or Logo component instead. If none of those components describes your content, you can use the generic Image component. |
| Use the Video or EmbedWebVideo (for YouTube and Vimeo video) component instead. |
| Use the Audio component instead. |
| There is no replacement for this tag. |
| There is no replacement for this tag. |
| There is no replacement for this tag. |
| There is no replacement for this tag. |
| There is no replacement for this tag. |
| There is no replacement for this tag. |
| There is no replacement for this tag. |
| There is no replacement for this tag. |
| There is no replacement for this tag. |
| There is no replacement for this tag. |
| There is no replacement for this tag. |
| There is no replacement for this tag. |
| There is no replacement for this tag. |
| There is no replacement for this tag. |