https://github.com/MichaelDeBoey/gatsby-remark-embedder
Gatsby Remark plugin to embed well known services by their URL.
https://github.com/MichaelDeBoey/gatsby-remark-embedder
codepen codesandbox embed gatsby gatsby-plugin gatsby-remark giphy instagram linchess markdown pinterest remark slides soundcloud spotify streamable testing-playground twitch twitter youtube
Last synced: about 1 month ago
JSON representation
Gatsby Remark plugin to embed well known services by their URL.
- Host: GitHub
- URL: https://github.com/MichaelDeBoey/gatsby-remark-embedder
- Owner: MichaelDeBoey
- License: mit
- Created: 2019-07-20T12:16:53.000Z (almost 6 years ago)
- Default Branch: main
- Last Pushed: 2023-05-30T19:17:37.000Z (almost 2 years ago)
- Last Synced: 2025-03-09T17:46:01.730Z (about 1 month ago)
- Topics: codepen, codesandbox, embed, gatsby, gatsby-plugin, gatsby-remark, giphy, instagram, linchess, markdown, pinterest, remark, slides, soundcloud, spotify, streamable, testing-playground, twitch, twitter, youtube
- Language: JavaScript
- Homepage:
- Size: 449 KB
- Stars: 300
- Watchers: 9
- Forks: 59
- Open Issues: 41
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
- awesome-list - gatsby-remark-embedder
README
gatsby-remark-embedder
Gatsby Remark plugin to embed well known services by their URL.
---
[![Build Status][build-badge]][build]
[![Code Coverage][coverage-badge]][coverage]
[![version][version-badge]][package]
[![downloads][downloads-badge]][npmtrends]
[![MIT License][license-badge]][license]
[![All Contributors][all-contributors-badge]](#contributors-)
[![PRs Welcome][prs-badge]][prs]
[![Code of Conduct][coc-badge]][coc]
## The problem
Trying to embed well known services (like [CodePen][codepen],
[CodeSandbox][codesandbox], [GIPHY][giphy], [Instagram][instagram],
[Lichess][lichess], [Pinterest][pinterest], [Slides][slides],
[SoundCloud][soundcloud], [Spotify][spotify], [Streamable][streamable], [Testing
Playground][testing-playground], [Twitch][twitch], [Twitter][twitter] or
[YouTube][youtube]) into your [Gatsby][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](#installation)
- [Usage](#usage)
- [Supported services](#supported-services)
- [CodePen](#codepen)
- [CodeSandbox](#codesandbox)
- [GIPHY](#giphy)
- [Instagram](#instagram)
- [Lichess](#lichess)
- [Pinterest](#pinterest)
- [Slides](#slides)
- [SoundCloud](#soundcloud)
- [Spotify](#spotify)
- [Streamable](#streamable)
- [Testing Playground](#testing-playground)
- [Twitch](#twitch)
- [Twitter](#twitter)
- [YouTube](#youtube)
- [Options](#options)
- [customTransformers](#customtransformers)
- [services](#services)
- [Inspiration](#inspiration)
- [Issues](#issues)
- [🐛 Bugs](#-bugs)
- [💡 Feature Requests](#-feature-requests)
- [Contributors ✨](#contributors-)
- [LICENSE](#license)
## Installation
This module is distributed via [npm][npm] which is bundled with [node][node] and
should be installed as one of your project's `dependencies`:
```sh
npm install gatsby-remark-embedder
```
or
```sh
yarn add gatsby-remark-embedder
```
This library has a required `peerDependencies` listing for [`gatsby`][gatsby]
and should be used as a plugin for
[`gatsby-transformer-remark`][gatsby-transformer-remark] or
[`gatsby-plugin-mdx`][gatsby-plugin-mdx].
Depending on the [services](#supported-services) you want to embed, you should
also install [`gatsby-plugin-instagram-embed`][gatsby-plugin-instagram-embed],
[`gatsby-plugin-pinterest`][gatsby-plugin-pinterest] and/or
[`gatsby-plugin-twitter`][gatsby-plugin-twitter].
## Usage
```js
// 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
```js
// 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
```md
https://codepen.io/team/codepen/pen/PNaGbb
```
Result
```html
```
### CodeSandbox
#### Usage
```md
https://codesandbox.io/s/ynn88nx9x?view=split
```
Result
```html
```
### GIPHY
#### Usage
```md
https://giphy.com/gifs/howtogiphygifs-how-to-XatG8bioEwwVO
```
Result
```html
```
### Instagram
The 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`][gatsby-plugin-instagram-embed].
#### Usage
```md
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][instagram-oembed-access-token-docs] and
[requirements][instagram-oembed-requirements-docs].
The safest way to enter your `accessToken` is to set is as an [environment
variable][gatsby-environment-variables-docs].
Example
```js
const GatsbyRemarkEmbedderOptions = {
services: {
Instagram: {
accessToken: process.env.INSTAGRAM_ACCESS_TOKEN,
},
},
};
```
### Lichess
#### Usage
```md
https://lichess.org/MPJcy1JW
```
Result
```html
```
### Pinterest
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`][gatsby-plugin-pinterest].
#### Usage
```md
https://pinterest.com/pin/99360735500167749
```
Result
### Slides
#### Usage
```md
https://slides.com/kentcdodds/oss-we-want
```
Result
```html
```
### SoundCloud
#### Usage
```md
https://soundcloud.com/clemenswenners/africa
```
Result
```html
```
### Spotify
#### Usage
```md
https://open.spotify.com/track/0It2bnTdLl2vyymzOkBI3L
```
Result
```html
```
### Streamable
#### Usage
```md
https://streamable.com/moo
```
Result
```html
```
### Testing Playground
#### Usage
```md
https://testing-playground.com/gist/fb336c386145b235372a0f57d5c58205/6d13e4ee508301c8b42f9d2cc8584e70bb05fb4a
```
Result
```html
```
### Twitch
Twitch embeds can only be embedded on HTTPS websites. Check out [the Gatsby
docs][gatsby-https-docs] for setting this up when developing locally.
#### Usage
```md
https://twitch.tv/videos/546761743
```
Result
```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][netlify-environment-variables-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][vercel-environment-variables-docs] for more info.
Example
```js
const GatsbyRemarkEmbedderOptions = {
services: {
Twitch: {
parent: [
process.env.VERCEL_URL,
// Other domains here...
],
},
},
};
```
### Twitter
The returned HTML snippet from the Twitter transformer will only be
automatically recognized as an [Embedded Tweet][embedded-tweet-docs] when
[Twitter's widget JavaScript][twitter-widget-javascript-docs] 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`][gatsby-plugin-twitter].
#### Usage
```md
https://twitter.com/MichaelDeBoey93/status/1152991421789548546
https://twitter.com/i/moments/994601867987619840
https://twitter.com/wesbos/timelines/1189618481672667136
```
Result
```html
Happy to announce I just published the first gatsby-remark-embedder 🎉🎉🎉
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
— Michaël De Boey (@MichaelDeBoey93)
July 21, 2019
🔥 Hot Tips from Wes Bos - Curated tweets by wesbos
```
### 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
```md
https://youtu.be/dQw4w9WgXcQ
```
Result
```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](#services). The value for this key will be provided
as the second argument to [`getHTML`](#gethtmlurl-options).
##### `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
```js
// some-site-transformer.js
const getHTML = (url) => ``;
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](#supported-services) 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][kentcdodds.com-repo].
The intention is to make this available to be used independently.
## Issues
_Looking to contribute? Look for the [Good First Issue][good-first-issue]
label._
### 🐛 Bugs
Please file an issue for bugs, missing documentation, or unexpected behavior.
[**See Bugs**][bugs]
### 💡 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.
[**See Feature Requests**][requests]
## Contributors ✨
Thanks goes to these people ([emoji key][emojis]):
Kent C. Dodds
💻 📖 🤔 🚇 ⚠️
Michaël De Boey
🐛 💻 📖 ⚠️
Kornel Dubieniecki
🐛
Nick Nish
💻 ⚠️
Caneco
🎨
Anurag Hazra
🐛 💻 ⚠️ 📖
Yash Joshi
💻 ⚠️
Christian C. Salvadó
💻 ⚠️
James Simone
💻 ⚠️
Agastya Chandrakant
💻 ⚠️
Fábio Rosado
💻 ⚠️
Arryangga Aliev Pratamaputra
🐛
Eduardo Reveles
💻 ⚠️
Michal Piechowiak
🐛 💻 ⚠️
Brad Garropy
🐛
Ilya Lyamkin
💻
Simon MacDonald
🐛 💻 ⚠️
Nicky Meuleman
💻
Ayush
💻
TEEAARBEE
🐛
Trevor Blades
📖
Titus
⚠️ 👀 💻
Joe Previte
🐛
This project follows the [all-contributors][all-contributors] specification.
Contributions of any kind welcome!
## LICENSE
MIT
[npm]: https://www.npmjs.com
[node]: https://nodejs.org
[build-badge]: https://img.shields.io/github/workflow/status/MichaelDeBoey/gatsby-remark-embedder/validate?logo=github&style=flat-square
[build]: https://github.com/MichaelDeBoey/gatsby-remark-embedder/actions?query=workflow%3Avalidate
[coverage-badge]: https://img.shields.io/codecov/c/github/MichaelDeBoey/gatsby-remark-embedder.svg?style=flat-square
[coverage]: https://codecov.io/github/MichaelDeBoey/gatsby-remark-embedder
[version-badge]: https://img.shields.io/npm/v/gatsby-remark-embedder.svg?style=flat-square
[package]: https://www.npmjs.com/package/gatsby-remark-embedder
[downloads-badge]: https://img.shields.io/npm/dm/gatsby-remark-embedder.svg?style=flat-square
[npmtrends]: https://www.npmtrends.com/gatsby-remark-embedder
[license-badge]: https://img.shields.io/npm/l/gatsby-remark-embedder.svg?style=flat-square
[license]: https://github.com/MichaelDeBoey/gatsby-remark-embedder/blob/main/LICENSE
[prs-badge]: https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square
[prs]: https://makeapullrequest.com
[coc-badge]: https://img.shields.io/badge/code%20of-conduct-ff69b4.svg?style=flat-square
[coc]: https://github.com/MichaelDeBoey/gatsby-remark-embedder/blob/main/CODE_OF_CONDUCT.md
[emojis]: https://allcontributors.org/docs/en/emoji-key
[all-contributors]: https://github.com/all-contributors/all-contributors
[all-contributors-badge]: https://img.shields.io/github/all-contributors/MichaelDeBoey/gatsby-remark-embedder?color=orange&style=flat-square
[bugs]: https://github.com/MichaelDeBoey/gatsby-remark-embedder/issues?utf8=%E2%9C%93&q=is%3Aissue+is%3Aopen+sort%3Acreated-desc+label%3Abug
[requests]: https://github.com/MichaelDeBoey/gatsby-remark-embedder/issues?utf8=%E2%9C%93&q=is%3Aissue+is%3Aopen+sort%3Areactions-%2B1-desc+label%3Aenhancement
[good-first-issue]: https://github.com/MichaelDeBoey/gatsby-remark-embedder/issues?utf8=%E2%9C%93&q=is%3Aissue+is%3Aopen+sort%3Areactions-%2B1-desc+label%3A%22good+first+issue%22
[codepen]: https://codepen.io
[codesandbox]: https://codesandbox.io
[embedded-tweet-docs]: https://developer.twitter.com/web/embedded-tweets
[gatsby]: https://github.com/gatsbyjs/gatsby
[gatsby-environment-variables-docs]: https://www.gatsbyjs.com/docs/environment-variables
[gatsby-https-docs]: https://gatsbyjs.org/docs/local-https
[gatsby-plugin-instagram-embed]: https://github.com/MichaelDeBoey/gatsby-plugin-instagram-embed
[gatsby-plugin-mdx]: https://github.com/gatsbyjs/gatsby/tree/master/packages/gatsby-plugin-mdx
[gatsby-plugin-pinterest]: https://github.com/robinmetral/gatsby-plugin-pinterest
[gatsby-plugin-twitter]: https://github.com/gatsbyjs/gatsby/tree/master/packages/gatsby-plugin-twitter
[gatsby-transformer-remark]: https://github.com/gatsbyjs/gatsby/tree/master/packages/gatsby-transformer-remark
[giphy]: https://giphy.com
[instagram]: https://instagram.com
[instagram-oembed-access-token-docs]: https://developers.facebook.com/docs/instagram/oembed#access-tokens
[instagram-oembed-requirements-docs]: https://developers.facebook.com/docs/instagram/oembed#requirements
[kentcdodds.com-repo]: https://github.com/kentcdodds/kentcdodds.com
[lichess]: https://lichess.org
[netlify-environment-variables-docs]: https://docs.netlify.com/configure-builds/environment-variables/#deploy-urls-and-metadata
[pinterest]: https://pinterest.com
[slides]: https://slides.com
[soundcloud]: https://soundcloud.com
[spotify]: https://spotify.com
[streamable]: https://streamable.com
[testing-playground]: https://testing-playground.com
[twitch]: https://twitch.tv
[twitter]: https://twitter.com
[twitter-widget-javascript-docs]: https://developer.twitter.com/en/docs/twitter-for-websites/javascript-api/overview
[vercel-environment-variables-docs]: https://vercel.com/docs/v2/build-step?query=Build#system-environment-variables
[youtube]: https://youtube.com