Guidelines updated! See the checklist for details. 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

  • Thumbnail for link preview must be shown if a suitable image or document exists in the source.
  • 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.).
  • The site_name property must include the correct name of the website. If the webmaster includes unnecessary data (e.g. ‘Site {sitename}’) or mixes the site name with the article title, your template must take care of this.

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 shown horizontally centered on IV page.
  • Media captions must be shown on IV page, aligned under their corresponding media if captions exist in the source.
  • Pullquotes must be horizontally centered on IV page if pull quotes exist in the source.
  • 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, in the meta tags 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’, 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 and time of publication is obligatory for news publications. It must be obtained by any means possible, including meta tags, etc.

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.

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, 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.

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.

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.

LINKS

6.3.1 Image links

In IV 2.0, <img> tags support the optional attribute href to make the image clickable. This should only be used if the link behind the image leads to some different page or content. E.g., if the link opens the same image in a higher resolution, it should be ignored.

6.3.2 Related articles

IV 2.0 supports a dedicated type for RelatedArticles.

It is obligatory to format “Related articles” links using the new <related> tag, provided they are identifiable in the source. Related Articles:

  • Are thematically related to the current article.
  • May also be located on a different website.
  • Lists of related articles are (relatively) static (a news item may eventually get an extra link to the newest piece on the topic, but this just adds another item to an otherwise static list).

Other types of “More” links that are not suitable for the “Related articles” block should be removed, provided this is technically possible without endangering essential content. Examples:

  • (Consistently) random unrelated articles.
  • Dynamic lists of “Latest articles from this category”.
  • Lists of categories (links to dynamic lists).
  • Etc.

We will accept issues if:

  • Related articles both exist in the source and are identifiable but were not formatted as IV 2.0 "Related articles”.
  • Other “More" links are identifiable and not either removed or formatted as “Related articles”.
  • External links leading to ‘Partner sites’, etc. were not removed along with other ads (e.g., You won't believe what this game does to people!).

We will not accept issues on whether or not links formatted as “Related articles” are thematically related enough or static enough.

Note 1: For links to be considered identifiable, the author of an issue must demonstrate a template that reliably identifies them for extraction/removal without endangering essential information.

Note 2: 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.

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.

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.

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.

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.

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 IV pages with issues for any subdomain.


7. Checklist Changelog

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

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.