https://github.com/luckrya/markdown-it-link-to-card
š A markdown-it plugin that converts links to cards. Preview simple URL information more intuitively
https://github.com/luckrya/markdown-it-link-to-card
link-to-card markdown markdown-it markdown-it-plugin vitepress vitepress-blog vitepress-theme
Last synced: about 1 month ago
JSON representation
š A markdown-it plugin that converts links to cards. Preview simple URL information more intuitively
- Host: GitHub
- URL: https://github.com/luckrya/markdown-it-link-to-card
- Owner: luckrya
- License: mit
- Created: 2022-10-17T11:24:28.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2024-02-19T15:27:10.000Z (over 1 year ago)
- Last Synced: 2025-04-22T11:55:34.240Z (2 months ago)
- Topics: link-to-card, markdown, markdown-it, markdown-it-plugin, vitepress, vitepress-blog, vitepress-theme
- Language: TypeScript
- Homepage:
- Size: 43.9 KB
- Stars: 19
- Watchers: 0
- Forks: 2
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# @luckrya/markdown-it-link-to-card
A [markdown-it](https://github.com/markdown-it/markdown-it) plugin for turning page links into link cards (which contain brief information about the link).
- Extract links with special flags (eg. `[text](@:url)`) and convert them into card information display.
- Support for custom renderers to support rendering into anything you want.
- Support injecting class names for cards to support custom styles.
## Install
```sh
npm i -D @luckrya/markdown-it-link-to-card
```
## Usage
```ts
import MarkdownIt from "markdown-it";
import { linkToCardPlugin } from "@luckrya/markdown-it-link-to-card";
import type { LinkToCardPluginOptions } from "@luckrya/markdown-it-link-to-card";
const md = MarkdownIt({ html: true }).use(
linkToCardPlugin,
{
// options
size: "small",
}
);
const rendered = md.render(`
# Home
...
### Reference
- [github](https://github.com)
- [bing](https://cn.bing.com/)
- [ē„ä¹ - åē°é”µ](https://www.zhihu.com/explore)
- [markdown-it-link-to-card](https://github.com/luckrya/markdown-it-link-to-card)
- [github](@:https://github.com)
- [bing](@:https://cn.bing.com)
- [ē„ä¹ - åē°é”µ](@:https://www.zhihu.com/explore)
- [markdown-it-link-to-card](@:https://github.com/luckrya/markdown-it-link-to-card)
`);
```
**Use in vitepress:**
```ts
// docs/.vitepress/config.ts
import { defineConfig } from "vitepress";
import { linkToCardPlugin } from "@luckrya/markdown-it-link-to-card";
import type { LinkToCardPluginOptions } from "@luckrya/markdown-it-link-to-card";
export default defineConfig({
// ...
themeConfig: {
nav: [{ text: "Home", link: "/index" }],
},
markdown: {
config: (md) => {
md.use(linkToCardPlugin, {
// options
size: "small",
});
},
},
// ...
});
// docs/index.md
// Let's say your home page content is:
`
# Home
...
### Reference
- [github](https://github.com)
- [bing](https://cn.bing.com/)
- [ē„ä¹ - åē°é”µ](https://www.zhihu.com/explore)
- [markdown-it-link-to-card](https://github.com/luckrya/markdown-it-link-to-card)
- [github](@:https://github.com)
- [bing](@:https://cn.bing.com)
- [ē„ä¹ - åē°é”µ](@:https://www.zhihu.com/explore)
- [markdown-it-link-to-card](@:https://github.com/luckrya/markdown-it-link-to-card)
`;
```
**_Rendering results:_**
## Options
### tag
- Type: `string`
- Default: `@`
- Details:
Identifier, e.g. `[xxx](@:https://github.com)`
> Note that a regular expression will be constructed internally to separate characters. If the value provided by tag is a special symbol of the regular expression, be sure to escape it manually.
>
> e.g. `\\$` => `[xxx]($:https://github.com)`
### Size
- Type: `'small' | 'large'`
- Default: `'small'`
- Details: Card size, only valid in inline style mode.
### target
- Type: `'_self' | '_blank' | '_top' | '_parent'`
- Default: `'_blank'`
- Details: Link jump behavior. [more detail](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#attr-target)
### classPrefix
- Type: `string | undefined`
- Default: `undefined`
- Details: Card DOM class name prefix. If this option is set, the inline style will not be injected, but the relevant class name will be injected directly. e.g. the setting value is `'my-docs'` will get the following structure
```html
$title
$description
```
### showTitle
- Type: `boolean`
- Default: true
- Details: Whether to display the link title. Note that this will be displayed as a tooltip, with the displayed value extracted from `[link title]()`. [more detail](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/title)
### render
- Type: `undefined | CardDomRender`
```ts
type CardDomRender = (
data: {
logo?: string;
title?: string;
description?: string;
},
options: {
href: string;
linkTitle: string;
showTitle: boolean;
target: "_self" | "_blank" | "_top" | "_parent";
size: "small" | "large";
classPrefix?: string;
}
) => string;
```
- Default: `undefined`
- Details: Custom Rendering DOM Fragments.
## Q/A
### How to get url metadata?
Synchronized remote request. why? "All complex parsers are sync by nature.".
As the number of card links you write increases, the loading will not become very slow, because it does caching internally.
### Does the plugin set up the cache? And how?
Yes, it's set. It will cache all the parsed metadata in the form of local cache instead of in memory!
A special file (`.linkcardrc`) will be created in the working directory of the current execution to store this metadata.
> It is not recommended that this file be ignored by Gitļ¼
## API
```ts
import { generateCard } from "@luckrya/markdown-it-link-to-card";
generateCard("https://github.com", {
linkTitle: "Github Home",
showTitle: true,
size: "small",
}).then(({ dom }) => {
// card dom fragment
console.log(dom);
});
```