Document Versions

Professional-grade version control and content recovery for ApostropheCMS. Never lose content again with automatic versioning, visual comparisons, and one-click restoration for all your pages and pieces.

Why Document Versions?

Mistakes happen. Rushed edits, an accidental deletion, miscommunication between teams, or a bulk update gone wrong can cause unnecessary stress and cost hours of work. Document Versions is enterprise-level version control built specifically for ApostropheCMS that provides the safety net and accountability content teams need.

Key Benefits

• 🛡️ Risk-Free Content Management - Every published change is automatically saved, so your team can edit confidently
• ⚡ Instant Recovery - Restore any document to any previous version with a single click
• 👀 Visual Comparisons - See what changed between versions with side-by-side differential views
• 📊 Change Tracking - Monitor content evolution with detailed edit counts and author attribution
• 🌐 Multi-language Support - Full compatibility with ApostropheCMS localization features
• 🎯 Zero Configuration - Works automatically once installed - no complex setup required

Business Value

• Reduce Content Risk - Eliminate the fear of making changes that could break your site
• Increase Team Productivity - Content editors work faster when they know mistakes are easily reversible
• Audit Trail - Meet compliance requirements with complete change history and author tracking
• Cost Savings - Avoid expensive content creator time recreating lost content
• Peace of Mind - Sleep better knowing your content is always recoverable

Installation

Install the Document Versions module in your ApostropheCMS project:

npm install @apostrophecms-pro/document-versions

Quick Start

Add the module to your app.js file:

import apostrophe from 'apostrophe';

export default apostrophe({
  root: import.meta,
  shortName: 'my-project',
  modules: {
    '@apostrophecms-pro/document-versions': {}
  }
});

That's it! Document versions will automatically start being created for all your published content. No additional configuration needed.

How It Works

Document Versions seamlessly integrates into your existing ApostropheCMS workflow:

1. Automatic Version Creation - Every time content is published (created or updated), a version is automatically saved
2. Access Version History - Right-click any document and select "Document Versions" from the context menu
3. Browse and Compare - View past versions, see what changed, and compare any two versions side-by-side
4. One-Click Restore - Select any previous version and restore it to your draft with a single click

Using Document Versions

Accessing Version History

1. Navigate to any page or piece in your ApostropheCMS admin
2. Right-click the document or use the context menu (three vertical dots)
3. Select "Document Versions"
4. The version history modal opens, showing all past versions

Understanding the Version Interface

The version interface has three main areas:

• Left Sidebar - Field groups for easy navigation through your document schema
• Center Panel - Document content preview (read-only)
• Right Sidebar - Chronological list of all versions with dates, authors, and change counts

Comparing Versions

Document Versions includes powerful comparison tools to help you understand exactly what changed:

1. Enable Comparison Mode - Click "View Options" → Toggle "Compare versions"
2. Side-by-Side View - The center panel splits to show two versions simultaneously
3. Highlight Changes - Modified fields are automatically highlighted
4. Filter Differences - Toggle "Only show differences" to see only changed fields

Restoring Previous Versions

1. Select Version - Click any version in the right sidebar to preview it
2. Review Changes - Use comparison mode to verify this is the version you want
3. Restore - Click the "Restore" button in the top-right corner
4. Publish - The content is restored to draft - remember to publish your changes

✅ Safe Restoration: Restoring a previous version is completely non-destructive. Your entire version history remains intact, and the restored content becomes a new version at the top of your history. You can always restore back to any other version if needed.

⚠️ Important: Restoring creates a new draft. You must manually publish to make the restored content live.

Content Type Configuration

Which Documents Get Versioned?

By default, Document Versions tracks:

• All pages (unless explicitly disabled)
• All pieces with localized: true (the default)
• Any document type with versions: true

What's Not Versioned

Document Versions automatically excludes:

• Document types with versions: false
• Document types with autopublish: true (unless versions: true is also set)
• Document types with localized: false (like the core Users piece)
• Archived documents

Enabling Versions for Specific Types

// In your piece or page type module
export default {
  options: {
    versions: true// Explicitly enable versions
  }
// ... rest of your configuration
};

Disabling Versions

// In your piece or page type module
export default {
  options: {
    versions: false// Explicitly disable versions
  }
// ... rest of your configuration
};

Advanced Configuration

While Document Versions works perfectly out of the box, you can customize date formatting and localization to match your team's preferences.

Custom Date and Time Display

Starting with version 3.0, Document Versions uses the native Intl.DateTimeFormat API for superior internationalization support:

