metalsmith-gravatar

metalsmith-gravatar

A Metalsmith plugin for Gravatar.

This plugin converts email addresses into their associated Gravatar URLs and adds them to Metalsmith's metadata object.

Installation

npm install --save metalsmith-gravatar

Getting Started

If you haven't checked out Metalsmith before, head over to their website and check out the documentation.

CLI Usage

If you are using the command-line version of Metalsmith, you can install via npm, and then add the metalsmith-gravatar key to your metalsmith.json file:

{
  "plugins": {
    "metalsmith-gravatar": {
      "stevenschobert": "[e-mail]"
    }
  }
}

JavaScript API

If you are using the JavaScript API for Metalsmith, then you can require the module and add it to your .use() directives:

var gravatar = require('metalsmith-gravatar');

metalsmith.use(gravatar({
  stevenschobert: "[e-mail]"
}));

Output

This plugin will a new metadata property named gravatar. This object will contain all the Gravatar URLs you can use in your templates:

<img src="{{gravatar.stevenschobert}}" />

Grouping Avatars

Both the CLI and the JavaScript APIs support nested objects. This allows you to group together multiple avatars into named groups!

{
  "plugins": {
    "metalsmith-gravatar": {
      "authors": {
        "stevenschobert": "[e-mail]",
        "malcolmreynolds": "[e-mail]"
      },
      "maintainers": {
        "core": { ... },
        "occasional": { ... }
      }
    }
  }
}

Nested objects map directly into the output'ed gravatar object, so you can access them by the same names:

<img src="{{gravatar.authors.stevenschobert}}" />

Options

If you want more control over how the Gravatar URLs are generated, you can specify an options object. If the plugin sees this options object, it will expect the avatars you wish to convert to be in a new avatars object:

{
  "plugins": {
    "metalsmith-gravatar": {
      "options": {
        "protocol": "https"
      },
      "avatars": {
        "stevenschobert": "[e-mail]",
        "authors": { ... }
      }
    }
  }
}

Below is a list of options that are supported:

protocol

String - 'http' (default)) or 'https'

Sets the URL prefix for Gravatar images. Useful if you are serving a page via SSL and want to also load the external images via SSL.

Credits

Thanks to Segment.io for creating and open-sourcing Metalsmith!