❤Never Propel Marmalade

npm

Sign UpSign In
Wondering what’s next for npm?Check out our public roadmap! »

rehype-meta

2.0.0 • Public • Published

rehype-meta

Build Coverage Downloads Size Sponsors Backers Chat

rehype plugin to add metadata (Open Graph, Twitter) to your head.

Table of contents

Install

npm:

npm install rehype-meta

Use

Say example.js looks as follows:

var report = require('vfile-reporter')
var rehype = require('rehype')
var meta = require('rehype-meta')
 
rehype()
  .data('settings', {fragment: true})
  .use(meta, {
    twitter: true,
    og: true,
    copyright: true,
    type: 'article',
    origin: 'https://www.nytimes.com',
    pathname: '/interactive/2019/12/02/nyregion/nyc-subway-map.html',
    name: 'The New York Times',
    siteTags: [
      'US Politics',
      'Impeachment',
      'NATO',
      'London',
      'Food',
      'Poverty',
      'Climate Change',
      'Global Warming'
    ],
    siteAuthor: 'The New York Times',
    siteTwitter: '@nytimes',
    author: 'Jane Doe',
    authorTwitter: '@jane',
    authorFacebook: 'janedoe',
    title: 'The New York City Subway Map as You’ve Never Seen It Before',
    separator: ' | ',
    description:
      'The city has changed drastically over the past 40 years, yet the M.T.A. map designed in 1979 has largely endured.',
    section: 'New York',
    tags: [
      'Subway',
      'Map',
      'Public Transit',
      'Design',
      'MTA',
      'Massimo Vignelli',
      'NYC'
    ],
    image: {
      url:
        'https://static01.nyt.com/images/2019/12/02/autossell/mta-promo-image/mta-crop-facebookJumbo.jpg',
      alt: 'M.T.A. map designed in 1979',
      width: '1050',
      height: '550'
    },
    published: '2019-12-02T10:00:00.000Z',
    modified: '2019-12-03T19:13:00.000Z'
  })
  .process('', function(err, file) {
    console.error(report(err || file))
    console.log(String(file))
  })

Now, running node example yields:

no issues found
<head>
<title>The New York City Subway Map as You’ve Never Seen It Before | The New York Times</title>
<link rel="canonical" href="https://www.nytimes.com/interactive/2019/12/02/nyregion/nyc-subway-map.html">
<meta name="description" content="The city has changed drastically over the past 40 years, yet the M.T.A. map designed in 1979 has largely endured.">
<meta name="keywords" content="Subway, Map, Public Transit, Design, MTA, Massimo Vignelli, NYC, US Politics, Impeachment, NATO, London, Food, Poverty, Climate Change, Global Warming">
<meta name="author" content="Jane Doe">
<meta name="copyright" content="© 2019 Jane Doe">
<meta property="og:type" content="article">
<meta property="og:site_name" content="The New York Times">
<meta property="og:url" content="https://www.nytimes.com/interactive/2019/12/02/nyregion/nyc-subway-map.html">
<meta property="og:title" content="The New York City Subway Map as You’ve Never Seen It Before">
<meta property="og:description" content="The city has changed drastically over the past 40 years, yet the M.T.A. map designed in 1979 has largely endured.">
<meta property="og:image" content="https://static01.nyt.com/images/2019/12/02/autossell/mta-promo-image/mta-crop-facebookJumbo.jpg">
<meta property="og:image:alt" content="M.T.A. map designed in 1979">
<meta property="og:image:width" content="1050">
<meta property="og:image:height" content="550">
<meta property="article:published_time" content="2019-12-02T10:00:00.000Z">
<meta property="article:modified_time" content="2019-12-03T19:13:00.000Z">
<meta property="article:author" content="https://www.facebook.com/janedoe">
<meta property="article:section" content="New York">
<meta property="article:tag" content="Subway">
<meta property="article:tag" content="Map">
<meta property="article:tag" content="Public Transit">
<meta property="article:tag" content="Design">
<meta property="article:tag" content="MTA">
<meta property="article:tag" content="Massimo Vignelli">
<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:image" content="https://static01.nyt.com/images/2019/12/02/autossell/mta-promo-image/mta-crop-facebookJumbo.jpg">
<meta name="twitter:image:alt" content="M.T.A. map designed in 1979">
<meta name="twitter:site" content="@nytimes">
<meta name="twitter:creator" content="@jane">
</head>

