Satteri Links

🌌 satteri-link-card

satteri-link-card converts a standalone HTTP or HTTPS URL into a metadata-rich card while Markdown is processed.

Experimental: The API, generated HTML, CSS class names, and behavior may change incompatibly between releases.

👨‍🚀 Astro setup

Sätteri is the default Markdown and MDX pipeline in Astro 7. Configure the plugin through @astrojs/markdown-satteri in astro.config.mjs:

import { satteri } from "@astrojs/markdown-satteri";
import { defineConfig } from "astro/config";
import { satteriLinkCard } from "satteri-link-card";

export default defineConfig({
  markdown: {
    processor: satteri({
      hastPlugins: [satteriLinkCard()],
    }),
  },
});

🎨 Styling this demo

The plugin emits class names but does not inject CSS. This page uses the optional preset shipped with the package:

import "satteri-link-card/preset.css";

The preset can be omitted and replaced with site-specific CSS.

✅ Default card

A bare URL must be the only content in a root-level paragraph. The default card shows the resolved title, description, favicon, thumbnail, and hostname when that metadata is available.

Example

https://github.com/ItoShimeji/satteri-links

Output

GitHub - itoshimeji/satteri-links: Link-related plugins for Sätteri.Link-related plugins for Sätteri. Contribute to itoshimeji/satteri-links development by creating an account on GitHub.github.com

⚙️ Hide the thumbnail

Set thumbnail to false. The Markdown input does not change.

Config

satteriLinkCard({
  thumbnail: false,
});

Output

AstroAstro builds fast content sites, powerful web applications, dynamic server APIs, and everything in-between.astro.build

⚙️ Place the thumbnail on the left

Set thumbnail.position to "left".

Config

satteriLinkCard({
  thumbnail: { position: "left" },
});

Output

AstroAstro builds fast content sites, powerful web applications, dynamic server APIs, and everything in-between.astro.build

⚙️ Show the full URL

The default footer shows only the hostname. Set shortenUrl to false to show the complete URL.

Config

satteriLinkCard({
  shortenUrl: false,
});

Output

GitHub - withastro/astro: The web framework for content-driven websites. ⭐️ Star to support our work!The web framework for content-driven websites. ⭐️ Star to support our work! - withastro/astrohttps://github.com/withastro/astro

⚙️ Hide the favicon

Set favicon to false.

Config

satteriLinkCard({
  favicon: false,
});

Output

GitHub - withastro/astro: The web framework for content-driven websites. ⭐️ Star to support our work!The web framework for content-driven websites. ⭐️ Star to support our work! - withastro/astrogithub.com

🚫 Ignore file extensions

Use ignoreExtensions to keep selected file URLs unchanged.

Config

satteriLinkCard({
  ignoreExtensions: [".pdf", ".mp4"],
});

Example

https://example.com/manual.pdf

Output

https://example.com/manual.pdf

❌ Links that are not converted

The plugin intentionally leaves the following input unchanged:

Example

Read the [Astro documentation](https://astro.build/).

- https://astro.build/

https://github.com/ItoShimeji/satteri-links https://astro.build/

Output

Read the Astro documentation.

https://github.com/ItoShimeji/satteri-links https://astro.build/

💾 Caching

Metadata is cached under .cache/satteri-link-card by default. Images remain remote by default. Configure both caches in the plugin definition:

satteriLinkCard({
  metadataCache: {
    directory: ".cache/link-cards",
    maxAge: 30 * 24 * 60 * 60 * 1000,
  },
  imageCache: {
    maxImageBytes: 5 * 1024 * 1024,
    store: createFileSystemImageCacheStore({
      directory: "public/link-cards",
      publicPath: "/link-cards",
    }),
  },
});

Set metadataCache: false to disable metadata caching. Set imageCache: true to use the default filesystem store, or provide a custom ImageCacheStore for another backend.

⚠️ Limitations

Metadata and image requests run in the build environment. Requests to private or local network addresses are not currently blocked. Use the plugin with trusted Markdown.

SVG images are not stored by the initial image cache. The package also does not currently provide offline builds, cache pruning, or concurrency limits across different URLs.