Skip to content

Commit b5df2cf

Browse files
nekomeowwwnekomeowww
authored
docs: added new documentations for thumbnail hasing and unlazy img (#304)
Signed-off-by: Neko Ayaka <neko@ayaka.moe>
1 parent ab4828a commit b5df2cf

12 files changed

Lines changed: 589 additions & 57 deletions

File tree

‎docs/.vitepress/theme/components/ThumbhashPreview.vue‎

Lines changed: 16 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
<script setup lang="ts">
2-
import { computed, ref, watch } from 'vue'
2+
import { computed, onMounted, ref, watch } from 'vue'
33
import { rgbaToThumbHash } from 'thumbhash'
44
import { createPngDataUri } from 'unlazy/thumbhash'
55
import { useClipboard } from '@vueuse/core'
@@ -12,6 +12,7 @@ const props = withDefaults(defineProps<{
1212
clearInputThumbhashText: string
1313
inputThumbhashPlaceholder: string
1414
previewThumbhashText: string
15+
demoImageUrl: string
1516
}>(), {
1617
thumbhashText: 'Select image to generate thumbhash',
1718
applyThumbhashText: 'Apply Thumbhash',
@@ -20,6 +21,7 @@ const props = withDefaults(defineProps<{
2021
clearInputThumbhashText: 'Clear thumbhash',
2122
inputThumbhashPlaceholder: 'Input Thumbhash base64...',
2223
previewThumbhashText: 'Input Thumbhash to preview',
24+
demoImageBase64Url: '',
2325
})
2426
2527
const thumbhash = ref('')
@@ -113,6 +115,19 @@ async function handleCopyHash() {
113115
function handleClearHash() {
114116
thumbhash.value = ''
115117
}
118+
119+
onMounted(() => {
120+
if (props.demoImageUrl) {
121+
const image = new Image()
122+
image.onload = () => {
123+
imageUploadObjectURL.value = props.demoImageUrl
124+
imageUploaded.value = image
125+
handleApplyHash()
126+
}
127+
128+
image.src = props.demoImageUrl
129+
}
130+
})
116131
</script>
117132

118133
<template>

‎docs/pages/en/index.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -55,7 +55,7 @@ Nólëbase Integrations project provides a variety of integrations, plugins, com
5555

5656
<IntegrationCard type="markdown-it" title="Lazy loading blurred thumbnails" package="markdown-it-unlazy-img">
5757
<template v-slot:badge>
58-
<Badge type="warning" text="Beta" />
58+
<Badge type="tip" text="v2.4.0" />
5959
</template>
6060
</IntegrationCard>
6161

@@ -115,7 +115,7 @@ Nólëbase Integrations project provides a variety of integrations, plugins, com
115115

116116
<IntegrationCard type="vitepress" title="Thumbnail hashing for images" package="vitepress-plugin-thumbnail-hash">
117117
<template v-slot:badge>
118-
<Badge type="warning" text="Beta" />
118+
<Badge type="tip" text="v2.4.0" />
119119
</template>
120120
</IntegrationCard>
121121

‎docs/pages/en/integrations/index.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,7 @@ Nólëbase Integrations project provides a variety of integrations, plugins, com
2424

2525
<IntegrationCard type="markdown-it" title="Lazy loading blurred thumbnails" package="markdown-it-unlazy-img">
2626
<template v-slot:badge>
27-
<Badge type="warning" text="Beta" />
27+
<Badge type="tip" text="v2.4.0" />
2828
</template>
2929
</IntegrationCard>
3030

@@ -102,7 +102,7 @@ Nólëbase Integrations project provides a variety of integrations, plugins, com
102102

103103
<IntegrationCard type="vitepress" title="Thumbnail hashing for images" package="vitepress-plugin-thumbnail-hash">
104104
<template v-slot:badge>
105-
<Badge type="warning" text="Beta" />
105+
<Badge type="tip" text="v2.4.0" />
106106
</template>
107107
</IntegrationCard>
108108

‎docs/pages/en/integrations/markdown-it-unlazy-img/index.md‎

Lines changed: 55 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -2,11 +2,7 @@
22
import packageJSON from '~/packages/markdown-it-unlazy-img/package.json'
33
</script>
44

5-
# Lazy loading blurred thumbnails <Badge type="warning" :text="`Beta v${packageJSON.version}`" />
6-
7-
::: warning 🚧 Constructing
8-
Nice to meet you! But sorry, this page is still under construction. If you don’t find the information you are interested in, you can first find the content you are interested in in the navigation in the sidebar to start reading.
9-
:::
5+
# Lazy loading blurred thumbnails <Badge type="tip" :text="`v${packageJSON.version}`" />
106

117
A [`markdown-it`](https://github.com/markdown-it/markdown-it) plugin wraps and transforms image tags to support [unlazy](https://github.com/johannschopplich/unlazy) lazy loading with [blurhash](https://github.com/woltapp/blurhash), [thumbhash](https://github.com/evanw/thumbhash) encoding, and more.
128

@@ -33,3 +29,57 @@ yarn add @nolebase/markdown-it-unlazy-img -D
3329
```
3430

3531
:::
32+
33+
## Configuration
34+
35+
### Integrate with VitePress
36+
37+
In the VitePress configuration file (usually `docs/.vitepress/config.ts`, the file path and extension may be different), import `@nolebase/markdown-it-unlazy-img` as a plugin, and use it as a `markdown-it` plugin in the `markdown` option:
38+
39+
<!--@include: @/pages/en/snippets/details-colored-diff.md-->
40+
41+
```typescript twoslash
42+
import { defineConfigWithTheme } from 'vitepress'
43+
import { UnlazyImages } from '@nolebase/markdown-it-unlazy-img' // [!code ++]
44+
45+
export default defineConfigWithTheme({
46+
lang: 'en',
47+
title: 'Site name', // For reference only, please do not copy directly
48+
description: 'Description', // For reference only, please do not copy directly
49+
themeConfig: {
50+
// Other configurations...
51+
},
52+
markdown: {
53+
config: (md) => {
54+
md.use(md.use(UnlazyImages(), { // [!code ++]
55+
imgElementTag: 'NolebaseUnlazyImg', // [!code ++]
56+
}) // [!code ++]
57+
},
58+
},
59+
})
60+
```
61+
62+
### Integrate on-demand
63+
64+
<!--@include: @/pages/en/snippets/configure-on-your-own-warning.md-->
65+
66+
Import this plugin into the file where you can access the [`markdown-it`](https://github.com/markdown-it/markdown-it) instance, and use it as a `markdown-it` plugin:
67+
68+
```typescript twoslash
69+
import { UnlazyImages } from '@nolebase/markdown-it-unlazy-img' // [!code ++]
70+
```
71+
72+
Then you need to use the `use()` member methods from the `markdown-it` instance to use this plugin:
73+
74+
```typescript twoslash
75+
import MarkdownIt from 'markdown-it'
76+
let markdownIt: MarkdownIt = null as unknown as MarkdownIt
77+
// ---cut---
78+
import { UnlazyImages } from '@nolebase/markdown-it-unlazy-img' // [!code ++]
79+
80+
// Rest of the code...
81+
// @noErrors
82+
markdownIt.use(UnlazyImages(), { // [!code ++]
83+
imgElementTag: 'NolebaseUnlazyImg', // [!code ++]
84+
}) // [!code ++]
85+
```

‎docs/pages/en/integrations/vitepress-plugin-thumbnail-hash/getting-started.md‎

Lines changed: 190 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,190 @@
1+
# Getting started
2+
3+
## Installation
4+
5+
Install `@nolebase/vitepress-plugin-thumbnail-hash` to your project dependencies by running the following command:
6+
7+
::: code-group
8+
9+
```shell [@antfu/ni]
10+
ni @nolebase/vitepress-plugin-thumbnail-hash -D
11+
```
12+
13+
```shell [pnpm]
14+
pnpm add @nolebase/vitepress-plugin-thumbnail-hash -D
15+
```
16+
17+
```shell [npm]
18+
npm install @nolebase/vitepress-plugin-thumbnail-hash -D
19+
```
20+
21+
```shell [yarn]
22+
yarn add @nolebase/vitepress-plugin-thumbnail-hash -D
23+
```
24+
25+
:::
26+
27+
## Usage
28+
29+
It consists two major steps to integrate the Inline Links Previewing plugin into your VitePress project:
30+
31+
- [Configure Vite plugin](#configure-vite-plugin) (data fetching, logs aggregation)
32+
- [Integrate with VitePress](#integrate-with-vitepress-theme) (UI and components)
33+
34+
### Configure Vite plugin
35+
36+
There are two ways to integrate the Thumbnail hashing for images Vite plugin into your VitePress project:
37+
38+
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)](#configure-vite-plugin-in-vitepresss-config-file)
39+
2. [Create a separated Vite configuration file (e.g. `vite.config.ts`) in the root directory of your VitePress project](#configure-vite-plugin-in-a-separated-vite-configuration-file)
40+
41+
#### Configure Vite plugin in VitePress's config file
42+
43+
In VitePress's [**primary configuration file**](https://vitepress.dev/reference/site-config#config-resolution) (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:
44+
45+
<!--@include: @/pages/en/snippets/details-colored-diff.md-->
46+
47+
<!--@include: @/pages/en/snippets/configure-tsconfig.md-->
48+
49+
```typescript twoslash
50+
import { defineConfig } from 'vitepress'
51+
import { // [!code ++]
52+
ThumbnailHashImages, // [!code ++]
53+
} from '@nolebase/vitepress-plugin-thumbnail-hash/vite' // [!code ++]
54+
55+
// https://vitepress.dev/reference/site-config
56+
export default defineConfig({
57+
vite: { // [!code ++]
58+
plugins: [ // [!code ++]
59+
ThumbnailHashImages(), // [!code ++]
60+
],
61+
}, // [!code ++]
62+
lang: 'en',
63+
title: 'Site Name',
64+
themeConfig: {
65+
// rest of the options...
66+
}
67+
// rest of the options...
68+
})
69+
```
70+
71+
#### Configure Vite plugin in a separated Vite configuration file
72+
73+
##### Ensure `vite.config.ts` is created
74+
75+
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`](#configure-plugin-in-viteconfigts).
76+
77+
::: tip New to `vite.config.ts` is?
78+
79+
First of all, `vite.config.ts` is a configuration file for [Vite](https://vitejs.org), the build tool that VitePress is built on. It allows developers to build and transform the assets, content and data in the project.
80+
81+
VitePress itself contains entire set of Vite options in its [**primary configuration file**](https://vitepress.dev/reference/site-config#config-resolution) (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.
82+
83+
:::
84+
85+
Therefore, please create a separated `vite.config.ts` file in the root directory of your VitePress project:
86+
87+
::: tip Where is the root directory of VitePress project?
88+
89+
VitePress project's root directory is where the parent directory of `.vitepress` directory is.
90+
91+
For example:
92+
93+
```shell
94+
.
95+
├── docs
96+
│ ├── .vitepress
97+
│ │ ├── config.ts
98+
│ │ └── theme
99+
│ │ └── index.ts
100+
│ └── README.md
101+
```
102+
103+
In this case, the root directory is `docs`.
104+
105+
```shell
106+
.
107+
├── .vitepress
108+
│ ├── config.ts
109+
│ └── theme
110+
│ └── index.ts
111+
└── README.md
112+
```
113+
114+
In this case, the root directory is `./`.
115+
116+
:::
117+
118+
```shell
119+
touch vite.config.ts
120+
```
121+
122+
##### Configure plugin in `vite.config.ts`
123+
124+
In the standalone [Vite configuration file](https://vitejs.dev/config/) (e.g. `vite.config.ts`) file we have under our root directory, we need to import `ThumbnailHashImages` and configure it properly:
125+
126+
<!--@include: @/pages/en/snippets/details-colored-diff.md-->
127+
128+
<!--@include: @/pages/en/snippets/configure-tsconfig.md-->
129+
130+
```typescript twoslash
131+
import { join } from 'node:path'
132+
import { defineConfig } from 'vite'
133+
import { // [!code ++]
134+
ThumbnailHashImages, // [!code ++]
135+
} from '@nolebase/vitepress-plugin-thumbnail-hash/vite' // [!code ++]
136+
137+
export default defineConfig(() => {
138+
return {
139+
plugins: [ // [!code ++]
140+
ThumbnailHashImages(), // [!code ++]
141+
]
142+
// other vite configurations...
143+
}
144+
})
145+
```
146+
147+
### Integrate with VitePress theme
148+
149+
Now, let's integrate the Thumbnail hashing for images UI widgets into your VitePress project.
150+
151+
In VitePress's [**theme configuration file**](https://vitepress.dev/reference/default-theme-config#default-theme-config) (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:
152+
153+
<!--@include: @/pages/en/snippets/details-colored-diff.md-->
154+
155+
::: code-group
156+
157+
```typescript twoslash [docs/.vitepress/theme/index.ts]
158+
import { h } from 'vue'
159+
import DefaultTheme from 'vitepress/theme'
160+
import type { Theme as ThemeConfig } from 'vitepress'
161+
import { // [!code ++]
162+
NolebaseUnlazyImg, // [!code ++]
163+
} from '@nolebase/vitepress-plugin-thumbnail-hash/client' // [!code ++]
164+
165+
import '@nolebase/vitepress-plugin-thumbnail-hash/client/style.css' // [!code ++]
166+
167+
export const Theme: ThemeConfig = {
168+
extends: DefaultTheme,
169+
Layout: () => {
170+
// other configurations...
171+
},
172+
enhanceApp({ app }) {
173+
app.component('NolebaseUnlazyImg', NolebaseUnlazyImg) // [!code ++]
174+
},
175+
}
176+
177+
export default Theme
178+
```
179+
180+
:::
181+
182+
## What's next?
183+
184+
In order to show and use the needed thumbnail hashes for VitePress pages. Take a look at another plugin called [`markdown-it-unlazy-img`](../markdown-it-unlazy-img/) too.
185+
186+
## Troubleshooting
187+
188+
### Encountered `Cannot find module ... or its corresponding type declarations` error?
189+
190+
<!--@include: @/pages/en/snippets/troubleshooting-cannot-find-module.md-->

0 commit comments

Comments
 (0)