API

rehype().use(meta[, options])

Add metadata to the head of a document. Adds a <head> if one doesn’t already exist. Overwrites metadata if found: for example, when a <title> already exists, updates it.

options

Configuration with least priority. Mixed into config.

Config

There are three ways to configure the metadata of a document.

  1. Pass an object as options when using meta
  2. Define it in YAML front matter (by integrating with vfile-matter)
  3. Define an object at file.data.meta

Configuration is created by extending the defaults, with these objects, in the above order (so file.data.meta takes precedence over options). Only options is enough if every file should have the same metadata. If your workflow enables front matter, vfile-matter is a good way to keep data in files. Alternatively, do it yourself by adding data at file.data.meta.

config.og

Whether to add Open Graph metadata (boolean, default: false).

Affects: meta[property=og:site_name], meta[property=og:url], meta[property=og:title], meta[property=og:description], meta[property=og:image], meta[property=article:published_time], meta[property=article:modified_time], meta[property=article:author], meta[property=article:section], meta[property=article:tag], meta[name=twitter:card].

config.twitter

Whether to add Twitter metadata (boolean, default: false).

Affects: meta[name=twitter:card], meta[name=twitter:image], meta[name=twitter:site], meta[name=twitter:creator].

config.copyright

Whether to add copyright metadata (boolean, default: false).

Affects: meta[name=copyright].

config.type

What the document refers to ('website' | 'article', default: website).

Affects: meta[property=og:type], meta[property=article:published_time], meta[property=article:modified_time], meta[property=article:author], meta[property=article:section], meta[property=article:tag].

config.origin

