前言#

在日常博客推文当中，不仅仅是 GitHub 存储库，还有很多的外部链接会常常引用。在Fuwari中，原生使用了 GithubCardComponent 这个组件来调用 Github 存储库，这是远远不够的，所以我参考了 @Hasenpfote 佬的 PR 来添加链接卡片来引用外部链接

示例#

1
在 Markdown 的段落中仅包含一个“裸链接”（没有描述性文字的链接）或类似内容
2
它将自动转换为链接卡片
3

4
**外部链接**
5

6
https://astro.build/
7

8
<https://music.163.com/>
9

10

11
**内部链接**
12

13
[/posts/fuwari/](/posts/fuwari/)
14

15

16
**国际化域名 (Internationalized Domain Name)**
17

18
https://はじめよう.みんな/

Astro

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

astro.build

网易云音乐

网易云音乐是一款专注于发现与分享的音乐产品，依托专业音乐人、DJ、好友推荐及社交功能，为用户打造全新的音乐生活。

.みんな | Google Registry

.みんな is the world's first open hiragana top-level domain. .みんな means "everyone" in Japanese.

はじめよう.みんな

NOTE
卡片显示后，更改主题颜色或启用夜间模式卡片也会随之改变嗷

添加链接卡片#

安装依赖#

我们需要安装 @fastify/deepmerge open-graph-scraper punycode unified 依赖仅需在项目根目录执行 pnpm add 相关依赖即可

1
pnpm add @fastify/deepmerge open-graph-scraper punycode
2
pnpm add -D unified @types/punycode  #-D 安装开发依赖

添加配置#

1
import fuwariLinkCard from "./src/plugins/fuwari-link-card.ts"
2

3
  integrations: [
4
    ...
5

6
    fuwariLinkCard({
7
      internalLink: { enabled: true },
8
    }),
9
    ...
10
  ]

主要配置说明#

名称 (Name)	类型 (Type)	默认值 (Default)	描述 (Description)
`devMode`	`boolean`	import.meta.env.DEV	启用或禁用开发模式。默认情况下，它会根据 Astro 的环境自动判断（即在 `astro dev` 时为 `true`，`astro build` 时为 `false`）。
`excludedUrls`	`Array<string \| RegExp>`	[]	一个由字符串或正则表达式组成的数组，用于排除特定的 URL 不进行链接卡片处理。此选项也有助于防止与其他处理链接的插件发生冲突。
`linkAttributes`	`Object`	{ target: ”, rel: ”, }	为外部链接设置 `target` 和 `rel` 属性。您可以将它们留空（如默认值所示），将这些属性的处理权交给其他插件（例如，一个自动为所有外链添加 `target="_blank"` 的插件）。
`rewriteRules`	`Array<Object>`	[]	重写从链接中获取的特定元数据属性，例如标题（title）和描述（description）。这在您需要修正或自定义抓取到的信息时非常有用。
`base`	`string`	’/‘	指定与您 Astro 配置中相同的 `base` 路径。详情请参考 Astro 的官方文档。当此工具作为 Astro 集成（Integration）使用时，如果未指定此选项，它将被自动检测并设置。
`defaultThumbnail`	`string`	”	当链接的元数据中不包含预览图（`og:image`）时，使用的默认缩略图路径。该路径应相对于 `public` 目录。例如，如果图片位于 `public/images/default-thumbnail.jpg`，则此项应设置为 `'images/default-thumbnail.jpg'`。
`internalLink`	`Object`	{ enabled: false, site: ” }	启用对您站点内部链接的处理。需要设置 `enabled: true` 并提供 `site` 的 URL。

添加插件#

在对应的文件夹下添加文件以及相关代码

1
import type { AstroIntegration } from 'astro'
2
import remarkLinkCard from './remark-link-card.ts'
3
import type { UserOptions } from './remark-link-card.ts'
4

