Getting Started
Installation
Install @nolebase/vitepress-plugin-inline-link-preview to your project dependencies by running the following command:
ni @nolebase/vitepress-plugin-inline-link-preview -Dpnpm add @nolebase/vitepress-plugin-inline-link-preview -Dnpm install @nolebase/vitepress-plugin-inline-link-preview -Dyarn add @nolebase/vitepress-plugin-inline-link-preview -DUsage
It consists two major steps to integrate the Inline Links Previewing plugin into your VitePress project:
- Configure
markdown-itplugin (syntax and markup handling) - Integrate with VitePress (UI and components)
Configure markdown-it plugin
First of all, in VitePress's primary configuration file (not this is not a theme configuration file, it's usually located at docs/.vitepress/config.ts, file paths and extensions may be vary), you need to register the essential markdown-it plugin that required:
If you've never seen a colored diff before
This is a markup rule for displaying diff in the user interface (UI).
Red parts usually represents the lines you are going to remove, commonly appeared with a Minus sign -, or you could simply understand it as: this line will be removed.
Green parts usually represents the lines you are going to add, commonly appeared with a Plus sign +, or you could simply understand it as: this line will be added.
To learn more about diff, you can check out this answer about the history of diffutils and Git's documentation
import { defineConfig } from 'vitepress'
import {
InlineLinkPreviewElementTransform
} from '@nolebase/vitepress-plugin-inline-link-preview/markdown-it'
// https://vitepress.dev/reference/site-config
export default defineConfig({
lang: 'en',
title: 'Site Name',
themeConfig: {
// rest of the options...
},
markdown: {
config(md) {
// other markdown-it configurations...
md.use(InlineLinkPreviewElementTransform)
}
}
// rest of the options...
})Behind the scene, the InlineLinkPreviewElementTransform is a markdown-it plugin that directly transforms the []() link markup <a> elements into the <VPNolebaseInlineLinkPreview> elements (which is a Vue component that renders the inline link previewing UI).
By default, this markdown-it plugin will transform all the []() link markup or <a> elements that met the following conditions:
- DOES NOT CONTAIN
header-anchorin the class list. - DOES NOT CONTAIN
no-inline-link-previewin the class list. - DOES HAVE
data-inline-link-preview="false"attribute.
Therefore, for those []() link markup and <a> elements you don't want to transform into <VPNolebaseInlineLinkPreview>, you either:
- Add
no-inline-link-previewto the class list. - Assign a
data-inline-link-previewattribute with the value offalse.
Integrate with VitePress
Since the InlineLinkPreviewElementTransform plugin will transform the []() link markup or <a> elements into the <VPNolebaseInlineLinkPreview> elements, you need to install the VPNolebaseInlineLinkPreview component into your VitePress theme in order to render the inline link previewing UI.
In VitePress's theme configuration file (note that it's not a configuration file, it's usually located at docs/.vitepress/theme/index.ts, file paths and extensions may be vary), install the Vue plugins:
If you've never seen a colored diff before
This is a markup rule for displaying diff in the user interface (UI).
Red parts usually represents the lines you are going to remove, commonly appeared with a Minus sign -, or you could simply understand it as: this line will be removed.
Green parts usually represents the lines you are going to add, commonly appeared with a Plus sign +, or you could simply understand it as: this line will be added.
To learn more about diff, you can check out this answer about the history of diffutils and Git's documentation
import { h } from 'vue'
import DefaultTheme from 'vitepress/theme'
import type { Theme as ThemeConfig } from 'vitepress'
import {
NolebaseInlineLinkPreviewPlugin,
} from '@nolebase/vitepress-plugin-inline-link-preview/client'
import '@nolebase/vitepress-plugin-inline-link-preview/client/styles.css'
export const Theme: ThemeConfig = {
extends: DefaultTheme,
Layout: () => {
// other configurations...
},
enhanceApp({ app }) {
app.use(NolebaseInlineLinkPreviewPlugin)
},
}
export default ThemeContributors
Neko