Advanced Usage

Advanced usage

Bridgetown SEO Tag is designed to implement SEO best practices by default and to be the right fit for most sites right out of the box. If for some reason, you need more control over the output, read on:

Author information

Author information is used to propagate the creator field of Twitter summary cards. This should be an author-specific, not site-wide Twitter handle (the site-wide username be stored as site.twitter.username).

TL;DR: In most cases, put author: [your Twitter handle] in the document's front matter, for sites with multiple authors. If you need something more complicated, read on.

There are several ways to convey this author-specific information. Author information is found in the following order of priority:

1. An author object, in the documents's front matter, e.g.:

author:
  twitter: benbalter

2. An author object, in the site's _data/_site_metadata.yml, e.g.:

author:
  twitter: benbalter

3. site.data.authors[author], if an author is specified in the document's front matter, and a corresponding key exists in site.data.authors. E.g., you have the following in the document's front matter:

author: benbalter

And you have the following in _data/authors.yml:

benbalter:
  picture: /img/benbalter.png
  twitter: benbalter

potus:
  picture: /img/potus.png
  twitter: whitehouse

In the above example, the author benbalter's Twitter handle will be resolved to @benbalter. This allows you to centralize author information in a single _data/authors file for site with many authors that require more than just the author's username.

Pro-tip: If authors is present in the document's front matter as an array (and author is not), the plugin will use the first author listed, as Twitter supports only one author.

4. An author in the document's front matter (the simplest way), e.g.:

author: benbalter

5. An author in the site's _config.yml, e.g.:

author: benbalter

Customizing image output

For most users, setting image: [path-to-image] on a per-page basis should be enough. If you need more control over how images are represented, the image property can also be an object, with the following options:

• path - The relative path to the image. Same as image: [path-to-image]
• height - The height of the Open Graph (og:image) image
• width - The width of the Open Graph (og:image) image

You can use any of the above, optional properties, like so:

image:
  path: /img/twitter.png
  height: 100
  width: 100

SmartyPants Titles

Titles will be processed using Bridgetown's smartify filter. This will use SmartyPants to translate plain ASCII punctuation into "smart" typographic punctuation. This will not render or strip any Markdown you may be using in a page title.

Setting customized Canonical URL

You can set custom Canonical URL for a page by specifying canonical_url option in page front-matter. E.g., you have the following in the page's front matter:

layout: post
title: Title of Your Post
canonical_url: 'https://github.com/bridgetownrb/bridgetown-seo-tag/'

Which will generate canonical_url with specified link in canonical_url.

<link rel="canonical" href="https://github.com/bridgetownrb/bridgetown-seo-tag/" />

If no canonical_url option was specified, then uses page url for generating canonical_url. E.g., you have not specified canonical_url in front-matter:

layout: post
title: Title of Your Post

Which will generate following canonical_url:

<link rel="canonical" href="https://example.com/title-of-your-post" />

Customizing title modifier for paginated pages

You can override the default title modifier for paginated pages from Page %{current} of %{total} for to a string of your choice by setting a seo_paginator_message key in your _config.yml.

For example:

seo_paginator_message: "%<current>s / %<total>s | "

While the value can be any string text, we recommend using a Ruby string-template containing the variables current and total similar to the example above, to incorporate the current page-number and total number of paginated pages in the title.