Widgets: Recommendations

The <devsite-recommendations> custom element can be used to provide content recommendations to your readers. You can let the system generate recommendations, you can provide explicit recommendations yourself, or you can wrap existing recommendation sections of your doc for consistent presentation, click-through statistics and a rich user-interface (including descriptions and images).

Usage

To use this widget, create a <devsite-recommendations> element. If you wish to provide recommendations explicitly, then add some links within the element. At present, system generated recommendations will be supplied when the element is empty, but future work will allow authors to experiment with generated recommendations when explicit recommendations are supplied, as well as using them as inputs to the algorithm.

If you are supplying explicit recommendations, then provide some markup within the element. Any <a> tags detected when the element is connected will have their href attributes extracted and used for the recommendations.

If you are supplying more than three recommendations, a random selection will be chosen. However, the ordering of the recommendations will remain the same as the input ordering, so higher priority recommendations will always show on the leftmost.

If you don't want specific recommendations to appear in the generated results, you can make an empty <devsite-recommendations> element with a collection of <link rel="disallow" href="/path">. Any <link> tags with rel=disallow and an href attribute will automatically be detected and removed from generated recommendations.

If you only want recommendations from a specific subset of pages, you can use Nomenclature tags in a query field to filter the results. The syntax is k:category:value. For example, k:language:typescript. The list of tags can be a comma separated list (k:language:typescript,k:language:swift) to include pages which contain any of the tags.

The following sections describe the markup, how it renders under normal conditions and how it renders to machines or simple user-agents.

Markup

<devsite-recommendations>
<p>Note: link text is displayed when JavaScript is off</p>
<ul>
  <li><a href="/maps/documentation">Maps docs</a></li>
  <li><a href="/analytics">Analytics</a></li>
  <li><a href="/machine-learning/crash-course">MLCC</a></li>
</ul>
</devsite-recommendations>

Result

Simple user-agents

Note: link text is displayed when JavaScript is off

Example with disallows

Markup

<devsite-recommendations>
  <link rel="disallow" href="/maps/documentation">
  <link rel="disallow" href="/analytics">
  <link rel="disallow" href="/machine-learning/crash-course">
</devsite-recommendations>

Result

Since the results are dependent on the recommendations, which can change, the output will appear the same as the output from the recommendations model.

Wrapping existing content

The element can progressively enhance existing markup on your pages, so you can upgrade existing links by wrapping them with <devsite-recommendations>.

The new links will adopt all of the functionality and policies of the recommendation platform, such as data collection and experiment dashboards, but the contents will also be replace with rich metadata including descriptions and images, and may exclude some links (e.g. access-controlled or pages without metadata).

Markup

<devsite-recommendations>
<h2>Example communities</h2>
<p>Note: All markup here will be replaced with the recommendation UI.</p>
<p>
  For more information on Google Developers, check out our <a href="/community/experts">GDEs</a>. If
  you are looking to form a community, take a look at <a href="/community/gdg">GDGs</a>. Lastly, if
  you're currently studying, don't miss our <a href="/community/dsc">DSCs</a>.
</p>
</devsite-recommendations>

Result

Example communities

Note: All markup here will be replaced with the recommendation UI.

For more information on Google Developers, check out our GDEs. If you are looking to form a community, take a look at GDGs. Lastly, if you're currently studying, don't miss our DSCs.

Usage in Markdown files

In a Markdown (.md) file, make sure the custom element is wrapped with a standard HTML element, such as a <section> or <div>:

Mixed content

## Markdown section

* Markdown list
* [Markdown link](/foo)

## HTML section

<div>
<devsite-recommendations>
  <p>Note: link text is displayed when JavaScript is off</p>
  <h2>Sample heading</h2>
  <a href="/recommended">Recommended</a>
</devsite-recommendations>
</div>

Markdown section

HTML section

Note: link text is displayed when JavaScript is off

Sample heading

Recommended

Pure markdown

<pre><devsite-recommendations>
## Sample heading

* Note: link text is displayed when JavaScript is off
* [Maps documentation](/maps/documentation)

</devsite-recommendations><pre>

Result

Sample heading

System attributes

At present the only supported attributes are for controlling system behavior and should not be needed by normal users.

yield (optional) If supplied, the element will yield to any other non-yielding recommendation elements on the page. This is typically used by the site itself to automatically place recommendations on a page, but to only show them when no other instances are present.

Filtering with Nomenclature

Markup

<devsite-recommendations query="k:language:typescript">
</devsite-recommendations>

Result