Build your personal knowledge base with Trilium Notes
TypeScript electronelectron-appknowledge-baseknowledge-graphknowledge-managementknowledge-management-graphlocal-firstnote-managmentnote-takernote-takingnotebooknotesnotes-apppersonal-knowledge-basepersonal-wikiscriptableself-hostedself-hostingwiki
import {
extractYouTubeVideoId, safeHostname, safeLinkPreviewHref, safeLinkPreviewImageSrc
} from "./link_embed.js";
import { escapeHtml } from "./utils.js";
/** A link preview as the note stores it, in the `data-*` attributes of its element. */
export interface LinkPreviewData {
url: string;
/** `opengraph` draws a card; anything else draws a video player when the URL is a video. */
embedType?: string | null;
title?: string | null;
description?: string | null;
image?: string | null;
favicon?: string | null;
siteName?: string | null;
/** The shape of a video, as its width and height in whole numbers, such as `9/16`. */
aspectRatio?: string | null;
}
export interface LinkPreviewMarkupOptions {
/** In the editor a link opens on a double click, so it carries no `target`. */
editable?: boolean;
/** The accessible name of a video's play button, translated by the caller. */
playVideoLabel: string;
}
/** The `data-*` attribute that stores each field of a link preview. */
export const LINK_PREVIEW_DATA_ATTRIBUTES = {
url: "data-url",
embedType: "data-embed-type",
title: "data-title",
description: "data-description",
image: "data-image",
favicon: "data-favicon",
siteName: "data-site-name",
aspectRatio: "data-aspect-ratio"
} as const satisfies Record<keyof LinkPreviewData, string>;
/** The custom property that gives the player of a video, and its box, the shape of the video. */
export const VIDEO_ASPECT_RATIO_PROPERTY = "--video-aspect-ratio";
/**
* The preview stored on a `section.link-embed` or `span.link-mention`, or `null` when it carries no
* URL. A missing embed type reads as `opengraph`.
*/
export function readLinkPreviewData(getAttribute: (name: string) => string | null | undefined) {
const attributes = LINK_PREVIEW_DATA_ATTRIBUTES;
const url = getAttribute(attributes.url);
if (!url) {
return null;
}
return {
url,
embedType: getAttribute(attributes.embedType) || "opengraph",
title: getAttribute(attributes.title),
description: getAttribute(attributes.description),
image: getAttribute(attributes.image),
favicon: getAttribute(attributes.favicon),
siteName: getAttribute(attributes.siteName),
aspectRatio: getAttribute(attributes.aspectRatio)
} satisfies LinkPreviewData;
}
/**
* The width of the video of `preview` divided by its height, or `null` when the preview stores
* no valid shape, as a video inserted before Trilium read the shape does. Its player is 16:9.
*/
export function getVideoAspectRatio({ aspectRatio }: Pick<LinkPreviewData, "aspectRatio">) {
const [ width, height ] = aspectRatio?.match(/^(\d{1,4})\/(\d{1,4})$/)?.slice(1).map(Number)
?? [];
return width && height ? width / height : null;
}
/** The box sizes of a video embed. */
export const VIDEO_EMBED_BOX_SIZES = [ "medium", "full" ] as const;
/**
* The box size of a video saved as a link preview, and whether its title is hidden. A video saved
* before videos were embeds has no box size: it is Full and untitled.
*/
export function readVideoEmbedBox(getAttribute: (name: string) => string | null | undefined) {
const savedBoxSize = getAttribute("data-box-size");
const boxSize = VIDEO_EMBED_BOX_SIZES.find((size) => size === savedBoxSize) ?? "full";
return {
boxSize,
isTitleHidden: !savedBoxSize || getAttribute("data-hide-title") === "true"
};
}
/** The YouTube ID of the video that a link preview plays, or `null` for a card. */
export function getLinkPreviewVideoId(
{ url, embedType }: Pick<LinkPreviewData, "url" | "embedType">
) {
return embedType !== "opengraph" ? extractYouTubeVideoId(url) : null;
}
/**
* The markup of an inline link mention: the site's favicon and the page title, or the host when
* the note stores no title.
*/
export function renderLinkMentionHtml(data: LinkPreviewData, options: LinkPreviewMarkupOptions) {
return `<a class="link-embed-mention" href="${escapeHtml(safeLinkPreviewHref(data.url))}"`
+ `${targetAttribute(options)} rel="noopener noreferrer">`
+ renderFavicon(data.favicon)
+ `<span class="link-embed-mention-title">`
+ `${escapeHtml(data.title || safeHostname(data.url))}</span>`
+ `</a>`;
}
/**
* The markup of a block link preview: a video player for a video URL, a card otherwise.
*
* The player starts as a facade showing the thumbnail stored in the note, so reading a note or a
* shared page that holds a video does not contact YouTube; `enhanceLinkPreviews()` swaps in the
* player on the reader's click.
*/
export function renderLinkEmbedHtml(data: LinkPreviewData, options: LinkPreviewMarkupOptions) {
const videoId = getLinkPreviewVideoId(data);
if (videoId) {
const label = escapeHtml(options.playVideoLabel);
const aspectRatio = getVideoAspectRatio(data);
const style = aspectRatio ? ` style="${VIDEO_ASPECT_RATIO_PROPERTY}:${aspectRatio}"` : "";
return `<div class="link-embed-video"${style}>`
+ `<button type="button" class="link-embed-video-facade"`
+ ` data-video-id="${escapeHtml(videoId)}"`
+ ` aria-label="${label}" title="${label}">`
+ renderPicture(data.image, "link-embed-video-thumbnail")
+ `<span class="link-embed-video-play" aria-hidden="true"></span>`
+ `</button></div>`;
}
const cardImage = renderPicture(data.image, "link-embed-card-image")
|| LINK_EMBED_CARD_IMAGE_PLACEHOLDER;
const title = data.title
? `<div class="link-embed-card-title">${escapeHtml(data.title)}</div>`
: "";
const description = data.description
? `<div class="link-embed-card-description">${escapeHtml(data.description)}</div>`
: "";
return `<a class="link-embed-card" href="${escapeHtml(safeLinkPreviewHref(data.url))}"`
+ `${targetAttribute(options)} rel="noopener noreferrer">`
// The wrapper gives the card's left column its size, so a card without a picture keeps
// the shape of one with it.
+ `<div class="link-embed-card-image-wrapper">${cardImage}</div>`
+ `<div class="link-embed-card-content">${title}${description}`
+ `<div class="link-embed-card-url">${renderFavicon(data.favicon)}`
+ `<span>${escapeHtml(data.siteName || safeHostname(data.url))}</span></div>`
+ `</div></a>`;
}
/** What stands in for a card's missing or broken cover image. */
export const LINK_EMBED_CARD_IMAGE_PLACEHOLDER =
`<div class="link-embed-card-image-placeholder">🔗</div>`;
function targetAttribute({ editable }: LinkPreviewMarkupOptions) {
return editable ? "" : ` target="_blank"`;
}
/**
* A missing favicon draws nothing: unlike a card's cover there is no hole to fill, and anything
* drawn in its place reads as a mark of its own.
*/
function renderFavicon(src: string | null | undefined) {
return renderPicture(src, "link-embed-mention-favicon", 16);
}
/**
* One of a preview's pictures, or an empty string when the note stores none the page may load.
* `safeLinkPreviewImageSrc()` allows only an inline image or an attachment of this instance, so
* opening a note never makes a request to a third party.
*/
function renderPicture(src: string | null | undefined, className: string, size?: number) {
const safeSrc = safeLinkPreviewImageSrc(src);
if (!safeSrc) {
return "";
}
const sizeAttributes = size ? ` width="${size}" height="${size}"` : "";
return `<img class="${className}" src="${escapeHtml(safeSrc)}" alt="" loading="lazy"`
+ ` draggable="false"${sizeAttributes}>`;
}