Offline Documentation

Creating offline-accessible documentation is essential for users who need to reference your documentation without an internet connection. This includes developers working in secure environments, travelers, or anyone who wants a local copy for performance or archival purposes.

Overview

Offline documentation provides: - Complete local access - All content available without internet - Fast performance - No network latency - Version control - Specific documentation snapshots - Distribution flexibility - Share via USB, email, or internal networks - Security - No external dependencies

Creating Offline Bundles

Using the Build Script

We provide a comprehensive build script that creates offline documentation bundles:

# Run the offline build script
./scripts/build-offline-docs.sh

This script: 1. Builds the complete site with PDF export 2. Optimizes HTML for offline viewing 3. Creates both ZIP and TAR.GZ archives 4. Generates checksums for verification 5. Includes a user-friendly index page

Manual Process

For manual offline bundle creation:

# 1. Enable PDF export and build
export ENABLE_PDF_EXPORT=1
mkdocs build

# 2. Create offline directory
mkdir -p offline-docs
cp -r site/* offline-docs/

# 3. Create archive
zip -r mkdocs-offline.zip offline-docs/

Offline Features

Supported Features

Feature	Support	Notes
HTML Navigation	✅ Full	All internal links work
PDF Export	✅ Full	Complete PDF included
Images	✅ Full	All images embedded
Code Examples	✅ Full	Syntax highlighting preserved
Downloads	✅ Full	Notebook downloads work
Print Styles	✅ Full	Optimized for printing

Limited Features

Feature	Limitation	Workaround
Search	Browser only	Use Ctrl+F
External Links	No internet	Include relevant content
Videos	Placeholder only	Provide descriptions
Live Examples	Static only	Include screenshots
Comments	Not available	Include contact info

Optimization Techniques

1. Asset Embedding

Ensure all assets are embedded:

# mkdocs.yml
theme:
  features:
    - navigation.instant  # Disable for offline

extra_css:
  - assets/stylesheets/offline.css

2. Offline CSS

Create specific offline styles:

/* assets/stylesheets/offline.css */

/* Hide online-only features */
.online-only {
    display: none !important;
}

/* Show offline notices */
.offline-notice {
    display: block !important;
    background: #ff9800;
    padding: 1rem;
    text-align: center;
}

/* Disable external link icons */
a[href^="http"]:after {
    content: " (external link)";
    font-size: 0.8em;
    color: #666;
}

3. JavaScript Modifications

Handle offline scenarios in JavaScript:

// Check if offline
if (!navigator.onLine) {
    document.body.classList.add('offline-mode');

    // Disable features that require internet
    document.querySelectorAll('.requires-internet').forEach(el => {
        el.style.display = 'none';
    });
}

Distribution Methods

1. USB/Physical Media

Perfect for conferences or secure environments:

# Create USB-friendly bundle
./scripts/build-offline-docs.sh

# Copy to USB (example for Linux)
sudo cp build/mkdocs-offline-*.zip /media/usb/

2. Internal Networks

Host on local servers:

# nginx configuration
server {
    listen 80;
    server_name docs.internal;
    root /var/www/offline-docs;
    index offline-index.html;
}

3. Email Distribution

For smaller docs or sections:

# Create minimal bundle
mkdocs build --no-directory-urls
zip -r docs-minimal.zip site/ -x "*/videos/*" "*/large-files/*"

4. Download Portal

Provide a download page:

<!-- download.html -->
<div class="download-options">
    <h2>Download Documentation</h2>

    <div class="download-card">
        <h3>Full Bundle (Recommended)</h3>
        <p>Complete documentation with all features</p>
        <a href="/downloads/full-bundle.zip" class="download-btn">
            Download ZIP (45 MB)
        </a>
    </div>

    <div class="download-card">
        <h3>PDF Only</h3>
        <p>Single PDF file for printing</p>
        <a href="/downloads/docs.pdf" class="download-btn">
            Download PDF (12 MB)
        </a>
    </div>

    <div class="download-card">
        <h3>Minimal HTML</h3>
        <p>Text-only version</p>
        <a href="/downloads/minimal.zip" class="download-btn">
            Download ZIP (5 MB)
        </a>
    </div>
</div>

Offline Index Page

Create a user-friendly landing page for offline users:

<!DOCTYPE html>
<html>
<head>
    <title>Offline Documentation</title>
    <meta charset="utf-8">
    <style>
        /* Embedded styles for offline use */
        body {
            font-family: system-ui, sans-serif;
            max-width: 1200px;
            margin: 0 auto;
            padding: 2rem;
        }
        .offline-header {
            background: #f5f5f5;
            padding: 2rem;
            border-radius: 8px;
            margin-bottom: 2rem;
        }
        .navigation-grid {
            display: grid;
            grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
            gap: 1rem;
        }
        .nav-card {
            border: 1px solid #ddd;
            padding: 1.5rem;
            border-radius: 4px;
            transition: box-shadow 0.3s;
        }
        .nav-card:hover {
            box-shadow: 0 4px 8px rgba(0,0,0,0.1);
        }
    </style>