5
const fuwariLinkCard = (options: UserOptions = {}): AstroIntegration => {
6
  const integration: AstroIntegration = {
7
    hooks: {
8
      'astro:config:setup': ({ config, updateConfig }) => {
9
        options.base = options.base ?? config.base
10

11
        if (options.internalLink?.enabled) {
12
          options.internalLink.site = options.internalLink.site ?? config.site
13
        }
14

15
        // If the remark-sectionize plugin exists, insert the new plugin before it to avoid conflicts.
16
        const pluginName = 'plugin' // remark-sectionize
17
        const index = config.markdown.remarkPlugins.findIndex(element => {
18
          if (typeof element === 'function') return element.name === pluginName
19
          if (Array.isArray(element) && typeof element[0] === 'function')
20
            return element[0].name === pluginName
21
          return false
22
        })
23

24
        if (index !== -1) {
25
          config.markdown.remarkPlugins.splice(index, 0, [
26
            remarkLinkCard,
27
            options,
28
          ])
29
        } else {
30
          updateConfig({
31
            markdown: { remarkPlugins: [[remarkLinkCard, options]] },
32
          })
33
        }
34
      },
35
    },
36
    name: 'fuwari-link-card',
37
  }
38

39
  return integration
40
}
41

42
export default fuwariLinkCard
43
export type { UserOptions }

1
import { createHash } from 'node:crypto'
2
import * as fs from 'node:fs/promises'
3
import path from 'node:path'
4
import deepmerge from '@fastify/deepmerge'
5
import { h } from 'hastscript'
6
import type { Link, Paragraph, Root, Text } from 'mdast'
477 collapsed lines
7
import ogs from 'open-graph-scraper'
8
import type { ErrorResult, OgObject } from 'open-graph-scraper/types'
9
import punycode from 'punycode/'
10
import type { Plugin, Transformer } from 'unified'
11
import { visit } from 'unist-util-visit'
12
import type { Visitor } from 'unist-util-visit'
13

14
type DeepPartial<T> = T extends object
15
  ? {
16
      [P in keyof T]?: DeepPartial<T[P]>
17
    }
18
  : T
19

20
type ObtainKeys<T, V> = keyof {
21
  // biome-ignore lint/suspicious/noExplicitAny: <explanation>
22
  [K in keyof T as T[K] extends V ? K : never]: any
23
}
24

25
interface LinkAttributes {
26
  target: string
27
  rel: string
28
}
29

30
interface RewriteStep {
31
  key: string
32
  pattern: RegExp
33
  replacement: string
34
}
35

36
interface RewriteRule {
37
  url: RegExp
38
  rewriteSteps: RewriteStep[]
39
}
40

41
interface InternalLink {
42
  enabled: boolean
43
  site: string
44
}
45

46
interface Cache {
47
  enabled: boolean
48
  outDir: string
49
  cacheDir: string
50
  maxFileSize: number
51
  maxCacheSize: number
52
  userAgent: string
53
}
54

55
interface Options {
56
  devMode: boolean
57
  excludedUrls: (string | RegExp)[]
58
  linkAttributes: LinkAttributes
59
  rewriteRules: RewriteRule[]
60
  base: string
61
  defaultThumbnail: string
62
  internalLink: InternalLink
63
  cache: Cache
64
}
65

66
type UserOptions = DeepPartial<Options>
67

68
interface BareLink {
69
  url: URL
70
  isInternal: boolean
71
}
72

73
interface Data {
74
  url: string
75
  domainName: string
76
  title: string
77
  description: string
78
  date: string
79
  faviconSrc: string
80
  thumbnailSrc: string
81
  thumbnailAlt: string
82
  hasThumbnail: boolean
83
  isInternalLink: boolean
84
}
85

86
const defaultOptions: Options = {
87
  devMode: import.meta.env.DEV,
88
  excludedUrls: [],
89
  linkAttributes: { target: '', rel: '' },
90
  rewriteRules: [],
91
  base: '/',
92
  defaultThumbnail: '',
93
  internalLink: { enabled: false, site: '' },
94
  cache: {
95
    enabled: false,
96
    outDir: './dist/',
97
    cacheDir: './link-card/',
98
    maxFileSize: 0,
99
    maxCacheSize: 0,
100
    userAgent:
101
      'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/127.0.0.0 Safari/537.36',
102
  },
103
}
104

