REPOSITORY OVERVIEW

Live repository statistics

★ 2.8KStars

⑂ 280Forks

◯ 14Open issues

◉ 2.8KWatchers

README preview

MetaTags: Rails helpers for SEO metadata, sharing, canonical URLs, and robots

MetaTags helps Ruby on Rails applications render HTML head metadata such as titles, descriptions, canonical links, robots directives, Open Graph tags, X card tags, and hreflang links.

It supports the metadata layer of search engine optimization (SEO), especially for titles, descriptions, canonicalization, robots directives, and social sharing previews.

Ruby on Rails

The MetaTags main branch fully supports Ruby on Rails 6.1+ and is tested against all major Ruby on Rails releases.

[!NOTE] We no longer support Ruby versions older than 3.0 and Ruby on Rails older than 6.1 since they reached their end of life (see Ruby and Ruby on Rails).

[!IMPORTANT] MetaTags manages HTML head metadata. It does not generate structured data / JSON-LD, robots.txt, sitemaps, internal links, or page content.

Installation

Add the "meta-tags" gem to your Gemfile.

gem "meta-tags"

And run bundle install command.

Configuration

MetaTags ships with practical defaults for truncation and rendering. You can change them to match your application. Legacy fields such as keywords are still supported for compatibility, but they are not modern search requirements.

To override the defaults, create an initializer config/initializers/meta_tags.rb using the following command:

rails generate meta_tags:install

When a truncation limit is reached, arrays passed to title or keywords can either partially truncate the last item or stop at item boundaries. Set config.truncate_array_items_at_boundaries = true to preserve whole items for multi-item arrays. Single-item arrays are still truncated normally.

By default, meta tags are rendered with the key name. However, some meta tags are required to use property instead (like Facebook Open Graph object). The MetaTags gem allows you to configure which tags to render with the property attribute. The pre-configured list includes all possible Facebook Open Graph object types by default, but you can add your own in case you need it.

MetaTags Usage

First, add this code to your main layout:

<head>
  <%= display_meta_tags site: "My website" %>
</head>

Then, to set the page title, add this to each of your views (see below for other options):

<h1><%= title "My page title" %></h1>

When views are rendered, the page title will be included in the right spots:

<head>
  <title>My website | My page title</title>
</head>
<body>
  <h1>My page title</h1>
</body>

You can find allowed options for the display_meta_tags method below.

[!IMPORTANT] You must use display_meta_tags in the layout files to render the meta tags. In the views, you will instead use set_meta_tags, which accepts the same arguments but does not render anything in the place where it is called.

Using MetaTags in controller

You can define the following instance variables:

@page_title = "Member Login"
@page_description = "Member login page."

Also, you could use the set_meta_tags method to define all meta tags simultaneously:

set_meta_tags(
  title: "Member Login",
  description: "Member login page."
)

You can find the allowed options for the set_meta_tags method below.

Using MetaTags in view

To set meta tags, you can use the following methods:

<% title "Member Login" %>
<% description "Member login page." %>
<% nofollow %>
<% noindex %>
<% refresh 3 %>

Also, the set_meta_tags method exists:

<%
  set_meta_tags(
    title: "Member Login",
    description: "Member login page."
  )
%>

You can pass an object that implements the #to_meta_tags method and returns a Hash:

class Document < ApplicationRecord
  def to_meta_tags
    {
      title: title,
      description: summary
    }
  end
end

@document = Document.first
set_meta_tags @document

The title method returns the title itself, so you can use it to show the title somewhere on the page:

<h1><%= title "Member Login" %></h1>

If you want to set the title and display another text, use this:

<h1><%= title "Member Login", "Here you can login to the site:" %></h1>

Allowed options for `display_meta_tags` and `set_meta_tags` methods

Use these options to customize the generated tags:

Option	Description
`:site`	Site title
`:title`	Page title
`:description`	Page description
`:keywords`	Legacy keywords meta tag for compatibility; ignored by Google Search and Bing web search
`:charset`	Page character set
`:prefix`	Text between site name and separator
`:separator`	Text used to separate the website name from the page title
`:suffix`	Text between separator and page title
`:lowercase`	When true, the page name will be lowercase
`:reverse`	When true, the page and site names will be reversed
`:noindex`	Add noindex meta tag; when true, "robots" will be used; accepts a string with a robot name or an array of strings
`:index`	Add index meta tag; when true, "robots" will be used; accepts a string with a robot name or an array of strings
`:nofollow`	Add nofollow meta tag; when true, "robots" will be used; accepts a string with a robot name or an array of strings
`:follow`	Add follow meta tag; when true, "robots" will be used; accepts a string with a robot name or an array of strings
`:noarchive`	Add noarchive meta tag; when true, "robots" will be used; accepts a string with a robot name or an array of strings
`:robots`	Add custom directives to the `robots` meta tag (Hash)
`:googlebot`	Add custom directives to the `googlebot` meta tag (Hash)
`:bingbot`	Add custom directives to the `bingbot` meta tag (Hash)
`:canonical`	Add canonical link tag
`:prev`	Add legacy prev pagination link tag
`:next`	Add legacy next pagination link tag

And here are a few examples to give you ideas.

<%= display_meta_tags separator: "&mdash;".html_safe %>
<%= display_meta_tags prefix: false, separator: ":" %>
<%= display_meta_tags lowercase: true %>
<%= display_meta_tags reverse: true, prefix: false %>
<%= display_meta_tags og: { title: "The Rock", type: "video.movie" } %>
<%= display_meta_tags alternate: { "zh-Hant" => "http://example.com.tw/base/url" } %>

Allowed values

You can specify :title as a string or array:

set_meta_tags title: ["part1", "part2"], site: "site"
# site | part1 | part2
set_meta_tags title: ["part1", "part2"], reverse: true, site: "site"
# part2 | part1 | site

If you still need the legacy keywords tag, values can be passed as a string of comma-separated values or as an array:

set_meta_tags keywords: ["tag1", "tag2"]
# tag1, tag2

The description is a string (HTML will be stripped from the output string).

Mirrored values

Sometimes, it is desirable to mirror meta tag values down into namespaces. A common use case is when you want the open graph's og:title to be identical to the title.

Let's say you have the following code in your application layout:

display_meta_tags og: {
  title: :title,
  site_name: :site
}

The value of og[:title] is a symbol, which refers to the value of the top-level title meta tag. In any view with the following code:

title "my great view"

You will get this open graph meta tag automatically:

<meta property="og:title" content="my great view"></meta>

[!NOTE] The title does not include the site name. If you need to reference the exact value rendered in the <title> meta tag, use :full_title.

Using with Turbo

Turbo is a simple solution for getting the performance benefits of a single-page application without the added complexity of a client-side JavaScript framework. MetaTags supports Turbo out of the box, so no configuration is necessary.

In order to update the page title, you can use the following trick. First, set the ID for the <title> HTML tag using MetaTags configuration in your initializer config/initializers/meta_tags.rb:

MetaTags.configure do |config|
  config.title_tag_attributes = {id: "page-title"}
end

Now in your turbo frame, you can update the title using a turbo stream:

<turbo-frame ...>
  <turbo-stream action="update" target="page-title">
    <template>My new title</template>
  </turbo-stream>
</turbo-frame>

Using with pjax

jQuery.pjax is a nice solution for navigation without a full-page reload. The main difference is that the layout file will not be rendered, so the page title will not change. To fix this, when using a page fragment, pjax will check the fragment DOM element for a title or data-title attribute and use any value it finds.

MetaTags simplifies this with the display_title method, which returns the fully resolved page title (including site, prefix/suffix, etc.). But in this case, you will h