</head>
<body>
    <div class="offline-header">
        <h1>📚 Offline Documentation</h1>
        <p>Welcome to the offline version. All content is available locally.</p>
        <p><strong>Generated:</strong> <span id="date"></span></p>
    </div>

    <div class="navigation-grid">
        <div class="nav-card">
            <h3>📖 Browse Docs</h3>
            <p>Full HTML documentation</p>
            <a href="index.html">Open Documentation</a>
        </div>

        <div class="nav-card">
            <h3>📄 PDF Version</h3>
            <p>Complete guide in PDF</p>
            <a href="pdf/documentation.pdf">Open PDF</a>
        </div>

        <div class="nav-card">
            <h3>🔍 Quick Search</h3>
            <p>Use Ctrl+F to search</p>
            <a href="search-index.html">Search Index</a>
        </div>
    </div>

    <script>
        document.getElementById('date').textContent = new Date().toLocaleDateString();
    </script>
</body>
</html>

Testing Offline Functionality

Verification Checklist

Test your offline bundle thoroughly:

# 1. Extract the bundle
unzip mkdocs-offline-*.zip

# 2. Start a local server (Python)
cd offline-docs
python -m http.server 8000

# 3. Disable network (for testing)
# - Turn off WiFi/Ethernet
# - Or use browser dev tools

# 4. Test all features

Test Script

Automated testing for offline bundles:

#!/usr/bin/env python3
"""Test offline documentation bundle"""

import os
import zipfile
from pathlib import Path

def test_offline_bundle(bundle_path):
    """Verify offline bundle completeness"""

    tests_passed = 0
    tests_failed = 0

    # Extract and test
    with zipfile.ZipFile(bundle_path, 'r') as zip_ref:
        extract_dir = Path('test_extract')
        zip_ref.extractall(extract_dir)

        # Test 1: Check index files
        index_files = ['index.html', 'offline-index.html']
        for file in index_files:
            if (extract_dir / 'offline-docs' / file).exists():
                print(f"✅ {file} found")
                tests_passed += 1
            else:
                print(f"❌ {file} missing")
                tests_failed += 1

        # Test 2: Check PDF
        pdf_files = list((extract_dir / 'offline-docs' / 'pdf').glob('*.pdf'))
        if pdf_files:
            print(f"✅ PDF found: {pdf_files[0].name}")
            tests_passed += 1
        else:
            print("❌ No PDF found")
            tests_failed += 1

        # Test 3: Check for external resources
        html_files = (extract_dir / 'offline-docs').rglob('*.html')
        external_resources = 0

        for html_file in html_files:
            content = html_file.read_text()
            if 'http://' in content or 'https://' in content:
                # Check if it's a real external resource
                if not any(x in content for x in ['href="http', 'src="http']):
                    continue
                external_resources += 1

        if external_resources == 0:
            print("✅ No external resources found")
            tests_passed += 1
        else:
            print(f"⚠️  {external_resources} files contain external resources")
            tests_failed += 1

        # Clean up
        import shutil
        shutil.rmtree(extract_dir)

    # Summary
    print(f"\nTest Summary:")
    print(f"  Passed: {tests_passed}")
    print(f"  Failed: {tests_failed}")

    return tests_failed == 0

if __name__ == "__main__":
    import sys
    bundle = sys.argv[1] if len(sys.argv) > 1 else "mkdocs-offline.zip"
    success = test_offline_bundle(bundle)
    sys.exit(0 if success else 1)

Best Practices

1. Version Control

Include version information:

# In mkdocs.yml
extra:
  version: "1.2.3"
  build_date: "2024-01-15"

2. Size Optimization

Reduce bundle size:

• Compress images (use WebP/AVIF)
• Minify CSS/JavaScript
• Exclude unnecessary files
• Use efficient archive formats

3. Update Notifications

Inform users about updates:

<div class="version-notice">
    This offline bundle was generated on {{ build_date }}.
    Check online for updates at: https://docs.example.com
</div>

4. Accessibility

Ensure offline docs remain accessible:

• Include all alt text
• Preserve ARIA labels
• Maintain keyboard navigation
• Test with screen readers

Summary

Offline documentation extends your docs' reach and usability. With proper planning and tools, you can create comprehensive offline bundles that provide nearly the same experience as the online version.