Markdown Sync

Markdown Sync publishes a local directory of Markdown pages into a root-site page hierarchy. The source directory remains authoritative; the receiving tinymash site stores normal pages and revisions below an entry point chosen by its superadmin.

It is one-way page synchronization. It does not clone users, settings, themes, plugins, menus, posts, author spaces, or media libraries.

Source layout

Each directory contains one index.md. The root file declares the collection ID and format. Every page has a stable ID:

---
id: example-docs-root
title: Documentation
collection: example-public-docs
format: 1
status: published
---

Documentation starts here.

Child pages normally add order, summary, and status. Keep IDs stable when moving or renaming source directories; the ID is what lets the receiver recognize the existing page.

Relative links to another page in the collection are validated and rewritten below the receiver's selected entry point. Root-relative and external links remain explicit destinations.

Receiver connection

A superadmin enables Markdown Sync, selects an existing root page as the entry point, and creates a connection token. The token is shown once and can be disabled, rotated, or deleted when unused.

The sender cannot choose another destination. A token can affect only its selected entry point and pages managed by that connection.

Store the receiver URL and token in an owner-readable profile outside the collection and source control:

{
  "receiver_url": "https://example.com",
  "token": "tms1.connection-id.secret"
}

On Unix-like systems, set mode 600.

Plan and push

php8.4 bin/tinymash.php markdown-sync plan site-docs --profile=.markdown-sync.json
php8.4 bin/tinymash.php markdown-sync push site-docs --profile=.markdown-sync.json

Plan reports creates, updates, moves, unchanged pages, stale mappings, and conflicts without applying content changes. Push applies a conflict-free plan as one locked batch. Handled content or connection-state failures restore the entry snapshots before the error is returned.

Pages missing from the source are retained unless --prune is supplied. Prune moves stale managed pages to Trash; it does not hard-delete them. Unmanaged pages below the entry point are untouched.

HTTP Basic authentication

When the whole receiver is protected by HTTP Basic authentication, add a separate http_basic object to the profile. Markdown Sync sends that web-server credential separately from its scoped connection token. The receiver endpoints do not need an authentication exception.