rehype-meta
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 = var rehype = var meta = data'settings' fragment: true
Now, running node example
yields:
no issues foundThe New York City Subway Map as You’ve Never Seen It Before | The New York Times
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.
- Pass an object as
options
when usingmeta
- Define it in YAML front matter (by integrating with
vfile-matter
) - 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'
:
About
If name
is 'Example'
:
Example
If title
is 'About'
and name
is 'Example'
:
About - Example
If title
is 'About'
, name
is 'Example'
, and separator to ' | '
:
About | Example
link[rel=canonical]
Affected by: origin
, pathname
.
If origin
is 'https://example.com'
and path
is '/path/'
:
If origin
is 'https://example.com'
and path
is not set:
meta[name=description]
Affected by: description
.
If description
is 'Lorem ipsum'
:
meta[name=keywords]
If tags
is ['a', 'b']
:
If siteTags
is ['b', 'c']
:
If tags
is ['a', 'b']
and siteTags
is ['b', 'c']
:
meta[name=author]
Affected by: author
, siteAuthor
.
If author
is 'Jane'
:
If siteAuthor
is 'John'
:
If author
is 'Jane'
and siteAuthor
is 'John'
:
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'
:
If copyright
is true
and siteAuthor
is 'John'
:
If copyright
is true
, author
is 'Jane'
, and siteAuthor
is 'John'
:
If copyright
is true
, author
is 'Jane'
, and published
is '2015'
:
meta[name=theme-color]
Affected by: color
.
If color
is '#bada55'
:
meta[property=og:type]
If og
is not true
, meta[property=og:type]
is not added.
If og
is true
and type
is 'website'
:
If og
is true
and type
is 'article'
:
meta[property=og:site_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: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/'
:
If origin
is 'https://example.com'
and path
is not set:
meta[property=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: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: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'
:
If og
is true
and image
is ['https://example.com/a.png', '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=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: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: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: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: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[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:
If twitter
is true
and there is no valid image:
meta[name=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'
:
If twitter
is true
and image
is ['https://example.com/a.png', 'https://example.com/b.png']
:
If twitter
is true
and image
is {url: 'https://example.com/a.png', alt: 'A', width: '670', height: '1012'}
:
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: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'
:
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
rehype-document
— Wrap a document around the treerehype-format
— Format HTMLrehype-minify
— Minify HTML
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.