The problem

You're using @remark-embedder/core to automatically convert URLs in your markdown to the embedded version of those URLs and want to have a transform for providers that support an oEmbed API. Learn more about oEmbed from oembed.com

This solution

This is a @remark-embedder transform for supported oembed API providers. Find the list of supported providers on oembed.com.

Table of Contents

• Installation
• Usage
  • Config
  • Config as a function
• Inspiration
• Other Solutions
• Issues
  • 🐛 Bugs
  • 💡 Feature Requests
• Contributors ✨
• LICENSE

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 @remark-embedder/transformer-oembed

Usage

import remarkEmbedder from '@remark-embedder/core'
import oembedTransformer from '@remark-embedder/transformer-oembed'
// or, if you're using CommonJS require:
// const {default: oembedTransformer} = require('@remark-embedder/transformer-oembed')
import remark from 'remark'
import html from 'remark-html'

const exampleMarkdown = `
# My favorite YouTube video

[This](https://www.youtube.com/watch?v=dQw4w9WgXcQ) is a great YouTube video.
Watch it here:

https://www.youtube.com/watch?v=dQw4w9WgXcQ

Isn't it great!?
`

async function go() {
  const result = await remark()
    .use(remarkEmbedder, {
      transformers: [oembedTransformer],
    })
    .use(html)
    .process(exampleMarkdown)

  console.log(result.toString())
}

go()

This will result in:

<h1>My favorite YouTube video</h1>
<p>
  <a href="https://www.youtube.com/watch?v=dQw4w9WgXcQ">This</a> is a great
  YouTube video. Watch it here:
</p>
<iframe
  width="200"
  height="113"
  src="https://www.youtube.com/embed/dQw4w9WgXcQ?feature=oembed"
  frameborder="0"
  allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
  allowfullscreen
></iframe>
<p>Isn't it great!?</p>

Config

Some oembed providers offer special configuration via query parameters. You can provide those via config:

// ...
import type {Config} from '@remark-embedder/transformer-oembed'

// ...

async function go() {
  const result = await remark()
    .use(remarkEmbedder, {
      transformers: [
        [
          oembedTransformer,
          {params: {theme: 'dark', dnt: true, omit_script: true}} as Config,
        ],
      ],
    })
    .use(html)
    .process(`https://twitter.com/kentcdodds/status/783161196945944580`)

  console.log(result.toString())
}

// ...

That results in (notice the data- attributes which are specific to twitter's oEmbed API):

<blockquote class="twitter-tweet" data-dnt="true" data-theme="dark">
  <p lang="en" dir="ltr">
    I spent a few minutes working on this, just for you all. I promise, it wont
    disappoint. Though it may surprise 🎉<br /><br />🙏
    <a href="https://t.co/wgTJYYHOzD">https://t.co/wgTJYYHOzD</a>
  </p>
  — Kent C. Dodds (@kentcdodds)
  <a
    href="https://twitter.com/kentcdodds/status/783161196945944580?ref_src=twsrc%5Etfw"
    >October 4, 2016</a
  >
</blockquote>

This could also be used to provide an access token for providers that require this (like Instagram).

Config as a function

You can also provide configuration as a function so you can determine what configuration to give based on the provider and/or the URL. Like so:

const oembedConfig: Config = ({url, provider}) => {
  if (provider.provider_name === 'Instagram') {
    return {
      params: {access_token: '{app-id}|{client-token}'},
    }
  }
}
const remarkEmbedderConfig = {
  transformers: [[oembedTransformer, oembedConfig]],
}
// ... etc...

Inspiration

It's a long story... Check out the inspiration on @remark-embedder/core

Other Solutions

• remark-oembed: This one requires client-side JS to work which was unacceptable for our use cases.

Issues

Looking to contribute? Look for the Good First Issue label.

🐛 Bugs

Please file an issue for bugs, missing documentation, or unexpected behavior.

See 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

Contributors ✨

Thanks goes to these people (emoji key):

Kent C. Dodds 💻 📖 🚇 ⚠️

Michaël De Boey 💻 📖 🚧

This project follows the all-contributors specification. Contributions of any kind welcome!

LICENSE

MIT