A Metalsmith plugin for adding Facebook OpenGraph meta tags
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
lib
test
.gitignore
.travis.yml
LICENSE.md
README.md
package.json

README.md

metalsmith-open-graph

Build Status Dependencies

This is a Metalsmith plugin for adding Facebook OpenGraph tags to a page.

open_graph = require('metalsmith-open-graph');

// ...

metalsmith.use(open_graph({
  ...options...
}))

The following options are accepted:

  • sitename: the human-readable name for your site.
  • sitetype: the OG type of your site, from this list.
  • siteurl: the base URL for your site, for resolving relative image URLs.
  • pattern: a minimatch pattern. Only source files matching this pattern will be modified.
  • title: where to find the og:title tag. See below.
  • description: where to find the og:description tag. See below.
  • image: where to find the og:image tag. See below.

Any other options are passed to Cheerio, which does the actual HTML parsing behind the scenes.

The og:url tag is not currently supported, because it's very hard for the plugin to detect the final version of the page's URL when other plugins could be in play (e.g. permalink). If you know in advance what the URL is going to be, we can try specifying it in metadata somehow.

Type

Some Open Graph types may require extra metadata. At present, it is not possible to specify this.

Title, Description, Image

The plugin will use the title, description, and image options to look in your HTML and metadata for the content it needs.

  • If the option value is ".X" or "#X", it uses that as a CSS selector by class or ID.
  • Otherwise, it's used as a key in the Metalsmith metadata.

For example:

metalsmith.use(open_graph({
  siteurl: 'http://mysite.io',
  title: '#og-title',
  description: 'ogDescription',
  image: '.og-image'
}))

And your input file is this:

---
ogDescription: 'My awesome page description'
---

<html>
  <body>
    <h1 id="og-title">My Page</h1>
    <img class="og-image" url="/images/awesome.jpg" />
  </body>
</html>

It will write the following HEAD tags:

Common Problems and Workarounds

Cyrillic or other symbols are being encoded

You can pass an option called decodeEntities with a value of false to disable this. Reported and solved by Vitaliy Bobrov