500 new domains have entered the contest. Read More

Perfect Template Checklist

Below is a list of detailed criteria that will be used to determine the winners of the contest. Anyone can report issues with templates based on these criteria. Telegram arbiters will check all reported issues and reject templates that do not stand up to this definition of perfect.

If you're looking for a more general definition, see our Criteria for a Good Template.

1. IV Targets: Must Generate

The template must generate Instant View pages for the relevant pages on the target website to be considered perfect.

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 your 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

The template must not generate Instant View pages for any of the pages of the following types on the target website to be considered perfect.

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 on our servers. The more time passed since an article was published, the less frequently the cached IV page will be updated. 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 contacts pages
  • Store areas of websites, such as pages where users can buy products

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 unsupported in the IV format

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

Tip: The rule here is simple. If a 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 it is a good idea to confirm this before submitting your template for the contest. Mark 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 to logged in users, 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 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 meta data 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 meta data (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 correct 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 meta data 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 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 that feature 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 for the contest. 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.

  • Main navigation bars and menus removed (essential navigation may be adjusted to simple links)
  • Top bars removed
  • Side bars removed or adjusted and appended to bottom of IV page
  • Footers removed
  • Unsupported widgets removed (check supported embeds)
  • Advertisements removed
  • Banners removed
  • Social media links and buttons removed, including “Share” and “Like” links and buttons
  • Buttons removed (if the button 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 of the template's author
  • No introduced ads or links of any kind
  • Etc.

Tip: It is allowed to 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 named 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. This section will be expanded, follow @IVContest to keep in touch.

GENERAL PROPERTIES

6.1.1 Author name

Author name is required only if it is consistently presented in the source article in a clear way (at the top of the page, at the very end of the text etc.), especially if there's a name of an actual person.

In less obvious cases, what the user sees when viewing the original article in an ordinary 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.

It is possible to omit the author in cases where no name can be seen by a regular user opening the original article in the browser. It is possible to omit the name when there‘s no identifiable person, only the website’s ‘team’, ‘editors’, ‘website name’ etc.

We will not accept issues based on absence of author names for articles in which no author can be easily identified by a regular viewing user.

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 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 the 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: Between ‘date published’ and ‘date last edited’, choose ‘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. Somewhat more common are short summary sentences that are also shown below the title (and are called standfirst by the British). 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 a 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 critical.

We will not accept issues on templates for presenting the lead paragraph as the subtitle in IV. If the lead paragraph uses a different style, it is recommended to use bold or italic text (we will not accept issues based on the absence of such formatting).

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. We will not accept issues based on missing section/category kickers.

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.

We will not accept issues if the difference in image quality is insignificant when viewed in-app.

If for some reason it is only technically possible to obtain low-resolution versions of images (lower than 320px) for a page, on which high-resolution images are available on the web, the page should not generate an IV.

Note: For the new 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.

See also: Infographics

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.

The cover must not be set if:

  • The chosen image is clearly inappropriate for the cover.
  • The chosen image appears several paragraphs deep into the article and it is technically 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, so 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 is possible, generate no IV for the page.

If there are 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 issues based on presence or absence of slideshows for ordinary images following each other in the source article.

EXCEPTION! Slideshows must not be used:

  • Unrelated images end up collected in the slideshow (e.g. an illustration and a disclaimer).
  • When the article consists entirely of a slideshow (and its caption/description) and there's no other content.
  • When 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 issues 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 technically 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.

LINKS

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 the 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).

We will accept issues on incorrectly formatted RelatedArticles.

6.3.3 Channel links

It is allowed to 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 issues 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 named 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.

We will not be accepting issues based on the availability of the source link.

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.

We will not be accepting issues based on author links. The only exception is when the author link is pointing to an inappropriate page.

Tip: IV only supports one author URL per article. If there are several in the article, it's ok to choose one or omit them altogether. Neither will be accepted as an issue.

6.3.6 Social media links

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

Many articles include something like “check out our facebook page” at the end of every text. Such links must be removed if they are consistently placed in an 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 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, you must preserve navigation. 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).

UNSUPPORTED CONTENT

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

Important: We will accept issues 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.

Important: We will accept issues 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.

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 this link to generate a <video> or <audio> with the correct src attribute.
  • Otherwise, mark the object with the @unsupported function.

If an otherwise supported article 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?” votes at the end of some of their articles to increase user engagement.

None of these should bother you. Simply remove such non-essential widgets from the article and go ahead with generating the IV page. Warning: Make sure that you don’t add this dynamic auxiliary data to your 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 not accept issues if it is not supported.

We will accept issues 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 of 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 on 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 issues 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).


7. Checklist Changelog

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

Mar 20

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 meta data is empty or contains site logo; template must generate proper description if meta data 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 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


Feb 6

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 technically 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

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.