Flipboard offers a simple way for publishers to render their content in a magazine-like layout within Flipboard. When an article from a participating publisher is shared on Twitter, Facebook, or other social sites, a Flipboard user can read the full content of the article as a beautiful, paginated layout on tablets and phones.

This document describes the technical requirements, as well as best practices, for optimizing your RSS feed for Flipboard.

Optimizing your RSS feed for Flipboard

Please note that your RSS feed will need to contain all of the following before being featured by Flipboard:

1) The entire body copy of your article, not just headlines and summaries.
2) At least one image per article, no less than 400px in the smallest dimension.
3) At least 30 items.

To simplify RSS compatibility, Flipboard has leveraged the following widely-adopted open standards:

  • RSS: The standard syndication format for content on the web. Full-text RSS feeds, where the entire content of the article is included within the feed, are required.
  • HTML5 and Microformats: Additional design elements, such as pullquotes, are specified using standard web design techniques.
  • Media RSS: Assets such as images, video, and audio are included using this standard extension to RSS.
  • GeoRSS: Standard method for geotagging within RSS

Display modes in the application

Within the Flipboard application there are two important display modes that apply to how content is displayed:

Layout view: refers to the way an article looks in overview mode alongside other items. In this mode an image, title and an image or video is displayed to give the reader an idea of the content of the item. A snippet of text referred to as the excerpt is used if available and taken from the main content of the article or explicitly defined using special html attributes defined below.

Detail view: This refers to the view of the item when the user clicks on an item in layout view. This will display the full content of the article. Flipboard displays articles in a “paginated” fashion which means the reader can flip from one page to the next. This necessitates some intelligence in how media is placed so as to not disrupt the reading flow. In particular images may not necessarily be placed in the same position as they appear in the article. This is done for aesthetic reasons to maximize the “magazine” feel of the article. Where it is desired to have the image be placed in exactly the same place as it appears in the article there are “inline” image directives that tell the system to do that.

Certain directives described below apply to either layout view (for example fine-tuning what excerpt is generated for an item) or detail view.

RSS display format

The same RSS feed can be displayed in two major ways in the application:

Scrolling RSS: In this version all of the content in the item is preserved and the content is displayed in a minimally styled scrolling format.

Paginated RSS: In this version any known ads are removed from the content and the output is displayed in a paginated format. Optionally ads may be interspersed between pages in the content.

Conceptually an RSS feed consists of a “container” specified in xml that contains rss entries. Each RSS entry can contain several attributes encoded as xml elements such as the title, date of publication, and so on. In addition certain elements such as “<content:encoded>” contain the actual content of the item specified as HTML.

The preferred container format is RSS 2.0. Within this format Flipboard uses the standard RSS 2.0 format. Within each item in an rss feed the following items:

Required Elements:

  • item — contains an individual rss entry with the following child elements:
    • title – title of the entry where any special HTML characters should be encoded so the title may be embedded in HTML content.
    • link – points to the url for this entry. The domain name of the host in the url should match the domain for the rss feed itself.
    • content:encoded – If there are no MRSS elements included in the entry then content:encoded is required and contains the content of the article as HTML markup enclosed in a CDATA section. An item can consist of both a content:encoded section and MRSS elements and this situation is discussed further below. These elements are not required but it is highly recommended they be present in the item:
    • pubDate – The publication date of the article in RFC822 format. If not present then the system will use the first time it was processed as the publication date which may not be ideal.
    • guid – A unique id for this entry in the feed.
    • dc:creator – The author(s) of the article.
    • language – The language used in the article specified as a standard ISO 639-2 language code.
    • description – This element will only be used if the content:encoded section is missing or if it contains less text than the description element.

MRSS