105
const mimeExtensions: Record<string, string> = {
106
  'image/apng': '.apng',
107
  'image/avif': '.avif',
108
  'image/gif': '.gif',
109
  'image/jpeg': '.jpg',
110
  'image/png': '.png',
111
  'image/svg+xml': '.svg',
112
  'image/webp': '.webp',
113
  'image/bmp': '.bmp',
114
  'image/x-icon': '.ico',
115
  'image/tiff': '.tif',
116
}
117

118
const remarkLinkCard: Plugin<[], Root> = (options?: UserOptions) => {
119
  const mergedOptions = deepmerge()(defaultOptions, options ?? {}) as Options
120

121
  const transformer: Transformer<Root> = async tree => {
122
    const tasks: Array<() => Promise<void>> = []
123

124
    const visitor: Visitor<Paragraph> = (paragraphNode, index, parent) => {
125
      if (
126
        index === undefined ||
127
        parent === undefined ||
128
        parent.type !== 'root' ||
129
        paragraphNode.children.length !== 1 ||
130
        paragraphNode.data !== undefined
131
      )
132
        return
133

134
      visit(paragraphNode, 'link', linkNode => {
135
        const bareLink = getBareLink(linkNode, mergedOptions)
136

137
        if (!bareLink || isExcludedUrl(bareLink.url.href, mergedOptions)) return
138

139
        const url = linkNode.url
140

141
        tasks.push(async () => {
142
          const data = await getData(bareLink, mergedOptions)
143
          if (!data) return
144

145
          for (const rewriteRule of mergedOptions.rewriteRules) {
146
            if (!rewriteRule.url.test(url)) continue
147

148
            for (const rewriteStep of rewriteRule.rewriteSteps) {
149
              if (!Object.hasOwn(data, rewriteStep.key)) continue
150

151
              const key = rewriteStep.key as ObtainKeys<Data, string>
152
              data[key] = data[key].replace(
153
                rewriteStep.pattern,
154
                rewriteStep.replacement,
155
              )
156
            }
157
          }
158

159
          const newNode = generateNode(data, mergedOptions)
160
          parent.children.splice(index, 1, newNode)
161
        })
162
      })
163
    }
164

165
    visit(tree, 'paragraph', visitor)
166

167
    try {
168
      await Promise.all(tasks.map(t => t()))
169
    } catch (error) {
170
      console.error(`[remark-link-card] Error: ${error}`)
171
      throw error
172
    }
173
  }
174

175
  return transformer
176
}
177

178
const isAbsoluteUrl = (url: string): boolean => {
179
  return /^[a-z][a-z\d+\-.]*:/i.test(url)
180
}
181

182
const isValidUrl = (url: string): boolean => {
183
  return /^https?:\/\/(?:[-.\w]+)(?:\/[^\s]*)?$/.test(url)
184
}
185

186
const getBareLink = (linkNode: Link, options: Options): BareLink | null => {
187
  if (
188
    linkNode.children.length !== 1 ||
189
    linkNode.children[0].type !== 'text' ||
190
    linkNode.children[0].value !== linkNode.url ||
191
    /\s/.test(linkNode.url) // When the URL contains multiple URLs
192
  )
193
    return null
194

195
  const url = linkNode.url
196
  const isInternal = !isAbsoluteUrl(url)
197
  const base =
198
    options.internalLink.enabled && isInternal
199
      ? options.internalLink.site
200
      : undefined
201

202
  let parsedUrl: URL
203

204
  try {
205
    parsedUrl = new URL(url, base)
206
  } catch {
207
    return null
208
  }
209

210
  if (!isValidUrl(parsedUrl.href)) return null
211

212
  return { url: parsedUrl, isInternal: isInternal }
213
}
214

