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 -D
pnpm add @nolebase/vitepress-plugin-inline-link-preview -D
npm install @nolebase/vitepress-plugin-inline-link-preview -D
yarn add @nolebase/vitepress-plugin-inline-link-preview -D
Usage
It consists two major steps to integrate the Inline Links Previewing plugin into your VitePress project:
- Configure
markdown-it
plugin (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
A TypeScript User?
You need to configure at least the following options:
{
"compilerOptions": {
"module": "ESNext",
"moduleResolution": "Bundler",
},
"include": [
"**/.vitepress/**/*.ts",
"**/.vitepress/**/*.mts",
"**/.vitepress/**/*.vue"
],
"exclude": [
"node_modules"
]
}
And the options
module
option specifies the JavaScript/TypeScript module format, and Nolebase Integrations uses theESNext
-compatible module format by default.moduleResolution
option specifies the module resolution policy, since all Nolebase Integrations plugins follow the latest ECMAScript specifications and export declarations, if you encounter aCannot find module ... or its corresponding type declarations
error you may need to setmoduleResolution
toBundler
.
If you want more configurations, you can refer to the following example:
{
"compilerOptions": {
"jsx": "preserve",
"lib": [
"DOM",
"ESNext"
],
"module": "ESNext",
"moduleResolution": "Bundler",
"resolveJsonModule": true,
"strict": true,
"strictNullChecks": true,
"noFallthroughCasesInSwitch": true,
"noImplicitAny": true,
"noUnusedLocals": true,
"noUnusedParameters": true,
"noEmit": true,
"removeComments": false,
"esModuleInterop": true,
"forceConsistentCasingInFileNames": true,
"isolatedModules": true,
"verbatimModuleSyntax": true,
"skipLibCheck": true
},
"include": [
"**/.vitepress/**/*.ts",
"**/.vitepress/**/*.mts",
"**/.vitepress/**/*.vue"
],
"exclude": [
"node_modules"
]
}
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-anchor
in the class list. - DOES NOT CONTAIN
no-inline-link-preview
in 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-preview
to the class list. - Assign a
data-inline-link-preview
attribute with the value offalse
.
Add plugin-specific options into configurations of Vite
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 supply some of the Server-Side Rendering related options in the root configuration object of Vite.
Add the Inline Link Previewing plugin package name @nolebase/vitepress-plugin-inline-link-preview
into the Vite options that required by VitePress to process this plugin:
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
A TypeScript User?
You need to configure at least the following options:
{
"compilerOptions": {
"module": "ESNext",
"moduleResolution": "Bundler",
},
"include": [
"**/.vitepress/**/*.ts",
"**/.vitepress/**/*.mts",
"**/.vitepress/**/*.vue"
],
"exclude": [
"node_modules"
]
}
And the options
module
option specifies the JavaScript/TypeScript module format, and Nolebase Integrations uses theESNext
-compatible module format by default.moduleResolution
option specifies the module resolution policy, since all Nolebase Integrations plugins follow the latest ECMAScript specifications and export declarations, if you encounter aCannot find module ... or its corresponding type declarations
error you may need to setmoduleResolution
toBundler
.
If you want more configurations, you can refer to the following example:
{
"compilerOptions": {
"jsx": "preserve",
"lib": [
"DOM",
"ESNext"
],
"module": "ESNext",
"moduleResolution": "Bundler",
"resolveJsonModule": true,
"strict": true,
"strictNullChecks": true,
"noFallthroughCasesInSwitch": true,
"noImplicitAny": true,
"noUnusedLocals": true,
"noUnusedParameters": true,
"noEmit": true,
"removeComments": false,
"esModuleInterop": true,
"forceConsistentCasingInFileNames": true,
"isolatedModules": true,
"verbatimModuleSyntax": true,
"skipLibCheck": true
},
"include": [
"**/.vitepress/**/*.ts",
"**/.vitepress/**/*.mts",
"**/.vitepress/**/*.vue"
],
"exclude": [
"node_modules"
]
}
import { defineConfig } from 'vitepress'
// https://vitepress.dev/reference/site-config
export default defineConfig({
vite: {
optimizeDeps: {
exclude: [
'@nolebase/vitepress-plugin-inline-link-preview/client',
],
},
ssr: {
noExternal: [
// If there are other packages that need to be processed by Vite, you can add them here.
'@nolebase/vitepress-plugin-inline-link-preview',
],
},
},
lang: 'en',
title: 'Site Name',
themeConfig: {
// rest of the options...
}
// rest of the options...
})
You might have configured the separated Vite configuration file (e.g. vite.config.ts
) if you are already mastered Vite. In this case, you could ignore the above configuration and add the following configuration to your Vite configuration file:
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
A TypeScript User?
You need to configure at least the following options:
{
"compilerOptions": {
"module": "ESNext",
"moduleResolution": "Bundler",
},
"include": [
"**/.vitepress/**/*.ts",
"**/.vitepress/**/*.mts",
"**/.vitepress/**/*.vue"
],
"exclude": [
"node_modules"
]
}
And the options
module
option specifies the JavaScript/TypeScript module format, and Nolebase Integrations uses theESNext
-compatible module format by default.moduleResolution
option specifies the module resolution policy, since all Nolebase Integrations plugins follow the latest ECMAScript specifications and export declarations, if you encounter aCannot find module ... or its corresponding type declarations
error you may need to setmoduleResolution
toBundler
.
If you want more configurations, you can refer to the following example:
{
"compilerOptions": {
"jsx": "preserve",
"lib": [
"DOM",
"ESNext"
],
"module": "ESNext",
"moduleResolution": "Bundler",
"resolveJsonModule": true,
"strict": true,
"strictNullChecks": true,
"noFallthroughCasesInSwitch": true,
"noImplicitAny": true,
"noUnusedLocals": true,
"noUnusedParameters": true,
"noEmit": true,
"removeComments": false,
"esModuleInterop": true,
"forceConsistentCasingInFileNames": true,
"isolatedModules": true,
"verbatimModuleSyntax": true,
"skipLibCheck": true
},
"include": [
"**/.vitepress/**/*.ts",
"**/.vitepress/**/*.mts",
"**/.vitepress/**/*.vue"
],
"exclude": [
"node_modules"
]
}
import { defineConfig } from 'vite'
export default defineConfig(() => {
return {
optimizeDeps: {
exclude: [
'@nolebase/vitepress-plugin-inline-link-preview/client',
'vitepress'
],
},
ssr: {
noExternal: [
// If there are other packages that need to be processed by Vite, you can add them here.
'@nolebase/vitepress-plugin-inline-link-preview',
],
},
plugins: [
// other vite plugins...
],
// other vite configurations...
}
})
If you haven't configured any of the separated Vite configuration file (e.g. vite.config.ts
) before but still want to have a try with the above configuration, you can create a vite.config.ts
file in the root directory of your VitePress project and add the above configuration to it. (Don't forget to install vite
through your package manager as well!)
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
A TypeScript User?
You need to configure at least the following options:
{
"compilerOptions": {
"module": "ESNext",
"moduleResolution": "Bundler",
},
"include": [
"**/.vitepress/**/*.ts",
"**/.vitepress/**/*.mts",
"**/.vitepress/**/*.vue"
],
"exclude": [
"node_modules"
]
}
And the options
module
option specifies the JavaScript/TypeScript module format, and Nolebase Integrations uses theESNext
-compatible module format by default.moduleResolution
option specifies the module resolution policy, since all Nolebase Integrations plugins follow the latest ECMAScript specifications and export declarations, if you encounter aCannot find module ... or its corresponding type declarations
error you may need to setmoduleResolution
toBundler
.
If you want more configurations, you can refer to the following example:
{
"compilerOptions": {
"jsx": "preserve",
"lib": [
"DOM",
"ESNext"
],
"module": "ESNext",
"moduleResolution": "Bundler",
"resolveJsonModule": true,
"strict": true,
"strictNullChecks": true,
"noFallthroughCasesInSwitch": true,
"noImplicitAny": true,
"noUnusedLocals": true,
"noUnusedParameters": true,
"noEmit": true,
"removeComments": false,
"esModuleInterop": true,
"forceConsistentCasingInFileNames": true,
"isolatedModules": true,
"verbatimModuleSyntax": true,
"skipLibCheck": true
},
"include": [
"**/.vitepress/**/*.ts",
"**/.vitepress/**/*.mts",
"**/.vitepress/**/*.vue"
],
"exclude": [
"node_modules"
]
}
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/style.css'
export const Theme: ThemeConfig = {
extends: DefaultTheme,
Layout: () => {
// other configurations...
},
enhanceApp({ app }) {
app.use(NolebaseInlineLinkPreviewPlugin)
},
}
export default Theme
Troubleshooting
Encountered Cannot find module ... or its corresponding type declarations
error?
If you are encountering this error with Nolebase Integrations packages inside of .ts
or .vue
files, you may need to configure the moduleResolution
option in your tsconfig.json
file.
{
"compilerOptions": {
"module": "ESNext",
"moduleResolution": "Bundler",
},
"include": [
"**/.vitepress/**/*.ts",
"**/.vitepress/**/*.mts",
"**/.vitepress/**/*.vue"
],
"exclude": [
"node_modules"
]
}
If the error persists, please submit a GitHub issue for further assistance and troubleshooting.