Getting started

Word count

715 words

Reading time

5 minutes

Installation

Install @nolebase/vitepress-plugin-thumbnail-hash to your project dependencies by running the following command:

@antfu/ni

ni @nolebase/vitepress-plugin-thumbnail-hash -D

pnpm

pnpm add @nolebase/vitepress-plugin-thumbnail-hash -D

npm

npm install @nolebase/vitepress-plugin-thumbnail-hash -D

yarn

yarn add @nolebase/vitepress-plugin-thumbnail-hash -D

Usage

It consists two major steps to integrate the Inline Links Previewing plugin into your VitePress project:

• Configure Vite plugin (data fetching, logs aggregation)
• Integrate with VitePress (UI and components)

Configure Vite plugin

There are two ways to integrate the Thumbnail hashing for images Vite plugin into your VitePress project:

1. Recommended: Use the vite option in VitePress's primary configuration file (usually located at docs/.vitepress/config.ts, file paths and extensions may be vary)
2. Create a separated Vite configuration file (e.g. vite.config.ts) in the root directory of your VitePress project

Configure Vite plugin in VitePress's config file

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), we need to import ThumbnailHashImages and configure it properly:

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

import { defineConfig } from 'vitepress'
import { 
  ThumbnailHashImages, 
} from '@nolebase/vitepress-plugin-thumbnail-hash/vite'

// https://vitepress.dev/reference/site-config
export default defineConfig({
  vite: { 
    plugins: [ 
      ThumbnailHashImages(), 
    ],
  }, 
  lang: 'en',
  title: 'Site Name',
  themeConfig: {
    // rest of the options...
  }
  // rest of the options...
})

Configure Vite plugin in a separated Vite configuration file

Ensure vite.config.ts is created

If you understand what vite.config.ts is already and have created it, you can skip this preparation step and jump to the next step Configure plugin in vite.config.ts.

New to vite.config.ts is?

First of all, vite.config.ts is a configuration file for Vite, the build tool that VitePress is built on. It allows developers to build and transform the assets, content and data in the project.

VitePress itself contains entire set of Vite options in its 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), these options, and yet, the vite.config.ts are identical in terms of configurations.

Therefore, please create a separated vite.config.ts file in the root directory of your VitePress project:

Where is the root directory of VitePress project?

VitePress project's root directory is where the parent directory of .vitepress directory is.

For example:

.
├── docs
│   ├── .vitepress
│   │   ├── config.ts
│   │   └── theme
│   │       └── index.ts
│   └── README.md

In this case, the root directory is docs.

.
├── .vitepress
│   ├── config.ts
│   └── theme
│       └── index.ts
└── README.md

In this case, the root directory is ./.

touch vite.config.ts

Configure plugin in vite.config.ts

In the standalone Vite configuration file (e.g. vite.config.ts) file we have under our root directory, we need to import ThumbnailHashImages and configure it properly:

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

import { join } from 'node:path'
import { defineConfig } from 'vite'
import { 
  ThumbnailHashImages, 
} from '@nolebase/vitepress-plugin-thumbnail-hash/vite'

export default defineConfig(() => {
  return {
    plugins: [ 
      ThumbnailHashImages(), 
    ]
    // other vite configurations...
  }
})

Integrate with VitePress theme

Now, let's integrate the Thumbnail hashing for images UI widgets into your VitePress project.

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 plugin and use the components:

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

docs/.vitepress/theme/index.ts

import { h } from 'vue'
import DefaultTheme from 'vitepress/theme'
import type { Theme as ThemeConfig } from 'vitepress'
import { 
  NolebaseUnlazyImg, 
} from '@nolebase/vitepress-plugin-thumbnail-hash/client'

import '@nolebase/vitepress-plugin-thumbnail-hash/client/style.css'

export const Theme: ThemeConfig = {
  extends: DefaultTheme,
  Layout: () => {
    // other configurations...
  },
  enhanceApp({ app }) {
    app.component('NolebaseUnlazyImg', NolebaseUnlazyImg)  
  },
}

export default Theme

What's next?

In order to show and use the needed thumbnail hashes for VitePress pages. Take a look at another plugin called markdown-it-unlazy-img too.

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

Changelog

Last edited about 1 month ago

View full history

a77cb30-feat(index): new plugin vitepress-plugin-index (#328)

b5df2cf-docs: added new documentations for thumbnail hasing and unlazy img (#304)