Skip to content

Latest commit

 

History

History
137 lines (100 loc) · 4.13 KB

Setup.md

File metadata and controls

137 lines (100 loc) · 4.13 KB

The setup wizard is invoked by :Obsidian sync setup, :ObsidianSync (when no vaults are linked), or automatically on first launch.

WebDAV / Nextcloud

Configure rclone sync for my-vault
  1. WebDAV / Nextcloud (connect directly)
  2. S3 / S3-compatible (connect directly)
  3. Use an existing rclone remote
  4. Run rclone config to add a new remote
  5. Sync with a local folder (two-way)

Choose 1 → pick server type:

Select WebDAV server type
  1. Nextcloud / ownCloud
  2. Generic WebDAV

Nextcloud/ownCloud auto-sets vendor = nextcloud for rclone. Then enter credentials:

WebDAV URL: https://my-nextcloud.example.com/remote.php/dav/files/user/MyVault/
Username:    myuser
Password:    ********

The plugin runs internally:

rclone config create obsidian-sync-my-vault webdav \
  url=... user=... pass=... vendor=nextcloud --non-interactive --obscure

The password is written to ~/.config/rclone/rclone.conf obscured (not plaintext). It never appears in Neovim's data files.

Optionally enter a sub-path if your vault lives inside a folder on the WebDAV root:

Remote sub-path (e.g. vault/main, <CR> for root):

Finally:

Linked my-vault <-> obsidian-sync-my-vault:
Start syncing now?  Yes

The mapping is persisted to stdpath("data")/obsidian-sync.json.

S3 / S3-compatible

Choose 2 → pick server type:

Select S3 server type
  1. S3-compatible (SeaweedFS, MinIO, Garage, R2, ...)
  2. AWS S3

For S3-compatible servers enter the endpoint URL; for AWS S3 the endpoint question is skipped. Then enter the region (default us-east-1), access key ID, secret access key and the bucket name:

Endpoint URL (e.g. https://s3.example.com): https://s3.home.example.com
Region (<CR> for us-east-1):
Access key ID:                                <access key>
Secret access key:                            ********
Bucket name:                                  my-vault

The plugin runs internally:

rclone config create obsidian-sync-my-vault s3 \
  provider=Other env_auth=false endpoint=... region=us-east-1 \
  access_key_id=... secret_access_key=... no_check_bucket=true \
  --non-interactive --obscure

The secret is written to ~/.config/rclone/rclone.conf obscured, exactly like the WebDAV password.

no_check_bucket=true is set unconditionally: credentials scoped to a single bucket on self-hosted S3 servers (SeaweedFS, Garage) deny HeadBucket, and rclone then aborts every upload with Access Denied. On AWS the flag only saves one transaction per sync.

Finally the optional sub-path — the vault is linked to remote:bucket/sub:

Remote sub-path (e.g. vault/main, <CR> for bucket root):

Existing rclone remote

If you already have remotes in rclone.conf (S3, SFTP, etc.), pick 3:

Select rclone remote
  mys3:
  backup-webdav:

Choose a remote, then optionally enter a sub-path. The vault is linked to remote:path.

Local folder

Pick 5 → enter an absolute path. Two-way sync between two local directories. Useful for testing, or syncing with an external drive.

First-run auto-wizard

When the plugin loads and no vaults are linked (empty obsidian-sync.json), it shows a dialog on VimEnter:

┌────────────────────────────────────────┐
│  obsidian-sync: No vaults linked yet.  │
│  Run the setup wizard now?             │
│                                        │
│  Yes  ← (default)                      │
│  No                                    │
└────────────────────────────────────────┘

For lazy-loaded obsidian.nvim (ft = "markdown"), the wizard fires on User ObsidianWorkpspaceSet — i.e. when you first open a .md file.

Answering No shows a hint: Run :ObsidianSync or :Obsidian sync setup later.