A New Way to Embed External Content To Your Markdown Files with Remarkable-oEmbed

At Elastic Path, we use markdown to author our product documentation. Markdown is a great format for any type of content publishing. It's a plain text format that can be used without any special tools or software.

However, sometimes we need to add a little more than just plain text article. One request I had often received was to be able to add videos within the documentation, such as a visual step by step guide. But that's not natively supported by markdown format. Plus, these videos are hosted by a 3rd party service provider. That's also a problem because markdown does not have any native way of embedding contents external sources.

What is Markdown?

Markdown is simply a set of guidelines/syntax for writing. Markdown parsers then follow those guidelines and convert the document into another format for publishing. The syntax is very simple and does not get in the way of the readability of contents. A document written using pure markdown format can be consumed as-is. A common usage is converting those documents into html files for publishing online article.

With the simplicity of the markdown format, it is possible for anyone within our organization to be able to contribute to our product documentation. For the same reason, reviewing the content before publishing is also a smooth experience. We build our documentation website from the markdown documents using a tool called Docusaurus v1, which uses remarkable markdown parser for converting the documents into an HTML format.

How to embed external contents using Markdown?

As mentioned earlier, Markdown format does not have any syntax or guideline for embedding contents from external services. There are several ways a video or any other external contents could be added without using any special tools:

• A link to the external contents - This is the simplest approach but lacks a cohesive experience. The user will move away from the content and go into another site or page containing the video.


• An iFrame whose source is the page containing external contents - The drawback with this approach is that another "site/page" is being embedded in your page, instead of only the content you're interested in.


• Add html code provided by external content hosting platform - Usually the service providers have a "Share" or "Embed" option that will give you a block of html code that can be added into into your website. That code  can be added into your markdown document. But, this requires writing and maintaining html code in the markdown document. That affects the maintenance, simplicity, readability, and review of contents. Besides, even a small typo or mistake can break the html page when that document is converted from markdown into html.

All of the above approaches have some drawbacks. This is where oEmbed really shines. That's why we've built remarkable-oembed - a plugin for remarkable markdown parser.

What is oEmbed?

Similar to Markdown, oEmbed is simply a specification or guideline for content providers and consumers. Following the specs, providers can deliver contents to be consumable in any way without implementing tools for every consumer. Additionally, consumers can retrieve contents from various service providers without implementing specific tools for different providers.

You may have already used oEmbed in various tools or platforms. For example, have you ever added a link to an image or a video into a rich text editor, which then automatically replaces the link with the corresponding image or video? That's most likely oEmbed under the hood.

The consumer, such as blog editing tool, contacts the content providers following oEmbed specs. Provider then responds back with appropriate html code (or an URL to an image) and the consumer then replaces the original link from user with the response received from the provider. The user (i.e. blog author) does not need to deal with any code.

oEmbed plugin for remarkable-oembed

At the time I didn't find an existing plugin for the remarkable markdown parser that uses oEmbed specs for embedding content. So I decided to implement a plugin ourselves. The plugin adds a new syntax for content authors to provide the URL of the external content. When the markdown document is converted into using remarkable parser, it will retrieve the external content and include it in the html document prepared for publishing.

Going with this approach added extra benefit for Elastic Path:

• Simple and familiar syntax for embedding content without requiring html code to be maintained


• Easy to update if we change our video hosting platform


• Embed other type of media from 3rd party sites  besides video, if needed

The simplest form of the plugin syntax is: `!oembed[alternative text](source url)`. This is very similar to existing/built-in syntax of markdown format for embedding an image. Many platforms support oEmbed specs already. For example, embed code editor from codesandbox.io, audio player from Spotify, video from YouTube or other streaming services, and so on.

If you use markdown format for any type of content publishing, such as docs, blogs, news, announcements, and so on and use the remarkable markdown parser, try out this plugin! Check out the open source plugin repository for installation and usage instructions. A list of supported providers can be found in the repository if you search for the `providers.json` file. 

Feel free to open a pull request if you find any type of provider missing. There are still opportunities for features to be added into this plugin. Help us build those features!

Thank you

Special thanks to some of my colleagues for engaging in the design discussions (shout out to Jake Lin, Damoon Tahmasbi) and many thanks to Allegra Chan for carrying out the implementation.