@fsegurai/marked-extended-embeds 17.0.0-beta.0

package/README.custom.md

@@ -0,0 +1,641 @@
+<!-- SECTION:CUSTOM_INTRO -->
+---
+
+This extension enables seamless integration of external content with automatic platform detection, responsive layouts,
+privacy controls, and extensive customization options. Perfect for documentation, blogs, portfolios, and educational
+content.
+
+<!-- SECTION:CUSTOM_TOC_USAGE -->
+
+	- [Supported Platforms](#supported-platforms)
+
+- [Configuration Options](#configuration-options)
+    - [Embed Properties](#embed-properties)
+    - [Advanced Examples](#advanced-examples)
+
+<!-- SECTION:CUSTOM_BASIC_USAGE -->
+**The extension automatically detects the platform from URLs or accepts explicit `provider` specification.**
+
+<!-- SECTION:CUSTOM_USAGE_EXAMPLE -->
+const markdown = `
+::::embed{title="My Video" aspectRatio="16:9"}
+https://www.youtube.com/watch?v=dQw4w9WgXcQ
+::::embedend
+
+::::embed{provider="codepen" theme="dark"}
+https://codepen.io/username/pen/abc123
+::::embedend
+
+::::embed{title="Spotify Playlist"}
+https://open.spotify.com/playlist/37i9dQZF1DXcBWIGoYBM5M
+::::embedend
+`;
+
+marked.parse(markdown);
+
+<!-- SECTION:CUSTOM_USAGE_NOTES -->
+The extension automatically detects providers, applies responsive layouts with proper aspect ratios, and includes
+accessibility features. All embeds support lazy loading, sandbox security, and customizable styling.
+
+### Styling Your Embeds
+
+This extension follows a **separation of concerns** approach, injecting only minimal structural CSS. Visual styling is completely separated for maximum flexibility.
+
+#### Generated HTML Structure
+
+```html
+
+<div class="marked-extended-embed-container"
+     data-provider="youtube"
+     data-embed-id="dQw4w9WgXcQ">
+    <!-- Loading state -->
+    <div class="marked-extended-embed-loading">
+        <div class="marked-extended-embed-spinner"></div>
+        <p>Loading...</p>
+    </div>
+  
+    <!-- Embedded content (iframe) -->
+    <iframe
+            src="https://www.youtube.com/embed/dQw4w9WgXcQ"
+            loading="lazy"
+            sandbox="allow-scripts allow-same-origin"
+            allowfullscreen>
+    </iframe>
+
+    <!-- Optional caption -->
+    <div class="marked-extended-embed-caption">
+        Video description
+    </div>
+</div>
+```
+
+#### CSS Classes Reference
+
+| Class | Purpose | Element |
+|-------|---------|---------|
+| `.marked-extended-embed-container` | Main wrapper | Container |
+| `.marked-extended-embed-container[data-provider="youtube"]` | Provider-specific styling | Container |
+| `.marked-extended-embed-loading` | Loading state overlay | Loading div |
+| `.marked-extended-embed-spinner` | Loading spinner animation | Spinner div |
+| `.marked-extended-embed-loading-text` | "Loading..." text | Text element |
+| `.marked-extended-embed-caption` | Caption/description | Caption div |
+| `iframe` | Embedded content | Iframe |
+
+#### Complete Styling Example
+
+```css
+/* Base Container */
+.marked-extended-embed-container {
+  position: relative;
+  width: 100%;
+  margin: 1.5rem 0;
+  border-radius: 8px;
+  overflow: hidden;
+  background: #f5f5f5;
+  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
+}
+
+/* Responsive aspect ratio wrapper */
+.marked-extended-embed-container::before {
+  content: '';
+  display: block;
+  padding-top: 56.25%; /* 16:9 aspect ratio */
+}
+
+.marked-extended-embed-container iframe {
+  position: absolute;
+  top: 0;
+  left: 0;
+  width: 100%;
+  height: 100%;
+  border: none;
+}
+
+/* Loading State */
+.marked-extended-embed-loading {
+  position: absolute;
+  top: 0;
+  left: 0;
+  width: 100%;
+  height: 100%;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  background: rgba(0, 0, 0, 0.05);
+  z-index: 1;
+}
+
+.marked-extended-embed-spinner {
+  width: 40px;
+  height: 40px;
+  border: 4px solid #e0e0e0;
+  border-top-color: #2196F3;
+  border-radius: 50%;
+  animation: spin 1s linear infinite;
+}
+
+@keyframes spin {
+  0% { transform: rotate(0deg); }
+  100% { transform: rotate(360deg); }
+}
+
+.marked-extended-embed-loading-text {
+  margin-top: 1rem;
+  font-size: 0.875rem;
+  font-weight: 500;
+  color: #666;
+}
+
+/* Caption Styling */
+.marked-extended-embed-caption {
+  padding: 0.75rem 1rem;
+  font-size: 0.875rem;
+  color: #666;
+  background: #fafafa;
+  border-top: 1px solid #e0e0e0;
+  text-align: center;
+}
+
+/* Provider-Specific Backgrounds */
+.marked-extended-embed-container[data-provider="youtube"] {
+  background: #000;
+}
+
+.marked-extended-embed-container[data-provider="vimeo"] {
+  background: #000;
+}
+
+.marked-extended-embed-container[data-provider="codepen"] {
+  background: #1e1e1e;
+}
+
+.marked-extended-embed-container[data-provider="codesandbox"] {
+  background: #151515;
+}
+
+.marked-extended-embed-container[data-provider="spotify"] {
+  background: #191414;
+}
+
+.marked-extended-embed-container[data-provider="soundcloud"] {
+  background: #ff5500;
+}
+
+.marked-extended-embed-container[data-provider="twitter"] {
+  background: #fff;
+}
+
+.marked-extended-embed-container[data-provider="github-gist"] {
+  background: #f6f8fa;
+}
+
+.marked-extended-embed-container[data-provider="figma"] {
+  background: #fff;
+}
+
+.marked-extended-embed-container[data-provider="mermaid"] {
+  background: #fff;
+  padding: 1rem;
+}
+
+.marked-extended-embed-container[data-provider="pdf"] {
+  background: #525659;
+}
+
+.marked-extended-embed-container[data-provider="loom"] {
+  background: #000;
+}
+
+.marked-extended-embed-container[data-provider="miro"] {
+  background: #fff;
+}
+
+.marked-extended-embed-container[data-provider="excalidraw"] {
+  background: #fff;
+}
+
+.marked-extended-embed-container[data-provider="drawio"],
+.marked-extended-embed-container[data-provider="diagrams-net"] {
+  background: #fff;
+}
+```
+
+#### Dark Mode Support
+
+```css
+/* Light theme */
+body.light .marked-extended-embed-container {
+  background: #f5f5f5;
+  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
+}
+
+body.light .marked-extended-embed-caption {
+  background: #fafafa;
+  color: #666;
+  border-top-color: #e0e0e0;
+}
+
+body.light .marked-extended-embed-loading {
+  color: #666;
+}
+
+body.light .marked-extended-embed-spinner {
+  border-color: #e0e0e0;
+  border-top-color: #2196F3;
+}
+
+/* Dark theme */
+body.dark .marked-extended-embed-container {
+  background: #1e1e1e;
+  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.3);
+}
+
+body.dark .marked-extended-embed-caption {
+  background: #2a2a2a;
+  color: #e0e0e0;
+  border-top-color: #3a3a3a;
+}
+
+body.dark .marked-extended-embed-loading {
+  color: #ccc;
+}
+
+body.dark .marked-extended-embed-spinner {
+  border-color: #333;
+  border-top-color: #2196F3;
+}
+
+/* Provider-specific dark mode overrides */
+body.dark .marked-extended-embed-container[data-provider="mermaid"],
+body.dark .marked-extended-embed-container[data-provider="twitter"],
+body.dark .marked-extended-embed-container[data-provider="figma"],
+body.dark .marked-extended-embed-container[data-provider="miro"],
+body.dark .marked-extended-embed-container[data-provider="excalidraw"],
+body.dark .marked-extended-embed-container[data-provider="drawio"],
+body.dark .marked-extended-embed-container[data-provider="diagrams-net"] {
+  background: #1e1e1e;
+}
+
+body.dark .marked-extended-embed-container[data-provider="github-gist"] {
+  background: #0d1117;
+}
+```
+
+#### Custom Aspect Ratios
+
+```css
+/* 16:9 (default - videos) */
+.marked-extended-embed-container[data-provider="youtube"]::before,
+.marked-extended-embed-container[data-provider="vimeo"]::before,
+.marked-extended-embed-container[data-provider="loom"]::before {
+  padding-top: 56.25%;
+}
+
+/* 1:1 (square - music players) */
+.marked-extended-embed-container[data-provider="spotify"]::before,
+.marked-extended-embed-container[data-provider="soundcloud"]::before {
+  padding-top: 100%;
+}
+
+/* 4:3 (presentations) */
+.marked-extended-embed-container[data-provider="google-slides"]::before {
+  padding-top: 75%;
+}
+
+/* Full height (code editors) */
+.marked-extended-embed-container[data-provider="codepen"]::before,
+.marked-extended-embed-container[data-provider="codesandbox"]::before,
+.marked-extended-embed-container[data-provider="replit"]::before {
+  padding-top: 100%;
+  min-height: 500px;
+}
+```
+
+#### Responsive Adjustments
+
+```css
+@media (max-width: 768px) {
+  .marked-extended-embed-container {
+    margin: 1rem 0;
+    border-radius: 4px;
+  }
+
+  .marked-extended-embed-caption {
+    padding: 0.5rem 0.75rem;
+    font-size: 0.8125rem;
+  }
+
+  /* Reduce height for code editors on mobile */
+  .marked-extended-embed-container[data-provider="codepen"]::before,
+  .marked-extended-embed-container[data-provider="codesandbox"]::before {
+    min-height: 400px;
+  }
+}
+```
+
+#### Print Styles
+
+```css
+@media print {
+  .marked-extended-embed-container {
+    break-inside: avoid;
+    box-shadow: none;
+    border: 1px solid #ccc;
+  }
+
+  .marked-extended-embed-loading {
+    display: none;
+  }
+
+  /* Show caption */
+  .marked-extended-embed-caption {
+    display: block !important;
+  }
+
+  /* Hide interactive embeds, show placeholder */
+  .marked-extended-embed-container iframe {
+    display: none;
+  }
+
+  .marked-extended-embed-container::after {
+    content: "Embedded content: " attr(data-provider);
+    display: block;
+    padding: 2rem;
+    text-align: center;
+    color: #666;
+    font-style: italic;
+  }
+}
+```
+
+#### Copy Demo Theme
+
+For complete styling with all 18+ providers: [embed-theme.css](https://github.com/fsegurai/marked-extensions/blob/main/demo/styles/extensions/embed-theme.css)
+
+Check the [demo](https://fsegurai.github.io/marked-extensions) to see all embed types in action.
+
+<!-- SECTION:CUSTOM_SECTIONS -->
+
+### Supported Platforms
+
+The extension supports **18 different platforms** with automatic URL detection:
+
+| Platform         | Type          | Example URL                   |
+|------------------|---------------|-------------------------------|
+| **YouTube**      | Video         | `youtube.com/watch?v=...`     |
+| **Vimeo**        | Video         | `vimeo.com/123456789`         |
+| **CodePen**      | Code          | `codepen.io/user/pen/abc`     |
+| **CodeSandbox**  | Code          | `codesandbox.io/s/abc`        |
+| **Twitter**      | Social        | `twitter.com/user/status/123` |
+| **GitHub Gist**  | Code          | `gist.github.com/user/abc`    |
+| **Spotify**      | Music         | `open.spotify.com/track/abc`  |
+| **SoundCloud**   | Music         | `soundcloud.com/user/track`   |
+| **SlideShare**   | Presentation  | `slideshare.net/user/slides`  |
+| **Figma**        | Design        | `figma.com/file/abc`          |
+| **Loom**         | Video         | `loom.com/share/abc`          |
+| **Miro**         | Collaboration | `miro.com/app/board/abc`      |
+| **Mermaid**      | Diagram       | `mermaid://graph TD; A-->B;`  |
+| **Excalidraw**   | Drawing       | `excalidraw.com/#room=abc`    |
+| **Draw.io**      | Diagram       | `diagrams.net/...`            |
+| **Diagrams.net** | Diagram       | `diagrams.net/...`            |
+| **PDF**          | Document      | Any PDF URL                   |
+| **iframe**       | Generic       | Any URL                       |
+
+Each platform is automatically detected from the URL pattern. You can also explicitly specify the provider using the
+`provider` property.
+
+## Configuration Options
+
+The marked-extended-embeds extension accepts the following configuration options:
+
+- `className`: The base CSS class name for embeds. Defaults to 'marked-extended-embed.'
+- `prefixId`: The prefix ID for embed elements. Defaults to 'embed'.
+- `defaultAspectRatio`: Default aspect ratio ('16:9', '4:3', '1:1', '21:9'). Defaults to '16:9'.
+- `allowFullscreen`: Allow fullscreen mode for embeds. Defaults to true.
+- `lazyLoad`: Enable lazy loading for better performance. Defaults to true.
+- `privacyMode`: Use privacy-enhanced domains when available. Defaults to false.
+- `template`: Custom HTML template for rendering embeds. Defaults to built-in template.
+- `customizeToken`: Function to customize embed tokens. Defaults to null.
+- `injectStyles`: Whether to inject default styles. Defaults to true.
+- `enableSandbox`: Enable iframe sandbox for security. Defaults to true.
+- `sandboxPermissions`: Array of sandbox permissions. Defaults
+  to ['allow-scripts', 'allow-same-origin', 'allow-popups', 'allow-presentation'].
+- `providers`: Custom provider configurations. Defaults to {}.
+- `onEmbedLoad`: Callback when embed loads. Defaults to null.
+- `onEmbedError`: Callback when embed fails. Defaults to null.
+
+### Embed Properties
+
+Embed syntax supports the following properties:
+
+**Common Properties:**
+
+- `title`: Title/caption for the embed
+- `aspectRatio`: Aspect ratio ('16:9', '4:3', '1:1', '21:9', 'custom')
+- `width`: Custom width (e.g., '800px')
+- `height`: Custom height (e.g., '600px')
+- `provider`: Explicit provider name
+- `id`: Custom identifier for the embed
+- `className`: Custom CSS class
+
+**Media Properties:**
+
+- `autoplay`: Auto-play video/audio (boolean)
+- `muted`: Start muted (boolean)
+- `loop`: Loop playback (boolean)
+- `startTime`: Start time for videos (e.g., '30')
+- `controls`: Show media controls (boolean)
+
+**Display Properties:**
+
+- `lazyLoad`: Enable lazy loading (boolean)
+- `allowFullscreen`: Allow fullscreen mode (boolean)
+- `privacyMode`: Use privacy-enhanced mode (boolean)
+- `theme`: Theme setting ('light', 'dark')
+
+**Custom Parameters:**
+
+- `param-*`: Any property starting with 'param-' becomes a URL parameter
+
+### Advanced Examples
+
+#### YouTube Video with Options
+
+```markdown
+::::embed{
+title="Tutorial Video"
+aspectRatio="16:9"
+autoplay="true"
+muted="true"
+startTime="30"
+privacyMode="true"
+}
+https://www.youtube.com/watch?v=dQw4w9WgXcQ
+::::embedend
+```
+
+#### CodePen with Dark Theme
+
+```markdown
+::::embed{title="Interactive Demo" theme="dark"}
+https://codepen.io/username/pen/abc123
+::::embedend
+```
+
+#### Responsive Design File
+
+```markdown
+::::embed{
+title="Mobile App Design"
+aspectRatio="4:3"
+width="100%"
+}
+https://www.figma.com/file/abc123/Mobile-App
+::::embedend
+```
+
+#### Spotify Playlist
+
+```markdown
+::::embed{title="Coding Playlist" aspectRatio="1:1"}
+https://open.spotify.com/playlist/37i9dQZF1DXcBWIGoYBM5M
+::::embedend
+```
+
+#### CodeSandbox Project
+
+```markdown
+::::embed{
+title="React Example"
+theme="dark"
+param-view="preview"
+}
+https://codesandbox.io/s/react-new
+::::embedend
+```
+
+#### Mermaid Diagram
+
+```markdown
+::::embed{provider="mermaid" title="System Architecture"}
+mermaid://graph TD;
+A[Client] -->|Request| B[API Gateway];
+B --> C[Service 1];
+B --> D[Service 2];
+C --> E[Database];
+D --> E;
+::::embedend
+```
+
+#### PDF Document
+
+```markdown
+::::embed{
+provider="pdf"
+title="Technical Specification"
+aspectRatio="4:3"
+}
+https://example.com/document.pdf
+::::embedend
+```
+
+#### Loom Video with Custom Size
+
+```markdown
+::::embed{
+title="Product Demo"
+width="800px"
+height="450px"
+}
+https://www.loom.com/share/abc123
+::::embedend
+```
+
+#### Twitter Thread
+
+```markdown
+::::embed{title="Latest Announcement"}
+https://twitter.com/username/status/1234567890
+::::embedend
+```
+
+#### GitHub Gist
+
+```markdown
+::::embed{title="Code Snippet"}
+https://gist.github.com/username/abc123
+::::embedend
+```
+
+#### Excalidraw Sketch
+
+```markdown
+::::embed{title="Whiteboard Sketch" aspectRatio="16:9"}
+https://excalidraw.com/#room=abc123,def456
+::::embedend
+```
+
+#### Draw.io Diagram
+
+```markdown
+::::embed{provider="drawio" title="System Architecture" aspectRatio="4:3"}
+https://viewer.diagrams.net/?highlight=0000ff&edit=_blank&title=diagram
+::::embedend
+```
+
+## Privacy Mode
+
+Enable privacy-enhanced embedding for supported platforms:
+
+```markdown
+::::embed{privacyMode="true"}
+https://www.youtube.com/watch?v=abc123
+::::embedend
+```
+
+This uses `youtube-nocookie.com` for YouTube and similar privacy-focused domains when available.
+
+## Custom Provider Configuration
+
+Configure provider-specific settings:
+
+```javascript
+marked.use(markedExtendedEmbeds({
+    providers: {
+        youtube: {
+            domain: 'www.youtube-nocookie.com',
+            params: {
+                rel: '0',
+                modestbranding: '1',
+            },
+        },
+        spotify: {
+            params: {
+                theme: '0',
+            },
+        },
+    },
+}));
+```
+
+## Security Features
+
+The extension includes several security features:
+
+- **Sandbox by default**: Iframes use sandbox attribute with restricted permissions
+- **Configurable permissions**: Customize allowed iframe capabilities
+- **Privacy mode**: Use no-cookie domains when available
+- **XSS protection**: All user input is escaped
+- **HTTPS enforcement**: Embed URLs use secure protocols
+
+## Accessibility
+
+All embeds include proper accessibility features:
+
+- Semantic HTML with proper roles
+- Alt text and titles
+- Keyboard navigation support
+- Screen reader compatibility
+- Loading states with aria-labels
+