Instant Articles Builder

With the Instant Articles Builder, you are able to specify the template for your Instant Articles simply by pointing and clicking on the visual elements of your mobile web articles. This template is used to map the content in your mobile web articles to Instant Articles, which will then be rendered to your readers within Facebook's mobile apps.

You can download and install the Instant Articles Builder from the bundled distribution or use the source code from Github.

Installation

Download the package for Mac and Windows or build the package on your environment from the source.

Once installed, start the Instant Articles Builder application. You should see a screen like this:

UI Components

The Instant Articles Builder resembles a web browser with few more specific features.

  1. Address bar: where you type the URL for the article used to generate the rules.
  2. Web browser: where you see the article rendered just like in any regular web browser.
  3. Rules management area: Where you save, edit and open rule sets; and configure each single rule.
  4. Preview: Where you can see the Instant Article markup generated with your rules, or the preview of the rendered Instant Article.

1. Address bar

The address bar works exactly as in your web browser, where you can type the exact article URL you want or type the website home page and then navigate to a sample article. To load the page you should hit ENTER or the "Go!" button.

2. Web browser

This portion of the tool will render the web page just like any regular browser and can be used to navigate to other articles by clicking on any link.

3. Template configuration area

The template configuration area is where you connect your template to your mobile website.

Check this video for an example of a simple configuration:

File toolbar

The main project management toolbar holds 3 actions:

  • New: Resets and starts from scratch a new template. Recommended to be used every time you change domains or navigate to a new website that holds a different HTML structure.
  • Open: Loads a previously saved template. You will need to pick the file from your file system. The files typically have the .json extension.
  • Save: Saves the template to a file.

Elements

Each template element will match to a component of your site. The elements are matched from bottom up, so if you want a element to be matched before some others, you must ensure that element is on the bottom. To perform the reordering you can drag-and-drop the elements by clicking and holding on the element name.

Currently, the tool only supports CSS Selectors. While the Instant Articles SDK also supports XPath selectors, these are not yet supported by the Instant Articles Builder.

Element Name Description HTML components SDK reference Rule

Article

[added by default, must be be configured]

Mostly used to describe the full document and finding each key element:

Title: The article title

Author: The article author

Article URL: This generally lies as a hidden field on the HTML, so we pre-fill it with the most common selector.

Content: The element that encapsulates the article content, must exclude other elements like the menu, the navigation bar for the site and anything else except the article content itself.

This is the main document, so a good selector for it is the html.

Title: Generally pointing to H1, using as selector: h1

Author: The article author

Article URL: This generally lies as a hidden field on the HTML, so we pre-fill it with the most common selector.

Content: Points to the article content, be sure you remove menus, navigation bar for site and anything else except the content.

GlobalRule

Footer

Mostly used for pointing to footer notes or considerations about the article

selector: Select the outter most tag container of the footer.

Generally credits and copyrights goes into this section.

See more: Footer reference

FooterRule

Sponsor

Mostly used for pointing to branded content information

selector: Select the outter most tag container of the branded content information.

For branded content. See more: Branded content reference

SponsorRule

Block Quotation

[provided by default]

Mostly used for pointing to <blockquote\> tags

selector: blockquote

Blockquote tags. See more: Blockquote reference

BlockquoteRule

Bold Text

[provided by default]

Mostly used for pointing to <b\> or <strong\> tags

selector: b, strong

Bold tags. See more: Text reference

BoldRule

Emphasized Text

[provided by default]

Mostly used for pointing to <em\> tags

selector: em

Emphasized tags. See more: Text reference

EmphasizedRule

Italic Text

[provided by default]

Mostly used for pointing to <i\> tags

selector: i

Italic tags. See more: Text reference

ItalicRule

Link

[provided by default]

Mostly used for pointing to <a\> tags

selector: a

Anchor tags. See more: Text reference

AnchorRule

List

[provided by default]

Mostly used for pointing to <ul\> or <ol\> tags

selector: ul, ol

Ordered or Unordered list tags. See more: List reference

ListRule

List Item

[provided by default]

Mostly used for pointing to <li\> tags

selector: li

List item. See more: List reference

ListItemRule

Paragraph

[provided by default]

Mostly used for pointing to <p\> tags

selector: p

A paragraph on text. See more: Text reference

ListItemRule

Subtitle, Header (h2)

[provided by default]

Mostly used for pointing to <h2\> tags

selector: h2

A sub title or title level 2 See more: Header reference

H2Rule

Title, Header (h1)

[provided by default]

Mostly used for pointing to <h1\> tags

selector: h1

A title or title level 1 See more: Header reference

H2Rule

Caption

