Skip to main content

Use the {{recommendations}} helper anywhere in a theme to output a list of recommended sites as configured in Ghost Admin.

Default template

Ghost uses the following default template to render recommendations.
The template loops over recommendations and outputs an HTML list item for each recommendation. Use the CSS class names to style the content. Alternatively, override the default template altogether with a custom one by adding a file called recommendations.hbs to the theme’s partials folder. When building a custom template, the recommendation object contains the following data:
  • id: Recommendation ID used to track the number of clicks.
  • url: The recommended site’s URL. Use the readable_url helper to make a more human-readable URL.
  • favicon: The recommended site’s favicon, output as an image URL
  • featured_image: The recommended site’s feature image, output as an image URL
  • title: The recommended site’s title
  • description: The recommended site’s description
  • created_at: The date the recommendation was created
  • updated_at: The date the recommendation was updated

Attributes

Combine the {{recommendations}} helper with the attributes listed below to customize its behavior.

Limit

Specify the maximum number of recommendations to display. The default is 5.

Order

Order recommendations based on any valid resource field (like title) in ascending (asc) or descending (desc) order. The default order is created_at desc (or newest recommendations on top).

Page

When the total number of recommendations exceeds the number defined in limit, recommendations become paginated. Use the page attribute to access subsequent pages of recommendations.

Filter

Use logic-based queries to filter recommendations. For a guide to filtering syntax, see our Content API docs.

Advanced options

Only show recommendations when enabled

Use @site.recommendations_enabled to only show recommendations when they’ve been enabled in Ghost Admin. This is useful when adding additional markup that should only be shown when recommendations are enabled:

Open the recommendations modal

When Portal is enabled on a Ghost site, recommendations are displayed at site.com/#/portal/recommendations. Let users open the recommendations modal by adding the data-portal="recommendations" attribute to a button.