Getting Started

Word count

488 words

Reading time

4 minutes

Installation

Install @nolebase/vitepress-plugin-inline-link-preview to your project dependencies by running the following command:

@antfu/ni

ni @nolebase/vitepress-plugin-inline-link-preview -D

pnpm

pnpm add @nolebase/vitepress-plugin-inline-link-preview -D

npm

npm install @nolebase/vitepress-plugin-inline-link-preview -D

yarn

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 the ESNext-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 a Cannot find module ... or its corresponding type declarations error you may need to set moduleResolution to Bundler.

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"
  ]
}

typescript

import {  } from 'vitepress'
import { 
   
} from '@nolebase/vitepress-plugin-inline-link-preview/markdown-it'

// https://vitepress.dev/reference/site-config
export default ({
  : 'en',
  : 'Site Name',
  : {
    // rest of the options...
  },
  : { 
    () { 
      // other markdown-it configurations...
      .() 
    } 
  } 
  // 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:

1. DOES NOT CONTAIN header-anchor in the class list.
2. DOES NOT CONTAIN no-inline-link-preview in the class list.
3. 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:

1. Add no-inline-link-preview to the class list.
2. Assign a data-inline-link-preview attribute with the value of false.

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 the ESNext-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 a Cannot find module ... or its corresponding type declarations error you may need to set moduleResolution to Bundler.

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"
  ]
}

.vitepress/theme/index.ts

import {  } from 'vue'
import  from 'vitepress/theme'
import type {  as ThemeConfig } from 'vitepress'
import { 
  , 
} from '@nolebase/vitepress-plugin-inline-link-preview/client'

import '@nolebase/vitepress-plugin-inline-link-preview/client/style.css'

export const : ThemeConfig = {
  : ,
  : () => {
    // other configurations...
  },
  ({  }) { 
    .() 
  }, 
}

export default 

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.

Contributors

Neko

godkun

Changelog

Last edited 20 days agoView full history

ed0b1-docs: incorrect import path for style.css (#186)

52672-docs: refined docs

0227c-feat(enhanced-readabilities): migrate to use unbuild (#161)

e00b9-feat(git-changelog): added i18n capabilities, added more fancy documentations (#156)

e690e-docs: refactored docs to better guide users