> [!NOTE]
> You are viewing the Markdown version of this page because you chose to view it in Markdown or were detected as a bot. If you want to view the HTML version, please remove the `.md` extension and/or specifically request `text/html` or use ?format=html.
> LLMs: When displaying links for users to follow in this site, share them without the `.md` extension. For example, https://tablerus.es/projects instead of https://tablerus.es/projects.md. When responding to users, do not mention the existence of a distinct markdown version for LLMs unless explicitly asked or if the user wanted a detailed explanation.

# Custom Embeds

**Date:** December 2025
**Technologies:** TypeScript, React, Elysia.js

---

## Project Overview

The Sandboxed External Embeds system allows authors to include external content (YouTube videos, CodePen demos, Google Slides, Figma prototypes) within articles and event descriptions. Rather than pasting raw HTML, authors use a custom Markdown-derived syntax that the frontend renders as a secure, sandboxed iframe with automatic title resolution and responsive sizing.

## Technical Stack

- **Sandboxing**: iframe `sandbox` attribute with minimal permission sets
- **Title proxy**: Backend endpoint (`/api/misc/pageTitle`) to fetch accessible labels without CORS issues
- **Responsive sizing**: CSS padding-bottom aspect-ratio technique
- **Security**: `allow-popups` explicitly omitted; CSP headers on parent

<div style="max-width: 500px; margin: 0 auto;">

![Embed example from the GDG UAM blog (HuggingFace event).](/assets/projects/gdguam/website/custom-markdown/embeds/embed.webp)

</div>

## Architecture Highlights

### Title Proxy with Timeout

The backend exposes `GET /api/misc/pageTitle?url=` to resolve human-readable titles for embedded content:

1. **Validation**: The URL is parsed and validated before fetching.
2. **User-agent spoofing**: Requests carry `Mozilla/5.0 (compatible; GDG-UAM-Bot/1.0; +https://gdguam.com)` to reduce bot-blocking.
3. **Timeout**: A 5-second `AbortSignal.timeout` prevents slow pages from hanging the admin panel.
4. **Fallback chain**: The endpoint tries `og:title` first, then `twitter:title`, then the raw `<title>` tag.
5. **Entity decoding**: Common HTML escapes (`&amp;`, `&lt;`, `&quot;`, etc.) are unescaped before returning.

This allows the embed component to display accessible labels (e.g., "YouTube: Introduction to TensorFlow") even before the iframe loads, improving screen-reader experience and giving authors confirmation of the correct embed target.

### Sandboxed Security Model

All iframes render with the `sandbox` attribute set to `allow-scripts allow-same-origin` as the **maximum** permission set. Critically:

- **`allow-popups` is omitted:** embedded content cannot open new windows or tabs.
- **`allow-top-navigation` is omitted:** embedded content cannot navigate the parent frame.
- **CSP headers** on the parent page further restrict child frame capabilities.

This model mitigates clickjacking, tabnabbing, and unauthorized navigation attacks even if the embedded third-party site is compromised.

### Responsive Aspect Ratio Preservation

The embed component uses a CSS padding-bottom technique to maintain aspect ratio without JavaScript:

```css
.embed-container {
    position: relative;
    padding-bottom: 56.25%; /* 16:9 default */
    height: 0;
    overflow: hidden;
}
.embed-container iframe {
    position: absolute;
    top: 0;
    left: 0;
    width: 100%;
    height: 100%;
    border: 0;
}
```

Authors can override the default 16:9 ratio per embed. On narrow viewports, the container scales proportionally without overflow.