export default apostrophe({
  root: import.meta,
  shortName: 'my-project',
  modules: {
    '@apostrophecms-pro/document-versions': {
      options: {
// Customize how dates appear in the version
        listdateTimeFormatOptions: {
          year: 'numeric',
          month: 'long',
          day: '2-digit',
          hour: '2-digit',
          minute: '2-digit',
          second: '2-digit',
          timeZone: 'America/New_York'
        },
// Map your ApostropheCMS locales to specific regional
        formatslocaleMapping: {
          en: 'en-US',
          fr: 'fr-CA',
          es: 'es-MX'
        }
      }
    }
  }
});

Date Format Examples

// Compact format: "Jul 30, 25 at 2:30 PM"
dateTimeFormatOptions: {
  year: '2-digit',
  month: 'short',
  day: 'numeric',
  hour: 'numeric',
  minute: '2-digit'
}

// European format: "30/07/2025, 14:30"
dateTimeFormatOptions: {
  year: 'numeric',
  month: '2-digit',
  day: '2-digit',
  hour: '2-digit',
  minute: '2-digit',
  hour12: false
}

// Full format: "Wednesday, July 30, 2025 at 2:30:45 PM EDT"
dateTimeFormatOptions: {
  weekday: 'long',
  year: 'numeric',
  month: 'long',
  day: 'numeric',
  hour: 'numeric',
  minute: '2-digit',
  second: '2-digit',
  timeZoneName: 'short'
}

Regional Formatting

The localeMapping option ensures dates display according to your preferred regional conventions:

localeMapping: {
  en: 'en-US',// American English formatting
  fr: 'fr-CA',// Canadian French formatting
  es: 'es-MX',// Mexican Spanish formatting
  de: 'de-DE'// German formatting
}

Migrating from Version 2.x

Breaking Change: Version 3.0 replaced day.js with native Intl.DateTimeFormat for better multilingual formatting.

If you used the versionDayjsTitleFormat translation key, migrate to dateTimeFormatOptions:

// ❌ Old (no longer supported)
versionDayjsTitleFormat: 'MMM D, YYYY [at] h:mm A'
// ✅ New
dateTimeFormatOptions: {
  year: 'numeric',
  month: 'short',
  day: 'numeric',
  hour: 'numeric',
  minute: '2-digit',
  hour12: true
}

Professional Features

Audit Trail and Compliance

Every version includes:

• Timestamp - Exact creation date and time
• Author Attribution - Username or display name of the person who made changes
• Change Count - Number of fields modified in that version
• Complete Content Snapshot - Full document state at that point in time

Multi-language Support

Full compatibility with ApostropheCMS localization:

• Per-Locale Versioning - Each language maintains its own version history
• Locale-Aware Restoration - Restore content without affecting other languages
• Regional Date Formatting - Dates display according to each locale's conventions

API Access

REST API Endpoints

Document Versions provides REST API access for custom integrations:

// Get all versions for a document
GET /api/v1/@apostrophecms-pro/document-versions?docId=page123:en:published

// Get a specific version
GET /api/v1/@apostrophecms-pro/document-versions/version456

// Compare two versions
GET /api/v1/@apostrophecms-pro/document-versions/compare/version123/version456

Programmatic Access

// In your custom module
const versions = await self.apos.modules['@apostrophecms-pro/document-versions']
  .find(req, { docId: 'page123:en:published' });

// Create a version manually
await self.apos.modules['@apostrophecms-pro/document-versions']
  .createFor(req, document);

Use Cases

Content Marketing Teams

"Our content team can now experiment with copy changes without fear. If a new headline doesn't perform well, we can revert to the previous version instantly."

Enterprise Websites

"During our website redesign, Document Versions let us track every change and quickly rollback problematic updates without losing work."

Multi-Author Publications

"With multiple writers and editors, Document Versions provides the audit trail we need to understand how articles evolve and who made specific changes."

E-commerce Sites

"Product descriptions change frequently. Document Versions ensures we can always recover if an update accidentally removes important information."

Support and Documentation

• Full ApostropheCMS Documentation - docs.apostrophecms.org
• Community Support - Discord Community
• Professional Support - Available with ApostropheCMS Pro subscriptions
• Issue Reporting - GitHub Issues

Why ApostropheCMS Pro?

Document Versions is part of ApostropheCMS Pro, our enterprise-ready platform that includes:

• Advanced Security - Enterprise authentication, role-based permissions, audit logging
• Performance Tools - Caching, optimization, monitoring, and scaling features
• Workflow Management - Content approval processes, scheduled publishing, collaboration tools
• Professional Support - Priority support, training, and consulting services

Learn more about ApostropheCMS Pro and how it can transform your content management workflow.

Ready to track your content? Install Document Versions today and never worry about losing important changes again.