This is a caption to videos, images or slideshows. Any text that goes together with the image, should be configured using this rule.

Generally the HTML tags for this particular usage are the <caption> tags. See more: Caption reference

CaptionRule

Embed

This is the configuration for transforming Embed codes from Facebook, Twitter, Instagram, YouTube or any other code snippet for embed component. Any component not supported by Instant Articles should use this rule. Example: infographics, table, etc.

Generally the HTML tags for this particular usage are the outermost <div> from <iframe> tags. See more: Embeds reference

EmbedRule

Image

This is the configuration for transforming Images. Generally a point-and-click should be enough for selecting images. Pro-tip: In case of images that contains captions, be sure you select the outermost container for the image that contains not only the image but also the caption container tags.

Generally the HTML tags for this particular usage are the simplest <img>. See more: Embeds reference

ImageRule

Slideshow (Container)

This is the configuration for transforming Carousel, Galleries or Slideshows that contains images. Pro-tip: Be sure you select the outermost container (generally a div) of the set of images.

Generally the HTML tags for this particular usage are <div> with some specific container for the slideshow, carousel or gallery. See more: Slideshow reference

SlideshowRule

Slideshow Image

This is the configuration for transforming Images that are part of a carousel or slideshow. Generally a point-and-click should be enough for selecting images. Pro-tip: In case of images that contains captions, be sure you select the outermost container for the image that contains not only the image but also the caption container tags.

Generally the HTML tags for this particular usage are the simplest <img>. See more: Slideshow reference

SlideshowImageRule

Video

This is the configuration for transforming Videos on native format, which means the video should point to a open standard format on web. Pro-tip: In case of videos that contains captions, be sure you select the outermost container for the image that contains not only the image but also the caption container tags.

Generally the HTML tags for this particular usage are the simplest <video>, referencing to a playable video on the browser. If your video has a signed client or need to use any kind of signed stream service you shouldn't use the Video rule converter, you should use the Embed instead. See more: Video reference

VideoRule

Related Articles (Footer)

This is the configuration for Related Articles that goes into the footer section.

If you use a internal system for related articles from your own service, you can plug those into this article being converted by using this Related Articles (Footer) section. See more: Related Articles reference

RelatedArticleFooterRule

See that this rule should point to the outermost container HTML tag, so you can apply the RelatedArticleItem rule afterwards.

Related Articles (In-line)

This is the configuration for Related Articles that goes in the middle of the article, in between paragraphs or other article body elements.

If you use a internal system for related articles from your own service, you can plug those into this article being converted by using this Related Articles (In-line) section. See more: Related Articles reference

RelatedArticleRule

See that this rule should point to the outermost container HTML tag, so you can apply the RelatedArticleItem rule afterwards.

Related Item

This is the configuration for each Related Article item link from the container Related Item.

It should point to other articles. If the referred article is a Instant Article also, it will take all advantages of Instant Article renderer. See more: Related Articles reference

RelatedArticleItemRule

Ignore

This is a dangerous rule that can do great stuff if well used. Its purpose is to ignore the selected tag and all the contained children from that tag.

A good usage for this tag is to ignore HTML structures that doesn't contain article content, like ADS, menus and anything other than article content.

IgnoreRule

Pass Through

This rule purpose is to ignore the selected tag but the transformer will start to look for matches for each child of this tag.

A good usage for this tag is to ignore the outer most container structures of an HTML document that do not help in the identification of content.

PassThroughRule

Selectors - Point and click

4. Preview Area

The preview area is where most of the attention goes after connecting each element. The ultimate goal is to build up a complete Instant Article representation of the web article, converting each web component into a Instant Article correspondent component based on table above. It has two tabs to help you accomplish that goal: Preview Tab and Source Tab.

Preview Tab (Beta)

This is an experimental feature intended to provide guidance. The rendering may differ from how the actual Instant Article looks, but it helps to understand which elements are being transformed.

The Preview tab renders a simple web version of the transformed Instant Article based on your web article and the rules configured for that transformation. Since this is a visual tool, this was aimed to help you spot missing or not transformed content, so put close attention for missing text, links, images, embeds and anything else that can be missing from the web content shown on the Web browser view

Source Tab

The source tab will output the Instant Article markup generated from the web article (URL entered on address bar) matching the connected elements from left panel (Rules Management). This is the most accurate output this tool generates, since it is exactly same output generated for that particular web article and template. To learn more about the Instant Articles markup, follow the documentation about markup.

Open Source

This project is open source and you can follow, fork or even report bugs through the github repository. The Report a bug button will automatically redirect you to GitHub with an issue structure ready:

Next Steps

  1. Add rules meta-tags. Turn on automatic ingestion and transformation of your articles based on your template.