markdown-it-link-to-card
markdown-it-link-to-card copied to clipboard
π A markdown-it plugin that converts links to cards. Preview simple URL information more intuitively
@luckrya/markdown-it-link-to-card
A 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
npm i -D @luckrya/markdown-it-link-to-card
Usage
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<LinkToCardPluginOptions>(
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)
<br />
- [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:
// 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<LinkToCardPluginOptions>(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)
<br />
- [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
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<span class="my-docs__container"> <img class="my-docs__img" src="$logo" /> <span class="my-docs__texts"> <span class="my-docs__texts--title">$title</span> <span class="my-docs__texts--desc">$description</span> </span> </span>
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
render
-
Type:
undefined | CardDomRender
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
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);
});