215
const isExcludedUrl = (url: string, options: Options): boolean => {
216
  for (const excludedUrl of options.excludedUrls) {
217
    if (typeof excludedUrl === 'string') {
218
      if (url.includes(excludedUrl)) return true
219
    } else if (excludedUrl instanceof RegExp) {
220
      if (excludedUrl.test(url)) return true
221
    }
222
  }
223

224
  return false
225
}
226

227
const fetchMetadata = async (
228
  url: string,
229
  options: Options,
230
): Promise<OgObject | null> => {
231
  try {
232
    const data = await ogs({
233
      url: url,
234
      fetchOptions: { headers: { 'user-agent': options.cache.userAgent } },
235
      timeout: 10000,
236
    })
237
    if (data.error) return null
238

239
    return data.result
240
  } catch (error) {
241
    const errorResult = error as ErrorResult
242
    console.warn(
243
      `[remark-link-card] Warning: Failed to fetch Open Graph data for ${errorResult.result.requestUrl} due to ${errorResult.result.error}.`,
244
    )
245

246
    return null
247
  }
248
}
249

250
const getDirSize = async (dirPath: string): Promise<number> => {
251
  const files = await fs.readdir(dirPath, { withFileTypes: true })
252
  const promises = files.map(async file => {
253
    const filePath = path.join(dirPath, file.name)
254
    if (file.isDirectory()) return await getDirSize(filePath)
255

256
    const { size } = await fs.stat(filePath)
257
    return size
258
  })
259

260
  const sizes = await Promise.all(promises)
261
  return sizes.reduce((accumulator, size) => accumulator + size, 0)
262
}
263

264
const ensureDirectoryExists = async (dirPath: string): Promise<void> => {
265
  try {
266
    await fs.access(dirPath)
267
  } catch {
268
    await fs.mkdir(dirPath, { recursive: true })
269
  }
270
}
271

272
const existsCache = async (
273
  cachePath: string,
274
  cacheName: string,
275
): Promise<string | undefined> => {
276
  const cachedFileNames = await fs.readdir(cachePath)
277
  return cachedFileNames.find(cachedFileName =>
278
    cachedFileName.startsWith(cacheName),
279
  )
280
}
281

282
const IsCacheable = async (
283
  fileSize: number,
284
  cachePath: string,
285
  maxFileSize: number,
286
  maxCacheSize: number,
287
): Promise<boolean> => {
288
  const exceedsMaxFileSize = maxFileSize > 0 && fileSize > maxFileSize
289
  const exceedsMaxCacheSize =
290
    maxCacheSize > 0 && (await getDirSize(cachePath)) + fileSize > maxCacheSize
291

292
  return !(exceedsMaxFileSize || exceedsMaxCacheSize)
293
}
294

295
const downloadImage = async (
296
  url: string,
297
  cachePath: string,
298
  options: Options,
299
): Promise<string | null> => {
300
  try {
301
    await ensureDirectoryExists(cachePath)
302

303
    const stem = createHash('sha256').update(decodeURI(url)).digest('hex')
304
    const cachedFileName = await existsCache(cachePath, stem)
305
    if (cachedFileName) return cachedFileName
306

307
    const response = await fetch(url, {
308
      headers: { 'User-Agent': options.cache.userAgent },
309
      signal: AbortSignal.timeout(10000),
310
    })
311
    const contentType = response.headers.get('Content-Type') || ''
312
    const extension = mimeExtensions[contentType] ?? ''
313

314
    if (extension === '') return null
315

316
    const arrayBuffer = await response.arrayBuffer()
317

318
    if (
319
      !(await IsCacheable(
320
        arrayBuffer.byteLength,
321
        cachePath,
322
        options.cache.maxFileSize,
323
        options.cache.maxCacheSize,
324
      ))
325
    )
326
      return null
327

328
    const fileName = `${stem}${extension}`
329
    const filePath = path.join(cachePath, fileName)
330
    const buffer = new Uint8Array(arrayBuffer)
331

332
    await fs.writeFile(filePath, buffer)
333

334
    return fileName
335
  } catch (error) {
336
    console.error(`[remark-link-card] Error: ${error}`)
337
    return null
338
  }
339
}
340

