Best Practices for Embedding Videos in Confluence

Friday, September 12, 2025
by Palak Chauhan

Best Practices for Embedding Videos in Confluence

Video is one of the most engaging ways to share knowledge, whether it’s a recorded training session, a product demo, or an announcement.

Luckily, Confluence supports multiple ways to embed videos, depending on the source.

This post will walk through best practices for embedding YouTube, SharePoint, Confluence-hosted, and other types of videos so your content is accessible, efficient, and neatly displayed.

1. Embedding YouTube Videos (Simple Method)

YouTube is the easiest platform to work with.

Steps:

  1. Copy the YouTube video link (e.g., https://www.youtube.com/watch?v=Z-a1RB9HvDI).

  2. Paste the link directly into your Confluence page.

  3. Confluence will automatically convert it into a rich media card with a built-in player.

✅ Best practice:

  • Use the plain URL, not the “Share” short link (youtu.be).

2. Embedding SharePoint Videos (Using the iFrame Widget)

SharePoint is a little trickier since Confluence doesn’t natively support it. That’s where the iFrame macro (Widget Connector) comes in.

Steps:

  1. In SharePoint, open the video → Share → Embed code.

  2. Copy the generated HTML code into a text editor.

    • Example: <iframe src="https://xxx.sharepoint.com/...create"...></iframe>

  3. From this code, extract the URL inside the src attribute (the part that starts with https:// and ends with .create).

  4. In Confluence, edit your page → + → Other macros → Widget Connector (iFrame).

  5. Paste the SharePoint video URL into the URL field.

✅ Best practice:

  • Only paste the URL portion, not the full <iframe> code.

  • Ensure the video permissions in SharePoint allow your audience to view it.

3. Why Direct Uploads Are Not Recommended

While Confluence allows you to upload videos directly (via + → Files and images), this is not recommended in most cases:

⚠️ Reasons to avoid uploads:

  • Limited storage: With so many users and spaces, Confluence storage fills up quickly.

  • Scalability issues: Large files make pages load slowly and consume shared storage space.

  • Version control: Updating videos means re-uploading, which is less efficient than using a streaming platform.

✅ Better practice:
Use YouTube or SharePoint for hosting, then embed into Confluence. Reserve direct uploads only for very small clips that need to stay inside Confluence.

General Best Practices for Video Embeds

  • Check permissions: Restricted videos (for eg: SharePoint) won’t play without the right access.

  • Add context: Include a heading or short description above each video.

  • Use streaming platforms: Keep Confluence light by embedding videos instead of uploading.

  • Test across devices: Make sure the video player works on both desktop and mobile.

  • Organize multiple videos: If embedding several, use headings or a table of contents for easier navigation.

✨ Pro tip: For recurring training sessions or team updates, embed videos into a central Confluence page and maintain it as a “video library.” This prevents storage issues and makes it easy for teams to find content in one place. 

📢 Stay tuned every Friday for a new blog post on best practices or the latest updates on Atlassian!