As of April 20, 2023, the Instant Articles API no longer returns data. Instant Articles API endpoints cannot be called on v17 or later and will be removed entirely on August 21, 2023.

Creating an Instant Article

This guide introduces the basic structure of Instant Articles documents. It also explains how to create Instant Article versions of standard web-based content. A sample article is provided to demonstrate the use of Instant Articles markup.

An Instant Article is an HTML document optimized for fast mobile performance, rich storytelling capabilities, branded design and customized visual display. Instant Articles use standardized markup language to apply styles and functionality to a story. This markup can be handled automatically, to enable automated publication of an entire content feed at scale. Or, it can be applied manually, to create bespoke stories that take advantage of unique Instant Article capabilities and rich-media elements. This guide provides a general overview of Instant Articles markup, but for detailed guidance refer to the Instant Articles Format Reference.

Once you're familiar with the Instant Articles document structure described here, read our Publishing Instant Articles guide to learn how to publish Instant Articles on Facebook, manually or automatically.

Requirements

Instant Articles are managed within the framework of a Facebook Page. To begin publishing Instant Articles, you must have:

An existing Facebook Page.
An Admin or Editor role on the Page.

If you don't already have an existing Page, create a new one.

Instant Articles are available on iPhones and Android devices. Required software is Facebook for iPhone Version 30.0 and iOS 7.0 and above, or Facebook for Android Version 57 and Android Jelly Bean and above.

How to Format an Instant Article

Instant Articles are created with HTML, so specifying page elements is done in a way that's similar to standard web publishing. In many cases, publishers can reuse code created for their web-based articles to generate versions that work as Instant Articles.

CSS is not supported for styling. Refer to our Design Guide for instructions on creating and modifying styles.

1. Required Article Elements

Every Instant Article requires some basic information to specify how the article should be presented to readers. This metadata is defined in the <head> of the HTML document, and it includes information such as the canonical URL (which ties the Instant Article back to its web-based counterpart) and the specific style that should be applied to the content.

A canonical link is required in the <head> of every Instant Article, and this must be an absolute URL. If this URL is not present, Facebook will display the canonical link defined for the <item> in your RSS feed. If a canonical link is not provided in either the article's <head> or in the RSS feed, Facebook will ignore the article.

<head>
  <meta charset="utf-8">
  <meta property="op:markup_version" content="v1.0">

  <!-- The URL of the web version of your article --> 
  <link rel="canonical" href="http://example.com/article.html">
  
  <!-- The style to be used for this article --> 
  <meta property="fb:article_style" content="myarticlestyle">
</head>

For additional detail on how to set up article-level configurations of your Instant Article, refer to the Instant Articles Format Reference.

2. Specifying The Article Header

When readers first open an Instant Article, they see an article header which acts as a visual "cover" for the body content. The header of each Instant Article is specified by the elements in the <header> section of the <article> block, which lives in the <body> of the HTML document. These elements include:

Media type: Image or Video
Title
Subtitle
Author(s)
Kicker
Published Time
Modified Time

You can select which elements of the published time (day, date, month, year and time) will appear in your articles in the Style Editor tool. Learn how to do this in the Creating and Modifying Styles section of the Instant Articles Design Guide.

<body>
  <article>
    <header>
      <!-- The cover image shown inside your article --> 
      <figure>
        <img src="http://mydomain.com/path/to/img.jpg" />
        <figcaption>This image is amazing</figcaption>
      </figure>
      
      <!-- The title and subtitle shown in your article -->
      <h1> Title </h1>
      <h2> Subtitle </h2>

      <!-- A kicker for your article -->
      <h3 class="op-kicker">
        This is a kicker
      </h3>

      <!-- The author of your article -->
      <address>
        <a rel="facebook" href="http://facebook.com/brandon.diamond">Brandon Diamond</a>
        Brandon is a avid zombie hunter.
      </address>

      <!-- The published and last modified time stamps -->
      <time class="op-published" dateTime="2014-12-11T04:44:16Z">December 11th, 4:44 PM</time>
      <time class="op-modified" dateTime="2014-12-11T04:44:16Z">December 11th, 4:44 PM</time>
    </header>
  </article>
</body>

For additional detail on how to configure the cover of an Instant Article, refer to the Instant Articles Format Reference.

3. Body Content Formatting

The standard HTML elements that define the body elements of your web-based articles also define the corresponding elements for the Instant Article version. Body text in your article is defined using <p> tags, while image and video content is defined using <figure> elements.

<body>
  <article>
    <!-- Body text for your article -->
    <p> This is some Instant Article content. </p> 

    <!-- A video within your article -->
    <figure>
      <video>
        <source src="http://mydomain.com/path/to/video.mp4" type="video/mp4" />
      </video>
    </figure>

    <!-- An image within your article -->
    <figure>
      <img src="http://mydomain.com/path/to/img.jpg" />
      <figcaption>This image is amazing</figcaption>
    </figure>

  </article>
</body>

4. Creating Rich-Media Elements

In addition to standard article body text, Instant Articles also provide support for rich media elements, such as interactive maps. These elements are implemented with simple HTML, and they are implemented natively within Instant Articles to provide a crisp reader experience. Special elements include:

Slideshows
Interactive Maps
Geotagged Media