Media RSS is a specification that provides for various ways to enclose attached media to the RSS item. It is allowed with the caveat that media is also allowed in the content:encoded tag using HTML5 markup. It is preferable to include media in the content:encoded section because then it can be put in context of the enclosing article. However for article types such as pure slideshows it makes sense to use MRSS to provide the list of videos/images. The question is what to do if a given image or video is included in both the MRSS section as well as the content:encoded section. In order to simplify the logic and prevent duplicate media from being included in the final result the following condition applies:

  • MRSS tags are only processed if there are no corresponding media type elements in the content:encoded section. For example if there is any image element in the content:encoded section then any images in the MRSS of the item are ignored. Similarly any videos in the content:encoded section cause videos in the MRSS section to be ignored.
  • An RSS item can consist purely of a sequence of media:content elements. In this case the content:encoded section may be missing and the description field will be used as an excerpt for the item as a whole (if present).
  • Note that according to the MRSS spec, media:group can only enclose media:content elements that consist of different representations of the same media item. Thus the proper way to encode a slideshow using MRSS is to use a sequence of media:content elements that are contained directly in the item element of the RSS item.

If your publishing system cannot handle inserting images within the <content:encoded> element, use mediaRSS to specify image assets used within an article:

The <media:content> element supports two sub-elements:

  • <media:description>: The image caption. Can be plain-text (type=plain) or HTML (type=html)
  • <media:copyright>: Copyright information or credit for the author of the asset

Having multiple image crops and resolutions provides more flexibility in layout. The <media:group> element can be used to provide alternate crops and sizes for an asset. The example below shows an image with a landscape crop as well as a portrait crop:

Article text

The content of the article is represented using a subset of standard HTML5.

Supported Tags and Structure

Whenever possible, HTML elements should respect proper nesting of inline and paragraph elements as described below. If nesting is not respected, the content is not guaranteed to render correctly.

Inline Elements

Inline elements can exist only within a paragraph (<p>, <h1>, etc — see below for definition) or another inline element. The layout engine will always assume that they are display: inline (ie. They are displayed within a paragraph). Inline elements can contain nested text and/or other inline elements. Supported inline elements include:

  • <a>: For linking text. Can also be used as a block element.
  • <abbr>, <b>, <br>, <cite>, <code>, <em>, <i>, <ins>, <kbd>, <mark>, <q>, <ruby>, <rp>, <rt>, <samp>,<small>, <span>, <strong>, <sub>, <sup>,<time>, <var>, <wbr>: Styling and/or semantic meaning.

Paragraph Elements

Paragraph elements are the only blocks which can contain text or inline elements. These elements must not contain other block elements; in other words, a <p> cannot exist within an <h1> nor vice-versa. The layout engine assumes these elements are display:block. Supported paragraph elements include:

  • <p>
  • <pre>
  • <h1>, <h2>, <h3>, <h4>, <h5>, <h6>: Only blocks that can contain inlines or text. These elements cannot contain other block elements (i.e. a <p> cannot exist within a <h1>)

Hyphenation

Text within paragraphs and headings may be hyphenated via unicode’s soft hyphens (U+00AD), but this is optional.

Block Elements

The layout engine will always assume these elements are display: block (i.e., they cannot be displayed within a paragraph). Supported block elements include:

  • <blockquote>, <div>, <section>, <header>, <footer>, <hgroup>: Used for grouping blocks, and only blocks (i.e. no inline elements or text nodes as children)
  • <a>: Can be used to wrap block elements like a <div>, or can be used within paragraphs.
  • <aside>, <figure>: Denotes content which can be placed outside of body text flow. Supports same content as <div>, with <figure> adding an optional <figcaption> as the final child (see below for detail)
  • <img>, <video>: Will typically be contained within a <figure>, but can be treated as a block as well. <img> and<video> must have width and height specified. Supports annotations for alternate versions (such as mobile resolution)
  • <ol> & <ul>: Only supports <li> as child
  • <table>: Strict content rules. Support planned in the near future, but not currently implemented for paginated output. Will still work on scrolling rss output.

Some blocks are only allowed within specific blocks:

  • <li>: Permitted only within <ul> or <ol>. Same content rules as <div>
  • <figcaption>: Permitted as last child of <figure>. Same content rules as <div>
  • <thead>, <tbody>, <tfoot>, <colgroup>: Permitted only as children of <table>. May only contain <tr> elements
  • <tr>: Permitted as children of <thead>, <tbody>, and <tfoot>. May only contain <td> or <th>
  • <td>, <th>: Permitted as child of <tr>. Same content rules as <div>

