gatsby-remark-embedder
Gatsby Remark plugin to embed well known services by their URL.
The problem
Trying to embed well known services (like CodePen, CodeSandbox, GIPHY, Instagram, Lichess, Pinterest, Slides, SoundCloud, Spotify, Streamable, Testing Playground, Twitch, Twitter or YouTube) into your Gatsby website can be hard, since you have to know how this needs to be done for all of these different services.
This solution
gatsby-remark-embedder tries to solve this problem for you by letting you just
copy-paste the link to the
gif/pen/pin/player/playground/post/sandbox/tweet/video you want to embed right
from within your browser onto a separate line (surrounded by empty lines) and
replace it with the proper embed-code.
Table of Contents
Installation
This module is distributed via npm which is bundled with node and
should be installed as one of your project's dependencies:
npm install gatsby-remark-embedderor
yarn add gatsby-remark-embedderThis library has a required peerDependencies listing for gatsby
and should be used as a plugin for
gatsby-transformer-remark or
gatsby-plugin-mdx.
Depending on the services you want to embed, you should
also install gatsby-plugin-instagram-embed,
gatsby-plugin-pinterest and/or
gatsby-plugin-twitter.
Usage
// In your gatsby-config.js
module.exports = {
// Find the 'plugins' array
plugins: [
{
resolve: `gatsby-transformer-remark`,
options: {
plugins: [
{
resolve: `gatsby-remark-embedder`,
options: {
customTransformers: [
// Your custom transformers
],
services: {
// The service-specific options by the name of the service
},
},
},
// Other plugins here...
],
},
},
],
};or
// In your gatsby-config.js
module.exports = {
// Find the 'plugins' array
plugins: [
{
resolve: `gatsby-plugin-mdx`,
options: {
gatsbyRemarkPlugins: [
{
resolve: `gatsby-remark-embedder`,
options: {
customTransformers: [
// Your custom transformers
],
services: {
// The service-specific options by the name of the service
},
},
},
// Other plugins here...
],
},
},
],
};Supported services
CodePen
Usage
https://codepen.io/team/codepen/pen/PNaGbbResult
```html ```CodeSandbox
Usage
https://codesandbox.io/s/ynn88nx9x?view=splitResult
```html ```GIPHY
Usage
https://giphy.com/gifs/howtogiphygifs-how-to-XatG8bioEwwVOResult
```htmlThe returned HTML snippet from the Instagram transformer will only be
automatically recognized as an embedded post when Instagram's embed JavaScript
is included on the page.
Since the Instagram transformer doesn't include this JavaScript (because we
don't want to include it multiple times on a page when having multiple embeds),
you have to include it yourself. The recommended way of including it is by using
gatsby-plugin-instagram-embed.
Usage
https://instagram.com/p/B60jPE6J8U-Result
```html```
Options
All options should go under the Instagram namespace.
| name | Type | Required | Default | Description |
|---|---|---|---|---|
| accessToken | string |
✅ | An App Access Token (recommended) or Client Access Token |
accessToken
To get an App Access Token (recommended) or Client Access Token for the Instagram embed, check out the Instagram oEmbed access token docs and requirements.
The safest way to enter your accessToken is to set is as an environment
variable.
Example
```js const GatsbyRemarkEmbedderOptions = { services: { Instagram: { accessToken: process.env.INSTAGRAM_ACCESS_TOKEN, }, }, }; ```Lichess
Usage
https://lichess.org/MPJcy1JWResult
```html ```The returned HTML snippet from the Pinterest transformer will only be
automatically recognized as an embedded pin when Pinterest's embed JavaScript is
included on the page.
Since the Pinterest transformer doesn't include this JavaScript (because we
don't want to include it multiple times on a page when having multiple embeds),
you have to include it yourself. The recommended way of including it is by using
gatsby-plugin-pinterest.
Usage
https://pinterest.com/pin/99360735500167749Slides
Usage
https://slides.com/kentcdodds/oss-we-wantResult
```html ```SoundCloud
Usage
https://soundcloud.com/clemenswenners/africaResult
```html ```Spotify
Usage
https://open.spotify.com/track/0It2bnTdLl2vyymzOkBI3LResult
```html ```Streamable
Usage
https://streamable.com/mooResult
```html ```Testing Playground
Usage
https://testing-playground.com/gist/fb336c386145b235372a0f57d5c58205/6d13e4ee508301c8b42f9d2cc8584e70bb05fb4aResult
```html ```Twitch
Twitch embeds can only be embedded on HTTPS websites. Check out the Gatsby docs for setting this up when developing locally.
Usage
https://twitch.tv/videos/546761743Result
```html ```Options
All options should go under the Twitch namespace.
| name | Type | Required | Default | Description |
|---|---|---|---|---|
| parent | string / string[] |
✅ | Domain(s) that will be embedding Twitch. You must have one parent key for each domain your site uses. |
parent
You could either put in (a) hardcoded value(s) or you could use environment variables that are available during the build process.
Netlify
Netlify has the URL, DEPLOY_URL and DEPLOY_PRIME_URL environment
variables. Take a look at the Netlify docs
for more info.
Example
```js const GatsbyRemarkEmbedderOptions = { services: { Twitch: { parent: [ process.env.URL, process.env.DEPLOY_URL, process.env.DEPLOY_PRIME_URL, // Other domains here... ], }, }, }; ```Vercel
Vercel has the VERCEL_URL environment variable. Take a look at the Vercel
docs for more info.
Example
```js const GatsbyRemarkEmbedderOptions = { services: { Twitch: { parent: [ process.env.VERCEL_URL, // Other domains here... ], }, }, }; ```The returned HTML snippet from the Twitter transformer will only be
automatically recognized as an Embedded Tweet when
Twitter's widget JavaScript is included on the
page.
Since the Twitter transformer doesn't include this JavaScript (because we don't
want to include it multiple times on a page when having multiple embeds), you
have to include it yourself. The recommended way of including it is by using
gatsby-plugin-twitter.
Usage
https://twitter.com/MichaelDeBoey93/status/1152991421789548546
https://twitter.com/i/moments/994601867987619840
https://twitter.com/wesbos/timelines/1189618481672667136Result
```html🔥 Design Tips 🔥 Hot Tips from Wes Bos - Curated tweets by wesbos ```Happy to announce I just published the first gatsby-remark-embedder 🎉🎉🎉
— Michaël De Boey (@MichaelDeBoey93) July 21, 2019
This first version is an extract of @kentcdodds' personal website remark-embedder plugin, but I'm planning on adding extra services then @codesandbox, @Twitter & @YouTube too. https://t.co/M4PA9aFZdG
YouTube
The YouTube transformer (currently) only supports videos in the following formats:
- Full url (
https://youtube.com/watch?v=dQw4w9WgXcQ) - Short url (
https://youtu.be/dQw4w9WgXcQ)
Usage
https://youtu.be/dQw4w9WgXcQResult
```html ```Options
customTransformers
The plugin allows you to pass an array of custom transformers that will be executed additionally to the default ones.
Properties
Each transformer should be an object which has the following properties:
getHTML(url, options)
The getHTML method is executed when the given URL has been matched to
transform. It should return the transformed HTML.
This asynchronous function receives the URL to transform together with an
options object to take into account when transforming.
name
The name is the value that needs to be used as a key in the
services plugin option. The value for this key will be provided
as the second argument to getHTML.
shouldTransform(url)
The shouldTransform method should check if the given URL matches the one
intended to transform. It should return a boolean value.
Example transformer
// some-site-transformer.js
const getHTML = (url) => `<iframe src="https://github.com/MichaelDeBoey/gatsby-remark-embedder/raw/main/${url}"></iframe>`;
const name = 'someSite';
const regex = /^https?:\/\/some-site\.com\//;
const shouldTransform = (url) => regex.test(url);
module.exports = { getHTML, name, shouldTransform };services
The plugin also allows you to pass an object which keys that represent the name of the service to transform and the value that's an object with options for that specific service.
Inspiration
This whole plugin was extracted out of Kent C. Dodds' personal website.
The intention is to make this available to be used independently.
Issues
Looking to contribute? Look for the Good First Issue label.
🐛 Bugs
Please file an issue for bugs, missing documentation, or unexpected behavior.
💡 Feature Requests
Please file an issue to suggest new features. Vote on feature requests by adding a 👍. This helps maintainers prioritize what to work on.
Contributors ✨
Thanks goes to these people (emoji key):
This project follows the all-contributors specification. Contributions of any kind welcome!
LICENSE
MIT