341
const getImageUrl = async (url: string, options: Options): Promise<string> => {
342
  let imageUrl = url
343

344
  if (!options.cache.enabled) return imageUrl
345

346
  const cachePath = path.join(options.cache.outDir, options.cache.cacheDir)
347
  const fileName = await downloadImage(imageUrl, cachePath, options)
348

349
  if (fileName) {
350
    const regex = /^(public|\.\/public)\/?$/
351
    const cachaDir =
352
      options.devMode && !regex.test(options.cache.outDir)
353
        ? cachePath
354
        : options.cache.cacheDir
355

356
    imageUrl = path.join(options.base, cachaDir, fileName)
357
    imageUrl = imageUrl.replaceAll(path.sep, path.posix.sep)
358
  }
359

360
  return imageUrl
361
}
362

363
const getFaviconUrl = async (
364
  url: string,
365
  options: Options,
366
): Promise<string> => {
367
  const faviconUrl = `https://www.google.com/s2/favicons?domain=${url}`
368

369
  return await getImageUrl(faviconUrl, options)
370
}
371

372
const getData = async (
373
  bareLink: BareLink,
374
  options: Options,
375
): Promise<Data | null> => {
376
  const metadata = await fetchMetadata(bareLink.url.href, options)
377
  if (!metadata) return null
378

379
  const url = bareLink.isInternal
380
    ? bareLink.url.href.replace(bareLink.url.origin, '')
381
    : bareLink.url.href
382

383
  const result: Data = {
384
    url: url,
385
    domainName: bareLink.url.hostname,
386
    title: '',
387
    description: '',
388
    date: '',
389
    faviconSrc: '',
390
    thumbnailSrc: '',
391
    thumbnailAlt: 'thumbnail',
392
    hasThumbnail: false,
393
    isInternalLink: bareLink.isInternal,
394
  }
395

396
  result.title = metadata.ogTitle ?? ''
397
  result.description = metadata.ogDescription ?? ''
398

399
  const date = metadata.ogDate ? new Date(metadata.ogDate) : null
400
  if (date && !Number.isNaN(date)) {
401
    result.date = `${date.toISOString().split('.')[0]}Z`
402
  }
403

404
  result.faviconSrc = await getFaviconUrl(bareLink.url.hostname, options)
405

406
  if (metadata.ogImage?.[0]?.url) {
407
    result.thumbnailSrc = await getImageUrl(metadata.ogImage[0].url, options)
408
    result.hasThumbnail = true
409
  } else if (options.defaultThumbnail) {
410
    result.thumbnailSrc = path.join(options.base, options.defaultThumbnail)
411
    result.thumbnailSrc = result.thumbnailSrc.replaceAll(
412
      path.sep,
413
      path.posix.sep,
414
    )
415
  }
416

417
  if (metadata.ogImage?.[0]?.alt) {
418
    result.thumbnailAlt = metadata.ogImage[0].alt
419
  }
420

421
  return result
422
}
423

