tessl/pypi-mkdocs-material

Material Design theme for MkDocs with built-in plugins for blogs, search, social cards, and privacy compliance

—

Pending

Overview

Eval results

Files

Privacy Plugin

Name: tessl/pypi-mkdocs-material
Author: tessl

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.

Capabilities

Basic Privacy Setup

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

plugins:
  - material/privacy:
      enabled: true                      # Enable privacy plugin (default: true)
      concurrency: 4                     # Processing concurrency (default: CPU cores - 1)
      cache: true                        # Enable caching (default: true)
      cache_dir: .cache/plugin/privacy   # Cache directory
      assets: true                       # Process external assets (default: true)
      assets_fetch: true                 # Fetch external assets (default: true)
      assets_fetch_dir: assets/external  # External assets directory

External Assets Management

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

plugins:
  - material/privacy:
      external_assets: bundle          # Asset handling mode
      external_assets_dir: assets/external  # Local storage directory
      external_assets_include: []      # Include patterns
      external_assets_exclude: []      # Exclude patterns

Asset Handling Modes:

report: Report external assets without modification
bundle: Download and serve external assets locally
exclude: Remove external assets entirely

Asset Filtering

Fine-grained control over which external assets to process.

plugins:
  - material/privacy:
      external_assets_include:
        - "*.googleapis.com/*"         # Include Google Fonts
        - "*.gstatic.com/*"           # Include Google static assets
      external_assets_exclude:
        - "*.google-analytics.com/*"   # Exclude analytics
        - "*.googletagmanager.com/*"   # Exclude tag manager

Links and External References

Management of external links and privacy-related link attributes.

plugins:
  - material/privacy:
      external_links: true             # Process external links
      external_links_attr_map:
        target: _blank                 # Open in new tab
        rel: noopener noreferrer      # Privacy-focused rel attributes
      external_links_noopener: true   # Add noopener to external links

Usage Examples

Basic Privacy Configuration

plugins:
  - material/privacy:
      external_assets: bundle

GDPR Compliant Setup

plugins:
  - material/privacy:
      external_assets: bundle
      external_assets_dir: assets/privacy
      external_assets_exclude:
        - "*.google-analytics.com/*"
        - "*.googletagmanager.com/*"
        - "*.facebook.com/*"
        - "*.twitter.com/*"
      external_links: true
      external_links_attr_map:
        target: _blank
        rel: "noopener noreferrer"

Strict Privacy Mode

plugins:
  - material/privacy:
      external_assets: exclude
      external_links: true
      external_links_noopener: true

Selective Asset Bundling

plugins:
  - material/privacy:
      external_assets: bundle
      external_assets_include:
        - "fonts.googleapis.com/*"
        - "fonts.gstatic.com/*"
      external_assets_exclude:
        - "*.doubleclick.net/*"
        - "*.googlesyndication.com/*"
        - "*.amazon-adsystem.com/*"

Development vs Production

plugins:
  - material/privacy:
      external_assets: !ENV [PRIVACY_MODE, "report"]
      external_assets_dir: !ENV [PRIVACY_DIR, "assets/external"]

Cookie Consent Integration

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

Cookie Consent Configuration

<!-- In custom template or extra_javascript -->
<script>
  document.addEventListener('DOMContentLoaded', function() {
    // Cookie consent implementation
    if (!localStorage.getItem('cookieConsent')) {
      showCookieConsentBanner();
    }
  });
</script>

Privacy Policy Integration

---
title: Privacy Policy
---

# Privacy Policy

## External Resources

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

## Data Collection

We do not collect personal data through:
- Analytics tracking
- Social media widgets
- Third-party advertising

## Contact

For privacy concerns, contact: privacy@example.com

External Asset Reports

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

Asset Report Structure

{
  "external_assets": [
    {
      "url": "https://fonts.googleapis.com/css2?family=Roboto:wght@300;400;500&display=swap",
      "type": "stylesheet",
      "pages": ["index.html", "about.html"],
      "status": "bundled"
    }
  ],
  "external_links": [
    {
      "url": "https://example.com",
      "pages": ["index.html"],
      "attributes": {"target": "_blank", "rel": "noopener noreferrer"}
    }
  ]
}

Site Configuration Integration

Integrate with site-wide privacy settings.

MkDocs Configuration

site_name: My Documentation
site_url: https://example.com

extra:
  privacy:
    policy_url: /privacy/
    contact_email: privacy@example.com
    
plugins:
  - material/privacy:
      external_assets: bundle
      external_links: true

Template Integration

<!-- In custom templates -->
{% if config.extra.privacy %}
<div class="privacy-notice">
  <p>This site respects your privacy. 
     <a href="{{ config.extra.privacy.policy_url }}">Privacy Policy</a>
  </p>
</div>
{% endif %}

Plugin API

class PrivacyPlugin(BasePlugin[PrivacyConfig]):
    """Privacy plugin for external asset management and compliance."""
    
    def on_config(self, config):
        """Configure privacy plugin settings."""
    
    @event_priority(-100)
    def on_files(self, files, *, config):
        """Process files for privacy compliance."""
    
    @event_priority(-100)
    def on_page_content(self, html, *, page, config, files):
        """Process page content for privacy compliance."""
    
    def on_env(self, env, *, config, files):
        """Configure template environment for privacy."""
    
    @event_priority(-50)
    def on_post_template(self, output_content, *, template_name, config):
        """Process template output for privacy compliance."""
    
    @event_priority(-50)
    def on_post_page(self, output, *, page, config):
        """Process page output for privacy compliance."""
    
    @event_priority(50)
    def on_post_build(self, *, config):
        """Generate privacy reports and finalize asset processing."""

Configuration Schema

class PrivacyConfig(Config):
    """Configuration options for the privacy plugin."""
    
    enabled = Type(bool, default=True)
    external_assets = Choice(['report', 'bundle', 'exclude'], default='report')
    external_assets_dir = Type(str, default='assets/external')
    external_assets_include = Type(list, default=[])
    external_assets_exclude = Type(list, default=[])
    external_links = Type(bool, default=False)
    external_links_attr_map = Type(dict, default={})
    external_links_noopener = Type(bool, default=True)

Privacy Compliance Checklist

Use this checklist to ensure privacy compliance:

✓ External Assets

External fonts bundled locally
Third-party scripts eliminated or justified
CDN resources downloaded and served locally
Analytics tracking scripts reviewed

✓ External Links

External links open in new tabs
rel="noopener noreferrer" added to external links
Privacy policy linked from all pages
Contact information provided for privacy concerns

✓ Data Collection

No unnecessary tracking scripts
Cookie consent implemented if needed
Privacy policy accurately describes data usage
User control over optional features

Install with Tessl CLI

npx tessl i tessl/pypi-mkdocs-material

docs

additional-plugins.md

theme-configuration.md

tile.json