Obsidian Link Embed

Starting from version 2.0.0, embeds are stored as MarkdownCodeBlockProcessor blocks using the embed language identifier. This format allows for structured metadata storage.

Key fields include:

• title: The title of the linked content.
• image: The URL of the preview image.
• description: A brief description of the content.
• url: The original link URL.
• favicon: The website's favicon URL.
• aspectRatio: Optional parameter to maintain image dimensions.
• metadata: Optional field for custom user data.
• parser: The parser used to generate the embed.
• date: The date of the embed.
• custom_date: A formatted date string.

title: "Example Title"
image: "https://example.com/image.jpg"
description: "This is an example description"
url: "https://example.com"
favicon: "https://example.com/favicon.ico"
aspectRatio: "1.5"
metadata: "Additional custom metadata can be included here"
parser: "local"
date: "2023-04-01"
custom_date: "2023-04-01 13:45:22"

The plugin converts URLs into rich embedded previews. You can trigger the embedding process in several ways:

1. Using the Popup Menu

When pasting a URL, a popup menu may appear (if enabled) with these options:

• Create Embed: Converts the URL into an embedded preview.
• Create Markdown Link: Converts the URL into a standard markdown link [title](url).
• Dismiss: Closes the popup.

2. Using the Command Palette

To manually trigger an embed, ensure the URL is available via one of these methods:

• The URL is currently selected in the editor.
• Your cursor is placed within the URL text.
• The URL is copied to your clipboard.

Then, open the Command Palette and select:

• Link Embed: Embed link

If you want to force a specific parser, use:

• Link Embed: Embed link with ...

3. Auto Embed

If Auto Embed is enabled in settings, the plugin will automatically replace a link with an embed preview when you paste a link into an empty line.

The plugin offers several configuration categories:

Parser Settings

• Default Parser: Set the primary parser. You can also configure a secondary parser to act as a fallback if the primary fails.
• Supported Parsers:
  • Local (Default): Parses HTML directly without an API.
  • JSONLink: Requires an API key.
  • MicroLink: Limited to 50 requests per day.
  • Iframely: Limited to 1000 requests per month.
  • LinkPreview: Requires an API key.

Embed Behavior

• In Place: When enabled, the selected URL is removed and replaced by the embed. When disabled, the embed is inserted on the next line.

Advanced Settings

• Save Images to Vault: Downloads images from embedded links into your vault.
• Image Folder Path: The directory for saved images (default: link-embed-images).
• Respect Aspect Ratio: Preserves original image dimensions.
• Use Cache: Caches favicons and aspect ratios for performance.
• Enable Favicon: Displays website favicons in embeds.
• Max Concurrent Local Parsers: Limits simultaneous local parsing operations to manage system load.
• Metadata: Enables custom information (notes, tags) to be associated with embeds.
• Metadata Template: Customize metadata using variables:
  • {{parser}}: The parser type used.
  • {{date}}: The date.
  • {{#formatDate}}YYYY-MM-DD HH:mm:ss{{/formatDate}}: Custom date formatting.

Markdown Link Favicon Settings

Allows displaying favicons next to standard markdown links:

• Enable Markdown Link Favicon: Shows favicons in Reading and Live Preview modes.
• Favicon Position: Choose to display before or after link text.
• Show on Aliased Links: Toggle for [text](url).
• Show on Plain Links: Toggle for https://url.com.

To add support for new URL types, you must extend the abstract Parser class and implement the process method. The Parser class provides a lifecycle for fetching and processing data.

Lifecycle of a Parse Operation:

1. parse(url): The entry point. It calls parseUrl and then process.
2. parseUrl(url): Fetches raw data from an API using Mustache to render the api template. It supports GET and POST methods.
3. process(data): (Required Implementation) An abstract method where you transform the raw API response into a basic object containing title, image, description, and optionally favicon.
4. handleImageProcessing(...): A built-in utility that automatically handles favicon fetching, image downloading to the vault (if configured), and aspect ratio calculation.

Parser Configuration Properties:

• api: A Mustache template string used to construct the request URL.
• debug: Boolean to enable/disable debug logging.
• location: String used for error reporting (e.g., file:line).
• method: HTTP method (defaults to 'GET').
• headers: A Record<string, string> for request headers.
• body: A string for POST requests. Use {{{url}}} as a placeholder for the target URL.
• vault: Reference to the Obsidian vault.
• saveImagesToVault: Boolean indicating if images should be downloaded locally.
• imageFolderPath: The path within the vault where images will be saved.

export abstract class Parser {
    // ... properties
    abstract process(data: any): {
        title: string;
        image: string;
        description: string;
        favicon?: string;
    };
}

Use the createParser factory function to instantiate a specific parser implementation based on a parserType string. The function handles API key validation for external services and configures image saving settings.

Supported parserType values:

• jsonlink: Requires settings.jsonlinkApiKey.
• microlink: No API key required.
• iframely: Requires settings.iframelyApiKey.
• local: For local file parsing.
• linkpreview: Requires settings.linkpreviewApiKey.

Configuration via settings:

• saveImagesToVault: Boolean (defaults to false).
• imageFolderPath: String (defaults to 'link-embed-images').

Vault Integration: If a vault object is provided, it is assigned to the parser instance to enable local file operations.

import { createParser } from './parsers';

const settings = {
    jsonlinkApiKey: 'YOUR_API_KEY',
    saveImagesToVault: true,
    imageFolderPath: 'my-custom-images'
};

// Create a JSONLink parser
const parser = createParser('jsonlink', settings, myVaultInstance);