Origin the file will be hosted on (string, optional, example: https://www.nytimes.com).

Affects: link[rel=canonical], meta[property=og:url].

config.pathname

Absolute pathname of where the file will be hosted (string, default: /, example: /interactive/2019/12/02/nyregion/nyc-subway-map.html).

Affects: link[rel=canonical], meta[property=og:url].

config.name

Name of the whole site (string, optional, example: 'The New York Times').

Affects: title, meta[property=og:site_name].

config.siteTags

Tags associated with the whole site (Array.<string>, optional, example: ['US Politics', 'Impeachment', 'NATO', 'London', 'Food', 'Poverty', 'Climate Change', 'Global Warming']).

Affects: meta[name=keywords].

config.siteAuthor

Name of the author of the whole site (string, optional, example: 'The New York Times').

Affects: meta[name=author], meta[name=copyright].

config.siteTwitter

Twitter username of the whole site (string, optional, example: '@nytimes').

Affects: meta[name=twitter:site].

config.color

Hexadecimal theme color of document or site (string, optional, example: '#bada55').

Affects: meta[name=theme-color].

config.author

Name of the author of the document (string, optional, example: 'Jane Doe').

Affects: meta[name=author], meta[name=copyright].

config.authorTwitter

Twitter username of the author of the document (string, optional, example: '@janedoe').

Affects: meta[name=twitter:creator].

config.authorFacebook

Facebook username of the author of the document (string, optional, example: 'example').

Affects: meta[property=article:author].

config.title

Title of the document (string, optional, example: 'The New York City Subway Map as You’ve Never Seen It Before').

Affects: title, meta[property=og:title].

config.separator

Value to use to join the title and name together (string, default: ' - ').

Affects: title.

config.description

Value used to join the title and name together if both exist (string, optional, example: 'The city has changed drastically over the past 40 years, yet the M.T.A. map designed in 1979 has largely endured.').

Affects: meta[name=description], meta[property=og:description].

config.section

Section associated with the document (string, optional, example: 'New York').

Affects: meta[property=article:section].

config.tags

Tags associated with the document (Array.<string>, optional, example: ['Subway', 'Map', 'Public Transit', 'Design', 'MTA', 'Massimo Vignelli', 'NYC']).

Affects: meta[name=keywords], meta[property=article:tag].

config.image

One or more images associated with the document (string, Image, or Array.<string | Image>, optional). If strings are passed, they are seen as Image objects with a url field set to that value.

Image:

  • url (string, required, example: 'https://static01.nyt.com/images/…/mta-crop-jumbo.jpg')
  • alt (string, optional, example: 'M.T.A. map designed in 1979')
  • width (string, optional, example: '1050')
  • height (string, optional, example: '550')

Affects: meta[property=og:image], meta[name=twitter:card], meta[name=twitter:image].

config.published

Date the document (or site) was first published (Date or string, optional, example: '2019-12-02T10:00:00.000Z').

Note: parsing a string is inconsistent, prefer dates.

Affects: meta[name=copyright], meta[property=article:published_time].

config.modified

Date the document was last modified (Date or string, optional, example: '2019-12-03T19:13:00.000Z').

Note: parsing a string is inconsistent, prefer dates.

Affects: meta[property=article:modified_time].

Metadata

The following metadata can be added by rehype-meta.

title

Affected by: title, name, separator.

If title is 'About':

<title>About</title>

If name is 'Example':

<title>Example</title>

If title is 'About' and name is 'Example':

<title>About - Example</title>

If title is 'About', name is 'Example', and separator to ' | ':

<title>About | Example</title>
link[rel=canonical]

Affected by: origin, pathname.

If origin is 'https://example.com' and path is '/path/':

<link rel="canonical" href="https://example.com/path/">

If origin is 'https://example.com' and path is not set:

<link rel="canonical" href="https://example.com/">
meta[name=description]

Affected by: description.

If description is 'Lorem ipsum':

<meta name="description" content="Lorem ipsum">
meta[name=keywords]

Affected by: tags, siteTags.

If tags is ['a', 'b']:

<meta name="keywords" content="a, b">

If siteTags is ['b', 'c']:

<meta name="keywords" content="b, c">

If tags is ['a', 'b'] and siteTags is ['b', 'c']:

<meta name="keywords" content="a, b, c">
meta[name=author]

Affected by: author, siteAuthor.

If author is 'Jane':

<meta name="author" content="Jane">

If siteAuthor is 'John':

<meta name="author" content="John">

If author is 'Jane' and siteAuthor is 'John':

<meta name="author" content="Jane">
meta[name=copyright]

Affected by: copyright, author, siteAuthor, published.

The below examples depend on the current date, so for example purposes, say it was the year 2030.

If copyright is not true, meta[name=copyright] is not added.

If copyright is true and author is 'Jane':

<meta name="copyright" content="© 2030 Jane">

If copyright is true and siteAuthor is 'John':

<meta name="copyright" content="© 2030 John">

If copyright is true, author is 'Jane', and siteAuthor is 'John':

<meta name="copyright" content="© 2030 Jane">

If copyright is true, author is 'Jane', and published is '2015':

<meta name="copyright" content="© 2015 Jane">
meta[name=theme-color]

Affected by: color.

If color is '#bada55':

<meta name="theme-color" content="#bada55">
meta[property=og:type]

Affected by: og, type.

If og is not true, meta[property=og:type] is not added.

If og is true and type is 'website':

<meta property="og:type" content="website">

If og is true and type is 'article':

<meta property="og:type" content="article">
meta[property=og:site_name]

Affected by: og, name.

If og is not true, meta[property=og:site_name] is not added.

If og is true and name is 'Example':

<meta property="og:site_name" content="Example">
meta[property=og:url]

Affected by: og, origin, pathname.

If og is not true, meta[property=og:url] is not added.

If og is true, origin is 'https://example.com', and path is '/path/':

<meta property="og:url" content="https://example.com/path/">

If origin is 'https://example.com' and path is not set:

<meta property="og:url" content="https://example.com/">
meta[property=og:title]

Affected by: og, title.

If og is not true, meta[property=og:title] is not added.

If og is true and title is 'About':

<meta property="og:title" content="title">
meta[property=og:description]

Affected by: og, description.

If og is not true, meta[property=og:description] is not added.

If og is true and description is 'Lorem ipsum':

<meta property="og:description" content="Lorem ipsum">
meta[property=og:image]

Affected by: og, image.

If og is not true, meta[property=og:image], meta[property=og:image:alt], meta[property=og:image:width], and meta[property=og:image:height] are not added.

Note: up to 6 images are added.

If og is true and image is 'https://example.com/image.png':

<meta property="og:image" content="https://example.com/image.png">

If og is true and image is ['https://example.com/a.png', 'https://example.com/b.png']:

<meta property="og:image" content="https://example.com/a.png">
<meta property="og:image" content="https://example.com/b.png">

If og is true and image is {url: 'https://example.com/a.png', alt: 'A', width: '670', height: '1012'}:

<meta property="og:image" content="https://example.com/a.png">
<meta property="og:image:alt" content="A">
<meta property="og:image:width" content="670">
<meta property="og:image:height" content="1012">
meta[property=article:published_time]

Affected by: og, type, published.

If og is not true or type is not 'article', meta[property=article:published_time] is not added.

If og is true, type is 'article', and published is '2014-06-30T15:01:35-05:00':

<meta property="article:published_time" content="2014-06-30T20:01:35.000Z">
meta[property=article:modified_time]

Affected by: og, type, modified.

If og is not true or type is not 'article', meta[property=article:modified_time] is not added.

If og is true, type is 'article', and modified is '2017-04-26T22:37:10-05:00':

<meta property="article:modified_time" content="2017-04-27T03:37:10.000Z">
meta[property=article:author]

Affected by: og, type, authorFacebook.

If og is not true or type is not 'article', meta[property=article:author] is not added.

If og is true, type is 'article', and authorFacebook is 'jane':

<meta property="article:author" content="https://www.facebook.com/jane">
meta[property=article:section]

Affected by: og, type, section.

If og is not true or type is not 'article', meta[property=article:section] is not added.

If og is true, type is 'article', and section is 'Politics':

<meta property="article:section" content="Politics">
meta[property=article:tag]

Affected by: og, type, tag.

If og is not true or type is not 'article', meta[property=article:tag] are not added.

Note: up to 6 tags are added.

If og is true, type is 'article', and tags is ['US Politics', 'Impeachment', 'NATO', 'London', 'Food', 'Poverty', 'Climate Change']:

<meta property="article:tag" content="US Politics">
<meta property="article:tag" content="Impeachment">
<meta property="article:tag" content="NATO">
<meta property="article:tag" content="London">
<meta property="article:tag" content="Food">
<meta property="article:tag" content="Poverty">
meta[name=twitter:card]

Affected by: og, twitter, image.

If twitter is not true, meta[name=twitter:card] is not added. If twitter is true, og is true, and there is no valid image, no meta[name=twitter:card] is added either, because Twitter assumes a summary in this case.

If twitter is true and there is a valid image:

<meta name="twitter:card" content="summary_large_image">

If twitter is true and there is no valid image:

<meta name="twitter:card" content="summary">
meta[name=twitter:image]

Affected by: twitter, image.

If twitter is not true, meta[name=twitter:image] and meta[name=twitter:image:alt] are not added.

Note: only one image is added.

If twitter is true and image is 'https://example.com/image.png':

<meta name="twitter:image" content="https://example.com/image.png">

If twitter is true and image is ['https://example.com/a.png', 'https://example.com/b.png']:

<meta name="twitter:image" content="https://example.com/a.png">

If twitter is true and image is {url: 'https://example.com/a.png', alt: 'A', width: '670', height: '1012'}:

<meta name="twitter:image" content="https://example.com/a.png">
<meta name="twitter:image:alt" content="A">
meta[name=twitter:site]

Affected by: twitter, siteTwitter.

If twitter is not true, meta[name=twitter:site] is not added.

If twitter is true and siteTwitter is '@example':

<meta name="twitter:site" content="@example">
meta[name=twitter:creator]

Affected by: twitter, authorTwitter.

If twitter is not true, meta[name=twitter:creator] is not added.

If twitter is true and authorTwitter is '@example':

<meta name="twitter:creator" content="@example">

Security

Use of rehype-meta is relatively safe, however, it is possible for an attacker to define metadata from within a because of the matter integration .

Related

Contribute

See contributing.md in rehypejs/.github for ways to get started. See support.md for ways to get help.

This project has a code of conduct. By interacting with this repository, organization, or community you agree to abide by its terms.

License

MIT © Titus Wormer

Keywords

Install

npm i rehype-meta

Fund this package

DownloadsWeekly Downloads

9

Version

2.0.0

License

MIT

Unpacked Size

35.7 kB

Total Files

4

Homepage

github.com/rehypejs/rehype-meta#readme

Repository

Gitgithub.com/rehypejs/rehype-meta

Last publish

Collaborators

  • avatar
  • avatar
Try on RunKit
Report malware