Auto Embed

Paste a plain YouTube, Vimeo, X (Twitter), or Instagram link on its own line in a page's Markdown, and this plugin turns it into a live embedded player/post — no shortcode, no copy-pasting iframe/embed code by hand.

Check out this talk:

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

More thoughts on this over on X:

https://x.com/someuser/status/1234567890123456789

Both links above render as full embeds on the live page. A link that sits inside a sentence, or on the same line as other text, is left completely alone — it stays a normal clickable link. Only a URL that is the sole content of its own paragraph gets converted.

Supported sites

• YouTube — youtube.com/watch?v=..., youtu.be/..., youtube.com/shorts/...
• Vimeo — vimeo.com/...
• X / Twitter — any .../status/... link on x.com or twitter.com
• Instagram — instagram.com/p/..., /reel/..., /tv/...

Each one can be switched on/off independently in the plugin settings.

How it works

No API keys, no oEmbed calls, no rate limits:

• YouTube and Vimeo become a responsive <iframe> player, wrapped in a 16:9 container that scales with your page width (this can be turned off in settings if your theme already handles responsive iframes).
• X/Twitter and Instagram become the platforms' own official <blockquote> embed markup, and the plugin automatically loads their widget script (platform.twitter.com/widgets.js / instagram.com/embed.js) on any page that actually uses one — never on pages that don't.

Because it hooks into onPageContentProcessed, the conversion happens once per page (as part of Grav's normal content caching), not on every request.

Install

git clone forgejo@code.hall.me.uk:david/autoembed.git user/plugins/autoembed

Or copy this whole folder into your Grav install so the folder structure looks like:

your-site/
  user/
    plugins/
      autoembed/
        autoembed.php
        autoembed.yaml
        blueprints.yaml
        assets/
          autoembed.css

Then enable it either in user/config/plugins/autoembed.yaml (enabled: true, which is the default) or from Admin2's Plugins list.

No further setup needed — it works immediately for any page whose Markdown is processed by Grav.

Configuration

Copy user/plugins/autoembed/autoembed.yaml to user/config/plugins/autoembed.yaml to override the defaults, or use the Admin panel form:

Option	Default	Description
enabled	true	Master on/off switch
responsive	true	Wrap YouTube/Vimeo iframes in a scaling 16:9 container
youtube.enabled	true	Enable YouTube embeds
youtube.privacy_enhanced	true	Serve the YouTube player from youtube-nocookie.com
vimeo.enabled	true	Enable Vimeo embeds
twitter.enabled	true	Enable X/Twitter embeds
instagram.enabled	true	Enable Instagram embeds

Notes and limitations

• This only runs on the live/front-end render, not inside the Admin page editor's preview pane, so you won't see the embed while editing — only once you view the actual page.
• X and Instagram embeds need JavaScript and a live internet connection for the visitor's browser to render (they load the provider's widget script, which then fills in the blockquote). If a post is deleted or made private, the blockquote will show a plain "View on X/Instagram" fallback link instead, same as on any other site using these official widgets.
• Cookies/privacy: the X and Instagram widget scripts are third-party scripts from those platforms and may set their own cookies once loaded. If your site needs cookie-consent gating, you'll want to load those scripts through your consent-management plugin instead of (or in addition to) this one. YouTube's "privacy-enhanced" mode already avoids this for video embeds.
• A URL that doesn't match any of the four supported providers is left as an ordinary link — nothing else on the page is touched.

Extending

To add another provider (e.g. TikTok, Facebook), add a new preg_match branch in replaceLink() in autoembed.php following the same pattern as the existing ones, plus a corresponding toggle in autoembed.yaml and blueprints.yaml.

Licence

MIT.