0
# VuePress Medium Zoom Plugin
1

2
A VuePress plugin that integrates the medium-zoom library to provide elegant image zoom functionality for documentation sites. The plugin enables users to click on images to expand them with a smooth zoom animation overlay, enhancing the visual experience of documentation without additional UI complexity.
3

4
## Package Information
5

6
- **Package Name**: @vuepress/plugin-medium-zoom
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install @vuepress/plugin-medium-zoom`
10

11
## Core Imports
12

13
VuePress plugins are typically imported and configured in the VuePress configuration file:
14

15
```javascript
16
// .vuepress/config.js
17
module.exports = {
18
  plugins: [
19
    ['@vuepress/plugin-medium-zoom', options]
20
  ]
21
}
22
```
23

24
For programmatic usage:
25

26
```javascript
27
const mediumZoomPlugin = require('@vuepress/plugin-medium-zoom');
28
```
29

30
## Basic Usage
31

32
### Default Configuration
33

34
Enable the plugin with default settings that target content images not wrapped in links:
35

36
```javascript
37
// .vuepress/config.js
38
module.exports = {
39
  plugins: [
40
    '@vuepress/plugin-medium-zoom'
41
  ]
42
}
43
```
44

45
### Custom Selector Configuration
46

47
Configure the plugin to target specific images using CSS selectors:
48

49
```javascript
50
// .vuepress/config.js
51
module.exports = {
52
  plugins: [
53
    ['@vuepress/plugin-medium-zoom', {
54
      selector: '.my-custom-images img',
55
      options: {
56
        margin: 16,
57
        background: 'rgba(25, 18, 25, 0.9)',
58
        scrollOffset: 40
59
      }
60
    }]
61
  ]
62
}
63
```
64

65
## Capabilities
66

67
### Plugin Factory Function
68

69
Creates a VuePress plugin configuration object with medium-zoom integration.
70

71
```javascript { .api }
72
/**
73
 * VuePress plugin factory function for medium-zoom integration (default export)
74
 * @param {PluginOptions} options - Plugin configuration options
75
 * @param {VuePressContext} context - VuePress application context
76
 * @returns {VuePressPlugin} Plugin configuration object
77
 */
78
module.exports = (options, context) => VuePressPlugin;
79

80
interface PluginOptions {
81
  /** CSS selector for images to apply zoom functionality */
82
  selector?: string;
83
  /** Configuration options passed to medium-zoom library */
84
  options?: MediumZoomOptions;
85
}
86

87
interface VuePressPlugin {
88
  /** Global constants injected into client-side code */
89
  define: {
90
    SELECTOR: string;
91
    OPTIONS: MediumZoomOptions | undefined;
92
  };
93
  /** Path to client-side Vue.js mixin */
94
  clientRootMixin: string;
95
}
96
```
97

98
### Plugin Configuration Options
99

100
Configure image targeting and zoom behavior through the options parameter.
101

102
```javascript { .api }
103
interface PluginOptions {
104
  /**
105
   * CSS selector for images to apply zoom functionality
106
   * @default '.theme-default-content :not(a) > img'
107
   */
108
  selector?: string;
109
  
110
  /**
111
   * Configuration options passed directly to medium-zoom library
112
   * Supports all medium-zoom configuration options
113
   */
114
  options?: MediumZoomOptions;
115
}
116

117
interface MediumZoomOptions {
118
  /** Spacing around the zoomed image in pixels */
119
  margin?: number;
120
  /** Background color/style for the zoom overlay */
121
  background?: string;
122
  /** Vertical offset from viewport top when scrolling */
123
  scrollOffset?: number;
124
  /** Additional medium-zoom configuration options */
125
  [key: string]: any;
126
}
127
```
128

129
### Client-Side Integration
130

131
The plugin automatically injects a Vue.js mixin that handles zoom initialization and lifecycle management.
132

133
```javascript { .api }
134
interface ClientRootMixin {
135
  /** Vue component data containing zoom instance */
136
  data(): {
137
    zoom: MediumZoomInstance | null;
138
  };
139
  
140
  /** Initialize zoom functionality when component mounts */
141
  mounted(): void;
142
  
143
  /** Reinitialize zoom when component updates (SPA navigation) */
144
  updated(): void;
145
  
146
  /** Update/reinitialize zoom functionality with current DOM state */
147
  methods: {
148
    updateZoom(): void;
149
  };
150
}
151

