eleventy-plugin-embed-twitter

1.4.1 • Public • Published

eleventy-plugin-embed-twitter

NPM Version Build test status codecov
MIT License Contributor Covenant

This Eleventy plugin automatically embeds Tweets from URLs in markdown files.

Install in Eleventy

In your Eleventy project, install the plugin through npm:

$ npm i eleventy-plugin-embed-twitter

Then add it to your Eleventy config file (usually .eleventy.js):

const embedTwitter = require("eleventy-plugin-embed-twitter");

module.exports = function(eleventyConfig) {
  eleventyConfig.addPlugin(embedTwitter);
};

Usage

To embed a Tweet into any markdown page, paste its URL into a new line. The URL should be the only thing on that line.

Markdown file example:

...

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nam vehicula, elit vel condimentum porta, purus.

https://twitter.com/SaraSoueidan/status/1289865845053652994s

Maecenas non velit nibh. Aenean eu justo et odio commodo ornare. In scelerisque sapien at.

...

Result:

Tweet by Sara Soueidan: “I've been increasingly feeling like Grid or Flex has become the new Tabs or Spaces.”

Configure

Plugin default options

The plugin’s default settings reside in lib/pluginDefaults.js. Pass an options object to the plugin to override any of its default settings.

Option Type Default
value
Notes
New in v1.3.0!
align
String undefined Change to left, center, or right to control the embed alignment.
New in v1.3.0!
cacheDuration
String 5m How long to cache the response from Twitter’s servers when cacheText is true. Use the eleventy-fetch syntax to set the duration. See also Caching Tweet content as plain HTML.
cacheText Boolean false Whether to save the Tweet content as plain HTML. Causes network calls on save. See Caching Tweet content as plain HTML for more details.
New in v1.3.0!
cards
String undefined Change to hidden to deactivate embedded media in Tweets, such as images or video.
New in v1.3.0!
conversation
String undefined Change to none to deactivate default automatic threading of the original Tweet when embedding a reply.
doNotTrack Boolean false Change to true to opt out of Twitter’s personalization features.
embedClass String eleventy-plugin-embed-twitter Class name applied to the div element that wrapps the embedded Tweet blockquote. Use the default string to target the embeds with CSS, or substitute your preferred string.
New in v1.3.0!
lang
String undefined Change to any of Twitter’s supported language codes to localize embedded Tweet components. Note that this has no connection to the language of the Tweet text itself!
theme String undefined By default, Tweets embed with a black-on-white color scheme. Change to dark to switch to dark mode display.
New in v1.3.0!
width
Number undefined Change to a whole number to control the width, in pixels, of embedded Tweets. Twitter recommends keeping this value between 250 and 550.
twitterScript Object
twitterScript.async Boolean true By default, Twitter’s JavaScript loads asynchronously. Changing to false will load it synchronously. Not recommended, as this harms page rendering performance.
twitterScript.charset String utf-8 The charset attribute for the Twitter script tag. This mirrors Twitter’s default embed approach, although charset is deprecated. Expect this option to be removed in a future release.
twitterScript.defer Boolean false Change to true to add a defer attribute to the Twitter script element. In most cases async is enough.
twitterScript.enabled Boolean true Change this to false to prevent the plugin from adding the Twitter script tag. Use this if you’re implementing your own strategy for loading Twitter’s widgets.js script.
twitterScript.src String https://platform.twitter.com/widgets.js The official URL for Twitter’s widgets.js script. This may be useful if you prefer to self-host your own version of the code instead of loading it from Twitter’s CDN.

Caching Tweet content as plain HTML

By default, the plugin does not save the text of the Tweet as plain HTML. That’s because doing so requires making a network request to Twitter. By default, we don’t make network calls unless you decide to enable them. To save the complete Tweet text when processing files in Eleventy, turn on the cacheText option:

eleventyConfig.addPlugin(embedTwitter, {
	cacheText: true,
});

As of v1.3.6, cacheText uses eleventy-fetch to download the text of the Tweet and cache it locally for up to 5 minutes, which reduces the overall number of network calls and speeds up builds. You can configure the cache timing with the cacheDuration option. If the plugin experiences any network failure (such as if you're not connected to the internet), then it simply won’t complete the embed and the Tweet URL will be rendered as plain text.

Notes and caveats

  • This plugin is deliberately designed only to embed when the URL is on its own line, and not inline with other text.
  • To do this, it uses a regular expression to recognize Twitter URLs, wrapped in an HTML <p> tag or, optionally, additionally wrapped in an anchor tag. If your Markdown parser produces any other output, it won’t be recognized.
  • The plugin supports common URL variants as well. Check the supported URL variants to see the complete list, but there are conceivably valid Twitter URLs that wouldn’t be recognized. Please file an issue if you run into an edge case!
  • This plugin uses transforms, so it alters Eleventy’s HTML output as it’s generated. It doesn’t alter the source markdown.
  • By necessity, this plugin will add a call to Twitter’s third-party JavaScript file. It does this once per page, if that page contains a Twitter embed.
  • Currently the plugin supports only individual Tweets. Embedding timelines, lists, or Twitter Moments isn’t possible right now.

Package Sidebar

Install

npm i eleventy-plugin-embed-twitter

Weekly Downloads

1,159

Version

1.4.1

License

MIT

Unpacked Size

20.1 kB

Total Files

9

Last publish

Collaborators

  • gfscott