Supported Attributes

Only a strict subset of standard HTML attributes is allowed:

  • class: For styling
  • id: For marking a specific portion of an article, not for styling. Note that the id property will be stripped in presentation, but can still be used for linking
  • hidden: Tells the layout engine to ignore an element
  • lang: Specifies content language
  • dir: Modifies direction of text flow (used for mixing right-to-left and left-to-right scripts)
  • title: Used for tooltips and some accessibility scenarios
  • itemprop: Remove the element from the text of the article and store as a property that can be referenced in templates.

Some attributes are supported only on specific elements:

  • data-fl-columnbreak and data-fl-pagebreak: Force a column or page break before the element. Only supported on block elements.
  • itemscope, data-fl-version and data-fl-href: Permitted on <article>
  • reversed, start, type: Permitted on <ul> and <ol>
  • value: Permitted on <li>
  • alt: Permitted on <img>
  • colspan and rowspan: Permitted only on <th> and <td>
  • span: Permitted only on <colgroup>

Unsupported Elements

  • <nav>
  • <form>, <input>, <button>, <select>
  • <style> & <script>: these elements will be removed from the content.
  • <object>, <embed>: Poorly supported on devices. The exception is for any social media and audio/video embeds described below.
  • <iframe>: Allows for arbitrary JavaScript which can be risky for stability, need to think about how this would work. The exception to this is for social media and audio/video embeds described below.
  • <canvas>: Useless without <script>
  • <details> & <summary>: Has interactivity and layout implications
  • Attributes:
    • style: Can lead to unpredictability in layout
    • on* event handlers: Don’t want to allow scripts to run
    • accesskey, tabindex: Only make sense for interactive elements

Media assets

Media assets referenced in markup within the <content:encoded> element are automatically downloaded and cached. The following filetypes are supported:

  • Images: JPEG, GIF, PNG
  • Video: MP4 (H.264 encoded), YouTube, Vimeo, Vine embeds
  • Audio: MP3, or SoundCloud embeds

Assets may also be included into the feed by adding <media:content> or <media:group> elements within the <item> tag. Any assets referenced within the <content:encoded> markup will be merged with <media:content> elements if the URL is an exact match. The position within the content will be preserved, but metadata and alternate resolutions specified within <media:content> will take priority. Note: Asset URLs must be identical, otherwise the article will duplicate the image.

Any assets added via <media:content> which do not occur within <content:encoded> can be automatically be appended to the content.

Images

Images can be represented in several ways. The simplest is to just use the img html tag:

If you want to include a caption for the image you can use the figure element:

You can include more complex html inside the figcaption element such as:

In this example we also use the special css class “fl:credit” to denote the copyright as an image credit. This will cause the text to be styled differently from the caption text to highlight the fact that it’s an image credit.

Figure and figcaption tags can also be used to encapsulate video elements and provide them with a caption if applicable.

An image tag can include several special attributes that control how it will be used in the article:

  • fl:hint-main-image — If set to “true” then this image will be used as the main image in the app’s layout view regardless of its position in the article.
  • fl:hint-ignore-image — If set to “true” then this image will not be used in layout view in the app though it will still be rendered in the article itself.
  • fl:hint-nocrop — If set to “true” then the app will attempt to disable any cropping of the image (sometimes this is unavoidable depending on the aspect ratio of the image)

Size & Aspect Ratios

Images must be at least 400px in the smallest dimension; any smaller images are ignored. For best results, provide images in the highest resolution possible.

For best results, use images with one of the following aspect ratios:

  • Landscape: 4:3, 16:9
  • Portrait: 3:4, 9:16
  • Square: 1:1

Images that do not use one of these aspect ratios may appear overly-cropped or be completely absent in layout.

Slideshows

To denote a sequence of images or video that constitute a slideshow you can use the section element with embedded figure elements:

In place of the section element you can also use a div element

There are other cases where the system will render images as slideshows. If an article contains no actual text but just a series of images then it will be rendered as a slideshow. Similarly a series of images at the end of an article will also be rendered as a slideshow.

External Media References

Articles may contain references to social media or external media. The intent of this spec is to allow this to be done using as close as possible the markup used by the external source.

