A Guide to Good Templates

This page lists general rules and detailed clarifications for creating good Instant View templates for news articles.

For more info on templates, see our Introduction and Sample Templates.

General Rules

Instant View templates must meet these five basic requirements:

1. IVs must only be generated for pages that need them

Instant View pages work best with relatively static articles. Dynamic pages (such as the main page of a news site) that are constantly refreshed with new links and media don't need IV.

Templates should only generate IV pages for articles and should not affect service areas of websites, as well as any other sections unsuitable for IV. IV pages should not be generated for articles that have content which is not supported in IV since this would result in unacceptable loss of information (e.g., IV pages don't support dynamic maps — if you generate an IV page for a wiki article with a dynamic map, the IV version will be missing a key element).

2. All essential content must be preserved

IV pages should show the entire text of the article, along with all its formatting, media, and embedded content. This includes headings, subheadings, quotes, captions, photos, videos, links, etc.

3. Unnecessary elements must be removed

IV pages should display only the source’s content – removing all interface elements, advertisments and irrelevant embedded material.

4. Template must process all the pages it covers

Pages with irregular elements should be processed correctly. All media, embeds, quotes and separators should be properly displayed.

5. No extraneous info may be added

Any attempt to add content that is not present on the original page will cause your template to be rejected.

You may include the username of websites’ official channels in Instant View templates. The username is assigned to the channel property, and to be considered official, the channel must be labeled as such by the company or person who published it (on its website or social media).

More detailed criteria and clarifications are available below.

Submitting Templates

You can submit your template for review as soon as it covers a sufficient number of articles. Make sure you've enabled Track Changes for at least 10-15 different pages on the target website and that all IV pages are generated correctly.

When ready, simply tap Submit Template next to a template in the My Templates section:

Submitting a template from My Templates

Finding Issues

Anyone can check how well Instant View templates process articles on their respective websites, and may submit feedback using the Report Issue button.

Click to select and highlight incorrectly parsed blocks in the source page or in the Instant View result and provide a detailed explanation of what is wrong (check the criteria below for ideas). The author of the template will be able to see all issues, fix and resubmit their work.

Perfect Templates

To make it easier to report issues in Instant View templates, we’ve compiled this list of characteristics that make a perfect template. Please use the list below as a reference when looking for issues in templates.

1. IV Targets: Must Generate

Templates must generate Instant View pages for all relevant pages on the target website.

1.1. Pages with static article-like content

News articles
Blog posts
Guides
Wiki entries
Documentation
Etc.

Tip: It may be a good idea to identify a common feature of all the IV-positive pages and add rules so that the template only applies to them. Note that these pages only need IV pages if their essential content is supported in the IV format — otherwise, see 2.3.

2. IV Targets: Must NOT Generate

Templates must not generate Instant View content for pages of the following types:

2.1. Pages with dynamic content

Dynamically updated lists of articles
Catalogs
Forum threads
Search pages and search results
Etc.

Tip: IV pages are cached. As articles get older, their cached IV pages update less frequently. Any pages that update content in real time would subsequently display outdated IV pages to users — which is unacceptable.

2.2. Pages that require significant interaction

Service areas of websites, such as Contact pages with forms
Store areas of websites, such as pages where users can buy products
Etc.

Tip: While it's possible to modify interactive components of a page into simple links, the IV format was primarily designed to allow Telegram users to enjoy web content in a quick and uniform way. Interacting with websites, buying things, writing reviews, etc. are outside of the current scope for IVs.

2.3. Pages featuring content not supported by the IV format

Pages with unsupported embedded content that can't be displayed
Any other unsupported content

Tip: The rule is simple. If an essential part of an article is not available in the Instant View format, an IV page must not be generated. In most cases, this will happen automatically but template creators can further protect their templates from data loss by marking any unsupported essential content using the @unsupported function. See this section for advice on handling unsupported videos.

2.4. Inaccessible pages

Pages that are fully or partially behind a paywall.
Pages that are only accessible after logging in, etc.

3. Essential Content

All essential content must be presented on the Instant View page.

3.1. General properties

The title must be shown on the IV page (may need to include the kicker).
The subtitle must be shown on the IV page if a subtitle exists in the source.
The date of publication must be shown on the IV page if the date of publication is mentioned anywhere in the source (including meta tags).

These properties are also essential, but not always present or supported in IV:

Author name can be shown on the IV page if an author is specified in the source.
Author name on the IV page can link to the author URL if an author URL is specified in the source.
The main image can be shown as a cover on the IV page if a suitable image exists in the source.
NEW Right-To-Left pages (Arabic, Persian, Hebrew, etc.) must have the dir="rtl" attribute set.

Important: See our Clarifications below for tips on how to best process cover images, date and time, author names and URLs, and other tricky elements.

3.2. Link preview

The link preview must include a photo if a suitable image or document exist in the source.
If the page has a cover but the metadata contains no image or contains the generic site logo, you must use the cover as the photo.
The link preview requires a description.
If a short description exists in the source, it must be used for the link preview (OpenGraph descriptions, lead sections, etc.).
If the description in the metadata (routinely) doesn’t describe the contents of the article, your template must create a description using the subtitle or lead section, first paragraph, etc.
The site_name property must include the name that users see on the main page of the website (examples here).
It is advisable to generate proper link previews even for pages that do not generate an IV.

Note: Telegram apps will show site_name in the header of the IV. It must match the name that users see on the main page of the website (see examples) and it must not contain any additional data. For this reason metadata should not be used blindly. If the main page doesn’t display a site name, use the name they use on social networks (Telegram channels have priority).

3.3. Supported elements

All important media (images, videos, slideshows, and other content that is relevant to the article) that exists in the source must be formatted accordingly.
Media captions must be included with the corresponding media, provided they exist in the source and can be reliably identified.
Credits in quotes and media captions must be formatted correctly.
Dividers must be converted to simplified dividers on the IV page if dividers exist in the source.
Anchor links must work properly on IV page if anchor links exist in the source.

Tip: Check that pages featuring unsupported content do not generate IV pages. In most cases, this will happen automatically, but it is a good idea to confirm this before submitting your template. Mark any unsupported essential content using the @unsupported function. See this section for advice on handling unsupported videos.

4. Content to be Removed

Anything that is not essential to the article in question should be removed from the Instant View page, including:

Main navigation bars and menus (essential navigation may be adjusted to simple links)
Top bars
Side bars (can potentially be adjusted and appended to bottom of IV page)
Footers
Unsupported widgets (check supported embeds)
Advertisements
Banners
Social media links and buttons, including “Share” and “Like”
Other buttons (if it is essential, it must be simplified into a link)
Etc.

5. Extraneous Content

The resulting IV page may not contain any content not present in the original.

No signatures or information about the template's author
No extra links or ads of any kind
Etc.

Tip: You may display the official Telegram channel of the website that published the article at the top of the IV page (by using the channel property). To be considered official, the channel must be labelled as such somewhere on the source website (doesn't have to be on the same page as the original article).

6. Clarifications

Below are some clarifications for the trickier aspects of creating perfect Instant View templates.

GENERAL PROPERTIES

6.1.1 Author name

Author name is required only if it is presented in the source article in a consistent, clear and identifiable way (in an html block with particular properties), especially if there's a name of an actual person.

In less obvious cases, what the user sees when viewing the original article in a browser has priority over invisible meta-information. Names of actual people are always preferable over entity names like 'team' or the name of the website.

You may omit the author in cases where no name can be seen by a regular user opening the original article in the browser. You may omit the name when there's no identifiable person, only the website's 'team', 'editors', 'website name' etc.

Absent author names for articles in which no author can be easily identified by a regular viewing user are not considered an issue.

6.1.2 Date and time

The date of publication is obligatory for news publications. It must be obtained by any means possible, including meta tags, etc. If the date is specified correctly, time is optional.

If conflicting dates are stored in multiple places on the source page, preference should be given to the time that is visible to an ordinary user who views the page in a browser.

The IV editor's 'Preview' section will always show the date/time in UTC format, while the 'Original' section may use a different time zone. It is possible for a perfect template to display a date/time that looks different than the original.

Support for time zones is optional, unless the time zone is reliably identifiable from the source, in which case it’s obligatory.

Tip: If given 'date published' and 'date last edited', use 'date published' for articles. For wiki-like entries 'date last edited' must be used.

6.1.3 Subtitle

A subtitle is a subordinate title of a published work or article giving additional information about its content. If this is present in the original article, a subtitle is required. Here's an example of a subtitle:

A Subtitle

Few publications actually use subtitles. More commonly, short summary sentences are shown below the title (and are called standfirst in the UK). These summary sentences are usually short and are not part of the article's text. It is advisable but not required to represent them as subtitle elements. Here's an example:

A Summary

6.1.4 Lead paragraph

Many publications use a slightly different style for their lead paragraphs. Unlike subtitles and summaries, the lead paragraph is part of the article's text. Even if the lead uses a different style from the rest of the text, it is less desirable to present it as a subtitle — but this is not a critical issue.

If the lead paragraph uses a different style, it is recommended to use bold or italic text.

A summary, then lead in bold

In the example above, the lead paragraph is highlighted in bold: “TAXI giant Uber has reportedly fired over 20 workers following an internal investigation into sexual harassment allegations.”

The article then continues: “The company told staff of the layoffs on Tuesday and related claims by law firm Perkins Coie, a person close with the case told Bloomberg.” It would be acceptable to present the “TAXI giant Uber…” paragraph as bold, or italic, or plain text.

Tip: Generally, it is advisable to avoid setting too much text as the subtitle. If the website publishes summaries that take an entire paragraph or even multiple paragraphs, it's better to use italic/bold text instead of the subtitle element to represent this content in IV.

6.1.5 Kicker

Kickers are separately formatted parts of the title supported in IV 2.0 with the kicker property. The kicker property must be set if a kicker is present and its text is actually a part of the title/story (see 'UBER SEX CLAIMS' on the screenshot above).

If the kicker represents a regular section or category into which the article falls, (e.g. 'CRIME: Seventy suitcases stolen from Heathrow airport'), it should be omitted. Missing section/category kickers are not considered an issue.

IMAGES AND MEDIA

6.2.1 Image quality

When several image resolutions are available and can be extracted reliably, the IV page should use better quality images (within reason). The optimal resolution range is 1280px-2560px, using larger images is pointless. Note that images that are too large (>5 MB) will fail to load. We recommend updating your template to IV 2.1 to automatically extract optimal images from the srcset attribute.

If for some reason it is only technically possible to obtain low-resolution versions of images (lower than 320px) for a page, but its original web version has high-resolution images, the page should not generate an IV.

Note: For the Icon type, we highly recommend setting the correct size using the width/height attributes so that they appear the same way in IV as they do in the text. Otherwise, you risk grabbing the 3x version of an emoji and displaying it as a full-blown image.

6.2.2 Cover images

It is obligatory to use a cover image:

If the image is present on the page and described in the source as “featured-img”, “cover”, “lead_img”, “main_image”, etc.
When the article has a cover on the source website (above the title or subtitle).

In other cases, cover images are optional:

We recommend setting a cover If there's a suitable image directly below the title/subtitle.
While it is possible to use GIFs and videos as cover, in most cases, it's better to leave these elements in the body of the article.

Sometimes, a cover is less desirable:

In single-image, single-video, or single-GIF articles with no significant text.
When text on the cover image repeats the title.
Images from meta-tags are not recommended: they might be suitable, but are usually designed with sharing widgets in mind and don’t work well in the IV environment.

A cover must not be set if:

The chosen image is clearly inappropriate for the cover.
The chosen image appears several paragraphs into the article and it is possible to reliably identify this.
The cover image is duplicated in the article.
Several images appear in the article one after another. In this case, the template should not break the sequence by extracting one of them as a cover (example).

Tip: Cover images can also have captions in IV, don't lose them.

6.2.3 Galleries and slideshows

Slideshows are required only if the source article shows several photos or other media as a slideshow or gallery. If this is the case, do the following:
- Present all images in the IV as a gallery, if possible.
- If that's not possible, keep a link to the full gallery.
- If none of the above are possible, generate no IV for the page.

If the source has several ordinary images/videos/GIFs following each other in the source, you may also convert them into a slideshow, but this is purely optional. This makes more sense in cases when images serve as additional content (e.g., a long text about a new car which is followed by ten images of the car).

We will not accept issue reports based on presence or absence of slideshows for ordinary images following each other in the source article.

EXCEPTION! Slideshows must not be used when:

The slideshow fetches unrelated images (e.g. an illustration and a disclaimer).
The article consists entirely of a slideshow (and its caption/description) and there's no other content.
The article uses images/videos/GIFs with captions as the main medium (e.g.: travel blogs that show many photos with captions, step-by-step crafting guides, cooking recipes, etc.).

In the cases above, use images with captions (or even plain paragraph text) following one another.

Tip: Remember that captions should be preserved for all images in the source. If you lose captions for images you've put into a slideshow, it's a valid issue. IV Slideshows support both a caption for the entire slideshows and different captions for each individual element.

6.2.4 Captions

Any captions present in the source article must be preserved. This includes captions for the cover image and captions for all individual elements of slideshows.

All Captions Preserved

If the image has no caption, but has meaningful text in the alt attribute, you may use that text as the caption. This is optional, we will not accept issue reports about alt-text missing from captions.

Tip: Please don't include meaningless alt-text as captions (e.g., the PlayStation blog always puts the name of the corresponding game in the alt attribute of all screenshots – there's no need to reproduce that on the IV page.)

6.2.5 Media credits

IV 2.0 supports a dedicated <cite> tag for credits in media captions. Credits in captions must be preserved and placed inside the appropriate tag, provided it is possible to reliably identify them.

6.2.6 Infographics

Tall infographic images are currently unreadable in Telegram apps. If there’s a reliable way to identify them (e.g., consistently used attributes or a specific section on the website that only contains infographics) the IV must add an image link to the full version of the image. If there is no reliable way to identify such images and they are not consistently featured on the website, it is acceptable to leave infographics as ordinary photos.

6.3.1 Image links

In IV 2.0, <img> tags support the attribute href to make the image clickable. It must be used to preserve the link behind the image if it leads to some different page or content.

Image links are required only if they are meaningful. If the link opens the same image in a higher resolution, it must be removed. Exception: Infographics.

6.3.2 Related Articles and other “More” links

IV 2.0 supports a dedicated type for RelatedArticles. Related articles are relatively static individual links or blocks of articles which are thematically related to the current one. They don't have to be located on the same domain.

It is obligatory to format “Related articles” links using the new <related> tag and/or remove other “More” links, provided all these links can be extracted from the article without endangering essential information.

We designed the RelatedArticles block to deliver a better IV-reading experience to users. The IV engine automatically checks whether articles in the <related> block have an IV, you don't need to worry about this.

If pages have no IV, they will not be displayed. If this results in an empty block, it will not be displayed.

There are cases when you must not use RelatedArticles:

1. Keep but don’t format as Related

Links that can’t be safely and reliably extracted from the article text.
Links that are part of essential content for the article (without which the article makes no sense).
Navigational links to the other parts of multipart articles.

Never put essential links into <related>, they will be lost if the page they are leading to doesn’t have an IV.

2. Remove

“More” blocks that show different links each time the page is reloaded.
(Consistently) random unrelated articles.
Dynamic lists of "Latest articles from this category”, “More articles by this author”, “Featured articles”, etc.
Lists of categories (links to dynamic lists).
External links leading to “Partner sites” (e.g., You won't believe what this game does to people!).

6.3.2.1. Formatting Related Articles

It is sufficient to put links into <related>. You only need the <a> – the IV engine will handle the rest (title, description, etc.). Your IV may only have one block of related articles at the end of the page. If the source has several blocks, merge them together or choose which one to keep.

Headers
Only one header may be present for the block of related articles at the end of the page. We will not accept reports about missing headers on Related blocks (unless the header contains critical information).

Note that if a header for a related article is not reliably extractable from the body, you must not use <related> for that link. (Otherwise, if the link gets no IV, the text will have a hanging header).

“Inline” blocks
You may leave “inline” related links in the middle the article. If you do, these <related> blocks must not have headers (unless the header contains critical information).

6.3.3 Channel links

You may display the official channel of the website that published the article on the IV page by using the channel property:

Official Channel Link

This channel link is optional. We will not accept issue reports based on the absence or presence of a channel link, with one exception:

If the channel property is set, the channel it is pointing to must be the official channel. To be considered official, the channel must be labelled as such somewhere on the source website (doesn't have to be on the same page as the original article).

6.3.4 Source links

Some articles include a link to their source. This link could be inserted at the end of the article in the format via <a href="https://example.org">Website Name</a>. A word with a similar meaning could be used instead of 'via' for websites in other languages.

6.3.5 Author links

Author links are optional. If there's a clearly identifiable author and they have a page on the target website, use that one. In more ambiguous cases, use what the regular viewing user can see in the original article or omit the link altogether.

Tip: IV only supports one author URL per article. If there are several in the article, it's permissible to choose one or omit them altogether.

6.3.6 Social media links

Sharing buttons and other interface-based links must be removed as per Rule 4.

Many articles include something like “check out our Facebook page” at the end of the text. Such links must be removed if they are placed in a reliably identifiable container.

6.3.7 Multi-page articles

To parse several pages into one IV, update your template to IV 2.1 (which skips canonical redirects by default) and use the inline function. Make sure to check in-app to see if your solution is working. The IV should open correctly when users share a link to any part of the article.

If pages can’t be safely assembled into one IV, navigation must be preserved. Please confirm that navigation is working and all further pages open correctly. If navigation can’t be preserved, the article must not generate an IV.

Never format links to the other parts of an article as related. This may break navigation if one part of the article fails to generate IV (since related articles without IVs are omitted in the block).

UNSUPPORTED CONTENT

Pages that display unsupported content (e.g. an interactive map widget) must not generate IVs.

Important: We will accept issue reports requesting to generate IVs for pages with content previously deemed unsupported if you include a link to a template that fully supports the content in question. This does not apply to supporting content from popular widgets that are likely to get official support in the future, see the list below.

6.4.1 Complex tables

IV 2.0 includes support for Tables. IVs can now be generated for articles with simple tables. However, complex tables may not render through existing means, and must be tagged as @unsupported.

6.4.2 Video/Audio from unsupported players

If the unsupported widget has an iFrame version, make it into an <iframe>. If you do that, the IV page will not be generated due to unsupported content, but things will work out of the box if and when we support that widget.
If it is not possible to represent the widget as an iFrame, but it is possible to get a direct link to the video/audio, use that link to generate a <video> or <audio> with the correct src attribute.
Otherwise, mark the object with the @unsupported function.

If an article that is otherwise supported includes a video or an audio track that would cause it to become unsupported, it is acceptable to include a link to the video instead of unsupporting the article. If there’s no other content on the page, it must not generate an IV.

6.4.3 Auxiliary widgets

Some pages include unsupported widgets that are not essential for the understanding of the article. A local news site may show a weather forecast widget on their pages. A business newspaper may show a stock price ticker for the companies covered in the article. Some websites include “And what would you do?” polls at the end of some of their articles to increase user engagement.

Such non-essential widgets may be omitted in IV. Warning: Make sure that this dynamic auxiliary data doesn't get added to the static IV page.

6.4.4 Popular Widgets

Telegram is likely to support the following popular widgets in the future:

Reddit
Spotify
Getty images
Imgur
Coub
Soundbank
JW Player
Twitter Timeline
Infogram
VK Post
WordPress Embed Post
Yandex.music

Supporting content from these widgets is optional since it will eventually become available through official means.

OTHER

6.5.1 Subdomains

Subdomains that present content in a similar way to the higher-level domain must be supported.

If a subdomain looks like a separate website, supporting it is optional. We will accept issue reports if a template generates broken IV pages for any subdomain.

Note: We will add the necessary redirects so that Telegram apps will show IVs for articles on the main domain when users share links to the mobile version. It is not necessary to support pages from the mobile version.

6.5.2 Service areas

Non-article pages are strictly optional, unless there’s interactive content – in which case they must not generate IVs. This includes Terms of Service, Privacy Policies, About sections, Contacts sections and special “Print” versions of articles.

6.5.3 Single-media pages

Support for pages that only contain a single media item (photo, GIF, video, etc.) is required if:

The pages are routinely accessible to users through the main navigation of the website and include other data like title, date, etc.
Such pages are the main medium for the domain in question (e.g. Pikabu.ru)

If the single-media page contains unsupported media, it must not generate an IV. See 6.4.2 Unsupported Video and Audio content.

In all other cases, supporting single-media pages is optional.

6.5.4 Ancient lore

Support for news articles from 2015 and earlier is optional. We won’t accept issue reports on news articles posted before 2016 if the template correctly handles articles published recently.

6.5.5 Quotes

Quotes must be formatted to match their appearance in the source article, provided it is possible to identify them (and their type) in a reliable way. Line breaks in quotes must be preserved.

Quotes support <cite> tags. If a quote includes an author, it must be formatted accordingly (provided the author can be reliably identified in the source).

7. Checklist Changelog

We will be updating this document with further clarifications as new issues arise.

Mar 20 2019

Don’t miss the IV 2.1 update.

Checklist 2.2:

Expanded clarifications

3.2, Link Preview: site_name must include the name that users see on the main page of the website; cover photo must be used in preview if metadata is empty or contains site logo; template must generate proper description if metadata is unsuitable
3.3, Supported Elements: Credits must be supported in media captions and quotes
6.1.2, Date and Time: Time is optional if the date is set correctly; time zones are optional, unless reliably identifiable in the source
6.2.1, Image Quality: for issues to be accepted, the difference in image quality must be significant; higher resolution images must be reliably extractable; note
6.3.1, Image links: Must be preserved if they are meaningful
6.3.2, Related articles: Details on when RelatedArticles must not be used; Formatting guidelines
6.4, Unsupported content: Optional to extract content from popular widgets which are scheduled for official Telegram support, even if another template does this
6.4.2, Unsupported Video/Audio: Possible to include a link to an audio/video instead of unsupporting an otherwise fine article
6.5.1, Subdomains: Added a note on mobile versions

Added NEW clarifications

6.2.6, Infographics
6.3.7, Multi-page articles
6.4.3, Popular Widgets
6.5.2, Service Areas
6.5.3, Single-media pages
6.5.4, Ancient lore
6.5.5, Quotes

Feb 6 2019

Checklist 2.1

Related Articles (6.3.2). Considerably expanded guidelines. Now obligatory to put related links into the new “Related articles” block, provided they are reliably identifiable in the source. Other links should be removed, see full details.
Cover Images (6.2.2). Added conditions when covers are obligatory.
Galleries and Slideshows (6.2.3). Added detailed explanations on gallery usage.

Feb 2 2019

Checklist 2.0: Changes for the Second Instant View Contest

The Clarifications section has been rewritten to better organize the lore we've accumulated during and after the previous contest. These clarifications have been updated:

Tables are supported (if they are not too complex).
Nested lists (and lists inside tables) are supported.
RTL-support has been introduced and is obligatory for RTL pages.
Related Articles got a dedicated element (UPDATED 6.02, see guidelines!).
Image links are supported.
Added guidelines on image quality.
Updated guidelines for cover images
The new Icon type requires careful handling.
Media credits can be formatted properly (if separable from caption).
Kickers in titles got a dedicated element for certain cases.
Added guidelines for supporting subdomains.
Updated guidelines for social media links
Updated the guidelines for site_name in link previews.

Don't forget to check out what's new in IV 2.0 to know what your templates are now able to support.