# -*- mode: org;  coding: utf-8; -*-

* oEmbed Plugin

#+BEGIN_SRC dokuwiki
---- plugin ----
description: Easily embed media from OEmbed providers.
author     : Dwayne Bent, nik gaffney
email      : nik@fo.am
type       : syntax
lastupdate : 2019-09-01
compatible : Greebo
depends    : 
conflicts  : 
similar    : 
tags       : media, images, video, music, embed

downloadurl: https://github.com/zzkt/dokuwiki-oembed/zipball/master
sourcerepo : https://github.com/zzkt/dokuwiki-oembed/
bugtracker : https://github.com/zzkt/dokuwiki-oembed/issues
donationurl: https://www.sarcoma.org.au/donations

----
#+END_SRC

The oEmbed plugin allows you to easily embed media from any provider that supports the [[https://oembed.com/][oEmbed]] format.

** Install

Search for and install the plugin using the [[plugin:extension][Extension Manager]]. Refer to [[:Plugins]] on how to install plugins manually.

** Syntax 

The simplest way to embed media is with its url. e.g. ~{{>http://example.com/}}~  

Some providers can be given extra options in the form ~{{>url?options}}~ such as ~maxwidth~ or ~maxheight~ 



An oembed provider will specify a URL scheme and API endpoint pairs. If you know the endpoint you can also use the ~!direct~ keyword to send paramaters to the API endpoint

** Examples

Embed a single image from Flickr

~{{>http://www.flickr.com/photos/foam/41018347952}}~~

embed an image with a maximum width of 800px

~{{>http://www.flickr.com/photos/foam/41018347952?maxwidth=800}}~~

embed a gallery

~{{>http://www.flickr.com/photos/flickr/galleries/72157667259442778/}}~~

use the API endpoint directly

~{{>http://www.flickr.com/services/oembed/ !direct ?url=http://www.flickr.com/photos/sdasmarchives/5018415361/}}~

** Further

A list of oembed providers can be found on the [[https://oembed.com/][oEmbed website]] and [[https://noembed.com/][Noembed]] can provide a consitent inferface for supported and unsupoprted site. 

** Known issues

The current plugin (as of 2019) has been updated from an old unmaintained version but doesn't use the new plugin skeleton and may not be fully compatible with current/future versions of dokuwiki.

  - can't resolve https urls for some providers