424
const generateNode = (data: Data, options: Options): Text => {
425
  const target = options.linkAttributes.target
426
  const rel = options.linkAttributes.rel
427

428
  return {
429
    type: 'text',
430
    value: '',
431
    data: {
432
      hName: 'div',
433
      hProperties: { class: 'link-card__container' },
434
      hChildren: [
435
        h(
436
          'a',
437
          {
438
            class: 'link-card',
439
            href: data.url,
440
            ...(!data.isInternalLink && {
441
              ...(target && { target }),
442
              ...(rel && { rel }),
443
            }),
444
          },
445
          [
446
            h('div', { class: 'link-card__info' }, [
447
              h('div', { class: 'link-card__title' }, [data.title]),
448
              h('div', { class: 'link-card__description' }, [data.description]),
449
              h('div', { class: 'link-card__metadata' }, [
450
                h('div', { class: 'link-card__domain' }, [
451
                  h(
452
                    'img',
453
                    {
454
                      class: 'link-card__favicon',
455
                      src: data.faviconSrc,
456
                      alt: 'favicon',
457
                    },
458
                    [],
459
                  ),
460
                  h('span', { class: 'link-card__domain-name' }, [
461
                    punycode.toUnicode(data.domainName),
462
                  ]),
463
                ]),
464
                ...(data.date
465
                  ? [h('span', { class: 'link-card__date' }, [data.date])]
466
                  : []),
467
              ]),
468
            ]),
469
            ...(data.thumbnailSrc
470
              ? [
471
                  h(
472
                    'div',
473
                    {
474
                      class:
475
                        `link-card__thumbnail ${data.hasThumbnail ? '' : 'link-card__thumbnail--default'}`.trim(),
476
                    },
477
                    [
478
                      h(
479
                        'img',
480
                        {
481
                          class: 'link-card__image',
482
                          src: data.thumbnailSrc,
483
                          alt: data.thumbnailAlt,
484
                        },
485
                        [],
486
                      ),
487
                    ],
488
                  ),
489
                ]
490
              : []),
491
          ],
492
        ),
493
      ],
494
    },
495
  }
496
}
497

498
export default remarkLinkCard
499
export type { UserOptions }

修改样式#

1
.link-card__container {
2
    @apply mb-4;
3
}
4

5
.link-card {
6
    @apply flex min-h-32 overflow-hidden rounded-xl transition-colors !no-underline !m-0 !p-0
7
    bg-[var(--card-bg)] hover:bg-[var(--btn-plain-bg-hover)] active:bg-[var(--btn-plain-bg-active)]
8
    ring-1 ring-[var(--btn-plain-bg-hover)] active:ring-[var(--btn-plain-bg-active)];
9
}
10

11
.link-card__info {
12
    @apply w-3/4 flex-1 pl-6 pr-4 py-4 flex flex-col gap-y-2 relative;
13
}
14

15
.link-card__title {
16
    @apply text-black/90 dark:text-white/90
17
    text-base font-semibold leading-6 line-clamp-2;
18
}
19

20
.link-card__title::before {
21
    @apply content-[''] block w-1 h-4 rounded-md bg-[var(--primary)] absolute left-[10px] top-[19px];
22
}
23

24
.link-card:hover .link-card__title,
25
.link-card:hover .link-card__description,
26
.link-card:hover .link-card__domain-name,
27
.link-card:hover .link-card__date {
28
    color: var(--primary);
29
}
30

31
.dark .link-card:hover .link-card__title,
32
.dark .link-card:hover .link-card__description,
33
.dark .link-card:hover .link-card__domain-name,
34
.dark .link-card:hover .link-card__date {
35
    color: var(--primary);
36
}
37

38
.link-card__description {
39
    @apply text-black/75 dark:text-white/75 mt-1 text-sm line-clamp-2;
40
}
41

42
.link-card__metadata {
43
    @apply flex flex-wrap items-center justify-between mt-auto;
44
}
45

46
.link-card__domain {
47
    @apply flex;
48
}
49

50
.link-card__favicon {
51
    @apply !my-0 mr-1 h-4 w-4 pointer-events-none;
52
}
53

54
.link-card__domain-name {
55
    @apply text-black/50 dark:text-white/50 text-xs;
56
}
57

58
.link-card__date {
59
    @apply text-black/50 dark:text-white/50 text-xs;
60
}
61

62
.link-card__thumbnail {
63
    @apply w-1/4 md:max-w-64 pr-6 pt-4;
64
}
65

66
.link-card__image {
67
    @apply h-24 w-48 !my-0 object-contain md:object-cover !rounded-none pointer-events-none;
68
}
69

70
.link-card__thumbnail--default > .link-card__image {
71
    @apply object-contain;
72
}