[6.x] Sidecar

[jackmcdade]

Sidecar: Edit external Markdown content with Statamic

Summary

Welcome to Sidecar: a new way to edit external Markdown content with Statamic.

Sidecar connects Statamic to an existing documentation site (like LaraDocs) or static site generator (like Jigsaw), turning its Markdown files into a native collection inside the Control Panel.

Content stays exactly where it is without any need to import, duplicate, or sync anything. No need to change how the original site is built. You just layer Statamic’s editing experience on top of it. It includes support for:

• Blueprints and custom fields
• Structure trees and drag-and-drop organization
• Live Preview
• User roles and permissions
• The full Statamic publishing experience

Why

Many teams already have documentation or content living in systems like LaraDocs or Jigsaw.

Those systems work well for developers, but editing raw Markdown, front matter, navigation files, and folder structures isn’t always a great experience for the rest of the team. And migrating to a whole new platform and learning a new front-end structure can be a barrier to entry that otherwise would be a happy integration.

Well, Sidecar bridges that gap.

Developers can keep the filesystem structure, tooling, and deployment workflow they already use. Editors get a polished, intuitive Control Panel for managing the same files.

That's a win/win/win. The legendary Triple Win.

How it works

Sidecar provides a common foundation for connecting Statamic collections to external content systems.

Each supported system has a small driver package that understands its particular conventions: where its content lives, how navigation works, how folders are structured, and how preview URLs should be generated.

This PR adds the core Sidecar framework. Individual integrations live in separate packages, including:

Package	Content model
statamic/sidecar-laradocs	Nested folders, _index.md files, and ordering via front-matter, manageable by the entries tree component
statamic/sidecar-jigsaw	Flat directory with hierarchy managed by navigation.php, manageable by the entries listing component

What this PR adds

External collections

A Sidecar driver can expose content from anywhere in the project as a Statamic collection.

The collection is registered dynamically, so it doesn’t require a corresponding YAML file inside content/collections.

Native content editing

Entries are read from and saved directly to their original files.

Existing front matter is preserved, including values Statamic doesn’t explicitly manage.
Note: Statamic may inject its own data into the front-matter (e.g. id to manage indexes).

Structure synchronization

For systems that use nested folders, reorganizing entries in Statamic’s structure tree updates the real filesystem structure.

Sidecar can:

• Move entries between folders
• Create and remove nested directories
• Convert between page.md and page/_index.md as convention dictates
• Keep sibling ordering in sync
• Clean up empty directories

Other drivers can manage hierarchy through their own navigation system instead.

Live Preview

Sidecar collections can provide Preview and Visit URLs even when the collection doesn’t have a traditional Statamic route.

This makes Live Preview available for documentation sites, static site generators, and other externally rendered content.

Blueprint fallbacks

Drivers can provide a default blueprint when the project doesn’t already contain one.

This allows a connected collection to work immediately while remaining fully customizable.

Guided installation

Sidecar can detect installed, compatible packages and configure the appropriate driver:

php please sidecar:install

You can also select one explicitly:

php please sidecar:install laradocs

Example

Install LaraDocs and its Sidecar driver:

composer require petebishwhip/laradocs statamic/sidecar-laradocs
php please sidecar:install laradocs

This produces a Sidecar collection configuration similar to:

// config/statamic/sidecar.php

'collections' => [
    'docs' => [
        'driver' => 'laradocs',
        'directory' => base_path('docs'),
    ],
],

The documentation files will then appear as a collection inside the Statamic Control Panel, ready to edit, organize, preview, and manage.

The original LaraDocs site continues to read and build those same files exactly as it did before.

Scope

This PR contains the core Sidecar framework and the underlying collection improvements it requires.

Concrete integrations, such as LaraDocs and Jigsaw support, are maintained as separate driver packages.

Sidecar is currently experimental while we validate the API and explore additional integrations.

Docs

Documentation is available here: statamic/docs#1958

Testing

• Running sidecar:install with no compatible packages installed
• Running sidecar:install with one compatible package installed
• Running sidecar:install with multiple compatible packages installed
• Sidecar collections appear in the Control Panel without collection YAML files
• Entries load from custom directories
• Saving entries preserves unknown front matter
• Reordering and nesting entries updates folder paths and ordering
• Empty directories are removed after moving entries
• Deleting a Sidecar collection does not delete its external content
• Live Preview and Visit URLs work without collection routes
• Existing collections and Stache behavior remain unchanged
• Multi-site collection behavior remains unchanged
• Sidecar and collection test suites pass