152
interface MediumZoomInstance {
153
  /** Remove zoom functionality from all images */
154
  detach(): void;
155
  /** Additional medium-zoom instance methods */
156
  [key: string]: any;
157
}
158
```
159

160
### CSS Styling
161

162
The plugin includes CSS styling for proper z-index management of zoom overlays.
163

164
```css { .api }
165
/* Zoom overlay container styling */
166
.medium-zoom-overlay {
167
  z-index: 100;
168
}
169

170
/* Zoomed image styling - ensures image appears above overlay */
171
.medium-zoom-overlay ~ img {
172
  z-index: 101;
173
}
174
```
175

176
## Configuration Examples
177

178
### Target All Images
179

180
```javascript
181
module.exports = {
182
  plugins: [
183
    ['@vuepress/plugin-medium-zoom', {
184
      selector: 'img'
185
    }]
186
  ]
187
}
188
```
189

190
### Target Images in Specific Container
191

192
```javascript
193
module.exports = {
194
  plugins: [
195
    ['@vuepress/plugin-medium-zoom', {
196
      selector: '.content-wrapper img:not([data-no-zoom])'
197
    }]
198
  ]
199
}
200
```
201

202
### Advanced Medium-Zoom Configuration
203

204
```javascript
205
module.exports = {
206
  plugins: [
207
    ['@vuepress/plugin-medium-zoom', {
208
      selector: '.theme-default-content :not(a) > img',
209
      options: {
210
        margin: 24,
211
        background: 'rgba(0, 0, 0, 0.8)',
212
        scrollOffset: 0,
213
        container: {
214
          top: 24,
215
          right: 24,
216
          bottom: 24,
217
          left: 24
218
        },
219
        template: {
220
          closeButton: true
221
        }
222
      }
223
    }]
224
  ]
225
}
226
```
227

228
## Integration Details
229

230
### VuePress Integration Points
231

232
- **Plugin System**: Uses VuePress plugin architecture with factory function pattern
233
- **Global Constants**: Injects `SELECTOR` and `OPTIONS` globally via `define` mechanism
234
- **Client Mixin**: Provides Vue.js component mixin for lifecycle management
235
- **Theme Compatibility**: Default selector targets VuePress default theme structure
236
- **SPA Support**: Handles Vue.js component updates and navigation changes
237

238
### Medium-Zoom Library Integration
239

240
- **Dependency**: Uses `medium-zoom@^1.0.4` as core zoom functionality
241
- **Configuration Passthrough**: All medium-zoom options supported via `options` parameter  
242
- **Instance Management**: Handles proper initialization, cleanup, and DOM updates
243
- **Lifecycle Integration**: Manages zoom instance lifecycle with Vue.js component lifecycle
244

245
### Browser Compatibility
246

247
- **Modern Browsers**: Full support for modern browsers with ES6+ features
248
- **CSS Requirements**: Requires CSS support for z-index and transitions
249
- **Touch Support**: Inherits touch/mobile support from medium-zoom library
250

251
## Default Behavior
252

253
- **Default Selector**: `.theme-default-content :not(a) > img` - targets content images not wrapped in links
254
- **Lazy Initialization**: 1-second delay before zoom initialization to ensure DOM stability
255
- **Automatic Cleanup**: Detaches previous zoom instances before reinitializing
256
- **SPA Navigation**: Automatically reinitializes zoom when Vue.js components update