Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.
Awesome Lists | Featured Topics | Projects
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 2 months 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 (about 5 years ago)
Default Branch: main
Last Pushed: 2023-05-30T19:17:37.000Z (over 1 year ago)
Last Synced: 2024-07-18T16:30:56.914Z (2 months 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: 294
Watchers: 10
Forks: 58
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



  

    

      

        

        

          

          

        

      

      

      

        

          

            

              

                

              

            

          

        

      

      

        

          View this post on Instagram

        

      

      

      

        

          

          

          

        

        

          

          

        

        

          

          

          

        



    

      Good morning New York! 🗽 #newyork #nyc #brotrip #newyear #2020 #city

        #bluesky #clearsky #timessquare #nycitylife #nycityworld #urban

        #manhattan #travel #cold #winter #citytrip #lastday #streetview

        #citythatneversleeps #bucketlist #buildings #skyscraper #midtown

    

    

      A post shared by

      

        Michaël De Boey

      (@michaeldeboey) on

      Jan 2, 2020 at 6:45am PST

    

  



```

#### 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

```html



```

### 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

  





  🔥 Design Tips





  🔥 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