0
# Privacy Plugin
1

2
Privacy compliance features including external asset localization, cookie consent management, and GDPR compliance helpers. The privacy plugin ensures documentation sites meet privacy regulations by controlling external resource loading and providing transparency about data usage.
3

4
## Capabilities
5

6
### Basic Privacy Setup
7

8
Core privacy configuration that enables privacy-focused features and external resource management.
9

10
```yaml { .api }
11
plugins:
12
  - material/privacy:
13
      enabled: true                      # Enable privacy plugin (default: true)
14
      concurrency: 4                     # Processing concurrency (default: CPU cores - 1)
15
      cache: true                        # Enable caching (default: true)
16
      cache_dir: .cache/plugin/privacy   # Cache directory
17
      assets: true                       # Process external assets (default: true)
18
      assets_fetch: true                 # Fetch external assets (default: true)
19
      assets_fetch_dir: assets/external  # External assets directory
20
```
21

22
### External Assets Management
23

24
Control how external assets (fonts, images, scripts) are handled for privacy compliance.
25

26
```yaml { .api }
27
plugins:
28
  - material/privacy:
29
      external_assets: bundle          # Asset handling mode
30
      external_assets_dir: assets/external  # Local storage directory
31
      external_assets_include: []      # Include patterns
32
      external_assets_exclude: []      # Exclude patterns
33
```
34

35
**Asset Handling Modes**:
36
- `report`: Report external assets without modification
37
- `bundle`: Download and serve external assets locally
38
- `exclude`: Remove external assets entirely
39

40
### Asset Filtering
41

42
Fine-grained control over which external assets to process.
43

44
```yaml { .api }
45
plugins:
46
  - material/privacy:
47
      external_assets_include:
48
        - "*.googleapis.com/*"         # Include Google Fonts
49
        - "*.gstatic.com/*"           # Include Google static assets
50
      external_assets_exclude:
51
        - "*.google-analytics.com/*"   # Exclude analytics
52
        - "*.googletagmanager.com/*"   # Exclude tag manager
53
```
54

55
### Links and External References
56

57
Management of external links and privacy-related link attributes.
58

59
```yaml { .api }
60
plugins:
61
  - material/privacy:
62
      external_links: true             # Process external links
63
      external_links_attr_map:
64
        target: _blank                 # Open in new tab
65
        rel: noopener noreferrer      # Privacy-focused rel attributes
66
      external_links_noopener: true   # Add noopener to external links
67
```
68

69
## Usage Examples
70

71
### Basic Privacy Configuration
72

73
```yaml
74
plugins:
75
  - material/privacy:
76
      external_assets: bundle
77
```
78

79
### GDPR Compliant Setup
80

81
```yaml
82
plugins:
83
  - material/privacy:
84
      external_assets: bundle
85
      external_assets_dir: assets/privacy
86
      external_assets_exclude:
87
        - "*.google-analytics.com/*"
88
        - "*.googletagmanager.com/*"
89
        - "*.facebook.com/*"
90
        - "*.twitter.com/*"
91
      external_links: true
92
      external_links_attr_map:
93
        target: _blank
94
        rel: "noopener noreferrer"
95
```
96

97
### Strict Privacy Mode
98

99
```yaml
100
plugins:
101
  - material/privacy:
102
      external_assets: exclude
103
      external_links: true
104
      external_links_noopener: true
105
```
106

107
### Selective Asset Bundling
108

109
```yaml
110
plugins:
111
  - material/privacy:
112
      external_assets: bundle
113
      external_assets_include:
114
        - "fonts.googleapis.com/*"
115
        - "fonts.gstatic.com/*"
116
      external_assets_exclude:
117
        - "*.doubleclick.net/*"
118
        - "*.googlesyndication.com/*"
119
        - "*.amazon-adsystem.com/*"
120
```
121

122
### Development vs Production
123

124
```yaml
125
plugins:
126
  - material/privacy:
127
      external_assets: !ENV [PRIVACY_MODE, "report"]
128
      external_assets_dir: !ENV [PRIVACY_DIR, "assets/external"]
129
```
130

131
## Cookie Consent Integration
132

133
The privacy plugin works with cookie consent solutions to provide comprehensive privacy compliance.
134

135
### Cookie Consent Configuration
136

137
```html
138
<!-- In custom template or extra_javascript -->
139
<script>
140
  document.addEventListener('DOMContentLoaded', function() {
141
    // Cookie consent implementation
142
    if (!localStorage.getItem('cookieConsent')) {
143
      showCookieConsentBanner();
144
    }
145
  });
146
</script>
147
```
148