For any social embeds or references to audio, video, or images, the reference must be publicly accessible. For example embedding a reference to an item in a private Instagram account, for example, will not be accessible to Flipboard’s servers and the item will be omitted from the enclosing content.

In general this spec aims to support the native embed format of the media in question. This is in order to provide a more natural mapping to the format and also so that the item will work either in a paginated or scrolling view. In a paginated view the relevant information is extracted and converted to a format that will work well with our pagination library. In the scrolling case the embed format will be the same as what would be encountered on a web page so it will continue to work.

Audio

Audio can be embedded in RSS items. In these cases the article will include a player UI that allows the user to stop and start the audio. Publishers may also include an optional album art attribute allows for an image to be associated with the audio item and a title that describes the item.

Soundcloud

Soundcloud embeds can consist of a single audio item or a playlist. The system will attempt to extract both into the generated article. Note that only public Soundcloud urls that are streamable are supported.

Example:

HTML5 Audio


Video

Various video formats are supported. However the only format that is guaranteed to render as an embedded video item is MP4 or HTML5 video. Other video formats may render by starting an external web view when the user hits the play button on the item.

YouTube

Only public YouTube urls are allowed. Others won’t be able to be processed by the system.

HTML5

Note that, for HTML5 videos, a valid poster image is required.

At least one source element must contain a video src of type video/mp4

Vimeo

Vine

Instagram

Instagram embeds may refer to both video and image content. The same markup is able to support both types of content.

or alternatively using Instagram’s embed format shown below. Note that the script tag is generated by Instagram but will be removed when rendered inside Flipboard and instead the Instagram media and caption will be rendered without the use of the script. The script markup is included here because it will be part of the standard embed markup for Instagram.

Twitter

Twitter embeds can consist of images or video accompanied by the tweet text, or it can be the text on its own. They should be included using the following markup:

Note that the script markup is removed when the item is processed. It is included in this example to demonstrate the concept using standard Twitter embed markup.

For example the following embed code was generated from an actual tweet using Twitter’s embed api:

Facebook

Facebook embeds may contain text, images or video. In all cases only public Facebook posts will be processed correctly. The format of the reference to the Facebook post should be:

  • <div class=“fb-post” data-href=“facebook_url_to_the_post”> ... </div>
  • <div class=“fb-video” data-href=“facebook_url_to_video”> ... </div>

Only the url in data-href is used to get the content so the contents of the div in either case are ignored.

Article Excerpts

In general the system will generate an excerpt of the article automatically by looking at the start of the article text specified in the content:encoded section. However it is possible to customize how this excerpt is generated.

To do this there are some special attributes that can be added to any text element in the content:encoded section:

  • fl:fl-excerpt-only – If this attribute is “true” for an element, then that element will be included in the excerpt but not in the main article text.
  • fl:fl-noexcerpt – If this attribute is “true” then the element will not be used in the article’s summary.
  • fl:fl-excerpt – If this attribute is “true” then this element will be included in the excerpt.

Note that if the above attributes are included in any element in the content section then the system will assume that manual control is desired for excerpt generation and automatic excerpt extraction is disabled. For example this means that if fl:fl-excerpt or fl:fl-excerpt-only is used then only those elements with those attributes will be in the excerpt in sequential order according to the order of how they appear in the content.

Best Practices

  • Make sure your feed is valid RSS using the W3C Feed Validator
  • Articles should be at least 700 characters or 150 words long
  • Update the <pubDate> when updating an item
  • Images
    • Include at least one image, at least 600px wide
    • Keep your image captions short, one or two sentences at most
    • Avoid images with non-standard aspect ratios
  • URLs
    • Use clean and consistent URLs. Use the same URLs used by RSS when posting on Twitter, Facebook, or social networks.
    • Specify Canonical Links via <link rel=canonical> on all pages.
    • Include a link to your RSS feed on every page via <link rel=alternate>
    • Some content management systems (such as WordPress) can generate an RSS feed per article. If supported, enable this option and include a reference via <link rel=alternate>

Below is a sample of an RSS 2.0 feed with two stories:

References