<body>
  <article>
    <!-- A slideshow within your article -->
    <figure class="op-slideshow">
      <figure>
        <img src="http://mydomain.com/path/to/img1.jpg" />
      </figure>
      <figure>
        <img src="http://mydomain.com/path/to/img2.jpg" />
      </figure>
      <figure>
        <img src="http://mydomain.com/path/to/img3.jpg" />
      </figure>
    </figure>
        

    <!-- A map within your article -->
    <figure class="op-map">
      <script type="application/json" class="op-geotag">  
        {
          "type": "Feature",
          "geometry": 
            {
              "type": "Point",
              "coordinates": [ [23.166667, 89.216667], [23.166667, 89.216667] ]    
            },    
          "properties": 
            {      
              "title": "Jessore, Bangladesh",      
              "radius": 750000,      
              "pivot": true,      
              "style": "satellite",
            }
        }  
      </script>
    </figure>

    <!-- A geotagged image -->
    <figure>
      <img src="http://mydomain.com/path/to/img.jpg" />
      <script type="application/json" class="op-geotag">  
        {
          "type": "Feature",    
          "geometry":
            {      
              "type": "Point",
              "coordinates": [ [23.166667, 89.216667], [23.166667, 89.216667] ] 
            },    
          "properties":
            {
              "title": "Jessore, Bangladesh",
              "radius": 750000,
              "pivot": true,
              "style": "satellite",
            }  
        } 
      </script>
    </figure>

    <!-- An image-->
    <figure>
      <img src="http://foo.com/1.jpg"/>
      <figcaption>Image caption</figcaption>
    </figure>

  </article>
</body>

5. Adding Embedded Media

You can embed external media directly within your Instant Article. External media may include interactive graphics from your website, content from social networks or advertisements. Embedded content is defined using the standard HTML <figure> element, with specific classes provided for different types of content, as shown here:

<body>
  <article>
    <!-- An interactive graphic -->
    <figure class="op-interactive">
      <iframe class="no-margin" src="http://example.com/custom-interactive" height="60"></iframe>
    </figure>

    <!-- A post from Instagram -->
    <figure class="op-social">
      <iframe>
        <!-- Include Instagram embed code here -->
      </iframe>
    </figure>

    <!-- An advertisement -->
    <figure class="op-ad">
      <iframe src="https://www.adserver.com/ss;adtype=banner320x50" height="60" width="320"></iframe>
    </figure>

  </article>
</body>

6. Configuring A Feed Preview

When a reader encounters your Instant Article in Facebook's Feed, they are shown a preview of the article (in much the same way article previews are shown in Feed for the web version of articles). By default, the Feed preview for an Instant Article displays with the same title, description, and image as the web-based version of your article. This information is defined using the Open Graph meta tags located in the <head> of the web version of your article.

This information is not defined directly in the markup for the Instant Articles version of the article. It must exist in the web version of your article.

<head>
  <meta property="og:title" content="Article title">
  <meta property="og:description" content="Article description">
  <meta property="og:image" content="http://myserver.com/image.jpg">
</head>

Publishing and Editing Articles

You can automate the publication of Instant Articles on Facebook with secure RSS feed. In addition, Facebook provides a web-based article editor that's accessible through your Facebook Page. The editor tool enables you to manually edit and publish individual Instant Articles.

For details on how to publish Instant Articles, refer to the Publishing Instant Articles guide.

Sample Article

This sample article demonstrates the structure of a typical Instant Article and outlines how each of the components are formatted. This article is provided solely for illustrative and testing purposes.

To live-demo this article in your Instant Articles CMS, a few changes are required:

Change the domain in the canonical URL to match the domain where your web articles are published.
Change dummy source URLs of the image, video, and ad examples to point to live content from your site.

<!doctype html>
<html lang="en" prefix="op: http://media.facebook.com/op#">
  <head>
    <meta charset="utf-8">
    <!-- URL of the web version of this article -->
    <!-- TODO: Change the domain to match the domain of your website -->    
    <link rel="canonical" href="http://example.com/article.html">
    <meta property="op:markup_version" content="v1.0">
  </head>
  <body>
    <article>
      <header>
        <!-- The title and subtitle shown in your Instant Article -->
        <h1>Article Title</h1>
        <h2>Article Subtitle</h2>

        <!-- The date and time when your article was originally published -->
        <time class="op-published" datetime="2014-11-11T04:44:16Z">November 11th, 4:44 PM</time>

        <!-- The date and time when your article was last updated -->
        <time class="op-modified" dateTime="2014-12-11T04:44:16Z">December 11th, 4:44 PM</time>

        <!-- The authors of your article -->
        <address>
          <a rel="facebook" href="http://facebook.com/brandon.diamond">Brandon Diamond</a>
          Brandon is a avid zombie hunter.
        </address>
        <address>
          <a>TR Vishwanath</a>
          Vish is a scholar and a gentleman.
        </address>

        <!-- The cover image shown inside your article --> 
        <!-- TODO: Change the URL to a live image from your website -->    
        <figure>
          <img src="http://mydomain.com/path/to/img.jpg" />
          <figcaption>This image is amazing</figcaption>
        </figure>   

        <!-- A kicker for your article --> 
        <h3 class="op-kicker">
          This is a kicker
        </h3>        

      </header>

      <!-- Article body goes here -->

      <!-- Body text for your article -->
      <p> Article content </p> 

      <!-- A video within your article -->
      <!-- TODO: Change the URL to a live video from your website -->    
      <figure>
        <video>
          <source src="http://mydomain.com/path/to/video.mp4" type="video/mp4" />
        </video>
      </figure>

      <!-- An ad within your article -->
      <!-- TODO: Change the URL to a live ad from your website -->    
      <figure class="op-ad">
        <iframe src="https://www.adserver.com/ss;adtype=banner320x50" height="60" width="320"></iframe>
      </figure>

      <!-- Analytics code for your article -->
      <figure class="op-tracker">
          <iframe src="" hidden></iframe>
      </figure>

      <footer>
        <!-- Credits for your article -->
        <aside>Acknowledgements</aside>

        <!-- Copyright details for your article -->
        <small>Legal notes</small>
      </footer>
    </article>
  </body>
</html>