149
### Privacy Policy Integration
150

151
```markdown
152
---
153
title: Privacy Policy
154
---
155

156
# Privacy Policy
157

158
## External Resources
159

160
This site uses the following external resources:
161
- Google Fonts for typography
162
- Local copies of all JavaScript libraries
163

164
## Data Collection
165

166
We do not collect personal data through:
167
- Analytics tracking
168
- Social media widgets
169
- Third-party advertising
170

171
## Contact
172

173
For privacy concerns, contact: privacy@example.com
174
```
175

176
## External Asset Reports
177

178
The plugin can generate reports of external asset usage for compliance auditing.
179

180
### Asset Report Structure
181

182
```json
183
{
184
  "external_assets": [
185
    {
186
      "url": "https://fonts.googleapis.com/css2?family=Roboto:wght@300;400;500&display=swap",
187
      "type": "stylesheet",
188
      "pages": ["index.html", "about.html"],
189
      "status": "bundled"
190
    }
191
  ],
192
  "external_links": [
193
    {
194
      "url": "https://example.com",
195
      "pages": ["index.html"],
196
      "attributes": {"target": "_blank", "rel": "noopener noreferrer"}
197
    }
198
  ]
199
}
200
```
201

202
## Site Configuration Integration
203

204
Integrate with site-wide privacy settings.
205

206
### MkDocs Configuration
207

208
```yaml
209
site_name: My Documentation
210
site_url: https://example.com
211

212
extra:
213
  privacy:
214
    policy_url: /privacy/
215
    contact_email: privacy@example.com
216
    
217
plugins:
218
  - material/privacy:
219
      external_assets: bundle
220
      external_links: true
221
```
222

223
### Template Integration
224

225
```html
226
<!-- In custom templates -->
227
{% if config.extra.privacy %}
228
<div class="privacy-notice">
229
  <p>This site respects your privacy. 
230
     <a href="{{ config.extra.privacy.policy_url }}">Privacy Policy</a>
231
  </p>
232
</div>
233
{% endif %}
234
```
235

236
## Plugin API
237

238
```python { .api }
239
class PrivacyPlugin(BasePlugin[PrivacyConfig]):
240
    """Privacy plugin for external asset management and compliance."""
241
    
242
    def on_config(self, config):
243
        """Configure privacy plugin settings."""
244
    
245
    @event_priority(-100)
246
    def on_files(self, files, *, config):
247
        """Process files for privacy compliance."""
248
    
249
    @event_priority(-100)
250
    def on_page_content(self, html, *, page, config, files):
251
        """Process page content for privacy compliance."""
252
    
253
    def on_env(self, env, *, config, files):
254
        """Configure template environment for privacy."""
255
    
256
    @event_priority(-50)
257
    def on_post_template(self, output_content, *, template_name, config):
258
        """Process template output for privacy compliance."""
259
    
260
    @event_priority(-50)
261
    def on_post_page(self, output, *, page, config):
262
        """Process page output for privacy compliance."""
263
    
264
    @event_priority(50)
265
    def on_post_build(self, *, config):
266
        """Generate privacy reports and finalize asset processing."""
267
```
268

269
## Configuration Schema
270

271
```python { .api }
272
class PrivacyConfig(Config):
273
    """Configuration options for the privacy plugin."""
274
    
275
    enabled = Type(bool, default=True)
276
    external_assets = Choice(['report', 'bundle', 'exclude'], default='report')
277
    external_assets_dir = Type(str, default='assets/external')
278
    external_assets_include = Type(list, default=[])
279
    external_assets_exclude = Type(list, default=[])
280
    external_links = Type(bool, default=False)
281
    external_links_attr_map = Type(dict, default={})
282
    external_links_noopener = Type(bool, default=True)
283
```
284

285
## Privacy Compliance Checklist
286

287
Use this checklist to ensure privacy compliance:
288

289
### ✓ External Assets
290
- [ ] External fonts bundled locally
291
- [ ] Third-party scripts eliminated or justified
292
- [ ] CDN resources downloaded and served locally
293
- [ ] Analytics tracking scripts reviewed
294

295
### ✓ External Links
296
- [ ] External links open in new tabs
297
- [ ] `rel="noopener noreferrer"` added to external links
298
- [ ] Privacy policy linked from all pages
299
- [ ] Contact information provided for privacy concerns
300

301
### ✓ Data Collection
302
- [ ] No unnecessary tracking scripts
303
- [ ] Cookie consent implemented if needed
304
- [ ] Privacy policy accurately describes data usage
305
- [ ] User control over optional features