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.
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:
The Instant Articles Builder resembles a web browser with few more specific features.
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.
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.
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:
.json extension.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:
| This is the main document, so a good selector for it is the
| GlobalRule |
Footer | Mostly used for pointing to footer notes or considerations about the article
| Generally credits and copyrights goes into this section. See more: Footer reference | FooterRule |
Sponsor | Mostly used for pointing to branded content information
| For branded content. See more: Branded content reference | SponsorRule |
Block Quotation [provided by default] | Mostly used for pointing to
| Blockquote tags. See more: Blockquote reference | BlockquoteRule |
Bold Text [provided by default] | Mostly used for pointing to
| Bold tags. See more: Text reference | BoldRule |
Emphasized Text [provided by default] | Mostly used for pointing to
| Emphasized tags. See more: Text reference | EmphasizedRule |
Italic Text [provided by default] | Mostly used for pointing to
| Italic tags. See more: Text reference | ItalicRule |
Link [provided by default] | Mostly used for pointing to
| Anchor tags. See more: Text reference | AnchorRule |
List [provided by default] | Mostly used for pointing to
| Ordered or Unordered list tags. See more: List reference | ListRule |
List Item [provided by default] | Mostly used for pointing to
| List item. See more: List reference | ListItemRule |
Paragraph [provided by default] | Mostly used for pointing to
| A paragraph on text. See more: Text reference | ListItemRule |
Subtitle, Header (h2) [provided by default] | Mostly used for pointing to
| A sub title or title level 2 See more: Header reference | H2Rule |
Title, Header (h1) [provided by default] | Mostly used for pointing to
| 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 | 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 | 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 | 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 | 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 | 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 | 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
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.
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:
