AutoCardLink

Render cardlink code blocks as link preview cards.

Overview

autoCardLinkPlugin() replaces fenced cardlink code blocks with an anchor-style link card (title, description, favicon, host, and an optional image). Styles ship in style.css.

Example post A short summary of the linked page.

example.com

Usage

import { defineConfig } from "@riebeckite/core";
import { autoCardLinkPlugin } from "@riebeckite/plugin-autocardlink";
 
export default defineConfig({
  // ...
  plugins: [autoCardLinkPlugin()],
});

Syntax

```cardlink
url: https://example.com/post
title: "Example post"
description: "A short summary of the linked page."
host: example.com
favicon: https://example.com/favicon.ico
image: https://example.com/og.png
```

Field	Description
`url`	Link target. Required — blocks without `url` are left untouched
`title`	Card title (double quotes optional). Falls back to `url`
`description`	Card description (double quotes optional)
`host`	Host label. Defaults to the `url` hostname; falls back to `url` when the hostname cannot be parsed
`favicon`	Favicon image URL
`image`	Preview image URL. Without it the card uses the no-image layout

title and description may be wrapped in double quotes; escaped quotes (\") inside them are unescaped. url, image, and favicon must use an http(s) or relative URL — unsafe schemes such as javascript: are rejected (the whole block is skipped for url, and the asset is dropped otherwise).

Rendered cards open in a new tab (target="_blank" rel="noopener noreferrer"). The preview image and favicon are lazy-loaded and marked data-lightbox-ignore="true" so they are skipped by @riebeckite/plugin-lightbox.

Each card is a div.rr-cardlink container holding the card link (a.rr-cardlink__card) and a copy button (button.rr-cardlink__copy) that copies the URL to the clipboard. The copy button appears on hover/focus on desktop and is always visible on touch devices. Cards respond to container queries: at narrow widths the description is hidden first, then the preview image.

Options

Option	Type	Default	Description
`className`	`string`	`(none)`	Extra CSS class added to the card root. The `rr-cardlink` hook is always applied

Exports

autoCardLinkPlugin(options?) — plugin factory
remarkAutoCardLink(options?) — remark transform usable on its own
Types: AutoCardLink, AutoCardLinkOptions

Not supported (yet)

The card is built only from the fields written in the fenced block. It does not fetch the target page, so it never derives metadata on its own. In particular:

Local Obsidian image embeds such as [[image.png]] are not resolved; image and favicon accept URLs only.
Wikilinks are not resolved inside favicon or image.
The Obsidian Auto Card Link data-auto-card-link-depth option is not implemented.
Open Graph metadata is not fetched or cached; title, description, and image must be authored explicitly.

History

1 changesCollapseExpand

From To

	1	+ <!-- Generated from packages/plugins/autocardlink/README.md. Do not edit this page directly; edit the package README and run `pnpm docs:sync`. -->
	2	`+`
	3	`+ # AutoCardLink`
	4	`+`
	5	+ Render `cardlink` code blocks as link preview cards.
	6	`+`
	7	`+ [日本語](./autocardlink.md)`
	8	`+`
	9	`+ ## Overview`
	10	`+`
	11	+ `autoCardLinkPlugin()` replaces fenced `cardlink` code blocks with an
	12	`+ anchor-style link card (title, description, favicon, host, and an optional`
	13	+ image). Styles ship in `style.css`.
	14	`+`
	15	+ ```cardlink
	16	`+ url: https://example.com/post`
	17	`+ title: "Example post"`
	18	`+ description: "A short summary of the linked page."`
	19	`+ host: example.com`
	20	`+ favicon: https://example.com/favicon.ico`
	21	`+ image: https://example.com/og.png`
	22	+ ```
	23	`+`
	24	`+ ## Usage`
	25	`+`
	26	+ ```ts
	27	`+ import { defineConfig } from "@riebeckite/core";`
	28	`+ import { autoCardLinkPlugin } from "@riebeckite/plugin-autocardlink";`
	29	`+`
	30	`+ export default defineConfig({`
	31	`+ // ...`
	32	`+ plugins: [autoCardLinkPlugin()],`
	33	`+ });`
	34	+ ```
	35	`+`
	36	`+ ## Syntax`
	37	`+`
	38	+ ````
	39	+ ```cardlink
	40	`+ url: https://example.com/post`
	41	`+ title: "Example post"`
	42	`+ description: "A short summary of the linked page."`
	43	`+ host: example.com`
	44	`+ favicon: https://example.com/favicon.ico`
	45	`+ image: https://example.com/og.png`
	46	+ ```
	47	+ ````
	48	`+`
	49	`+ \| Field \| Description \|`
	50	`+ \| ----- \| ----------- \|`
	51	+ \| `url` \| Link target. Required — blocks without `url` are left untouched \|
	52	+ \| `title` \| Card title (double quotes optional). Falls back to `url` \|
	53	+ \| `description` \| Card description (double quotes optional) \|
	54	+ \| `host` \| Host label. Defaults to the `url` hostname; falls back to `url` when the hostname cannot be parsed \|
	55	+ \| `favicon` \| Favicon image URL \|
	56	+ \| `image` \| Preview image URL. Without it the card uses the no-image layout \|
	57	`+`
	58	+ `title` and `description` may be wrapped in double quotes; escaped quotes
	59	+ (`\"`) inside them are unescaped. `url`, `image`, and `favicon` must use an
	60	+ `http(s)` or relative URL — unsafe schemes such as `javascript:` are rejected
	61	+ (the whole block is skipped for `url`, and the asset is dropped otherwise).
	62	`+`
	63	+ Rendered cards open in a new tab (`target="_blank" rel="noopener
	64	+ noreferrer"`). The preview image and favicon are lazy-loaded and marked
	65	+ `data-lightbox-ignore="true"` so they are skipped by
	66	+ `@riebeckite/plugin-lightbox`.
	67	`+`
	68	+ Each card is a `div.rr-cardlink` container holding the card link
	69	+ (`a.rr-cardlink__card`) and a copy button (`button.rr-cardlink__copy`) that
	70	`+ copies the URL to the clipboard. The copy button appears on hover/focus on`
	71	`+ desktop and is always visible on touch devices. Cards respond to container`
	72	`+ queries: at narrow widths the description is hidden first, then the preview`
	73	`+ image.`
	74	`+`
	75	`+ ## Options`
	76	`+`
	77	`+ \| Option \| Type \| Default \| Description \|`
	78	`+ \| ------ \| ---- \| ------- \| ----------- \|`
	79	+ \| `className` \| `string` \| `(none)` \| Extra CSS class added to the card root. The `rr-cardlink` hook is always applied \|
	80	`+`
	81	`+ ## Exports`
	82	`+`
	83	+ - `autoCardLinkPlugin(options?)` — plugin factory
	84	+ - `remarkAutoCardLink(options?)` — remark transform usable on its own
	85	+ - Types: `AutoCardLink`, `AutoCardLinkOptions`
	86	`+`
	87	`+ ## Not supported (yet)`
	88	`+`
	89	`+ The card is built only from the fields written in the fenced block. It does not`
	90	`+ fetch the target page, so it never derives metadata on its own. In particular:`
	91	`+`
	92	+ - Local Obsidian image embeds such as `[[image.png]]` are not resolved; `image`
	93	+ and `favicon` accept URLs only.
	94	+ - Wikilinks are not resolved inside `favicon` or `image`.
	95	+ - The Obsidian Auto Card Link `data-auto-card-link-depth` option is not
	96	`+ implemented.`
	97	+ - Open Graph metadata is not fetched or cached; `title`, `description`, and
	98	+ `image` must be authored explicitly.
	99	`+`
	100	`+ ## See also`
	101	`+`
	102	`+ - [Plugin guide](../reference/plugin-api.en.md)`
	103	`+`