public/obsidian-livesync
1
0
Fork 0
mirror of https://github.com/vrtmrz/obsidian-livesync.git synced 2026-08-28 22:37:08 +00:00
Code Issues Packages Projects Releases Wiki Activity

Reorganise settings around common tasks

Browse Source
This commit is contained in:
vorotamoroz
2026-08-25 05:34:57 +00:00
parent 8adc88b8cb
commit 070ce0e307
26 changed files with 1206 additions and 417 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/adr/2026_08_declarative_settings_adapter.md
+96 -21
View File
@@ -1,5 +1,5 @@
---
date: 2026-08-24
date: 2026-08-25
commonlib-version: "0.1.19"
self-hosted-livesync-version: "1.0.18"
status: accepted
@@ -9,10 +9,10 @@ status: accepted
## Status
Accepted and implemented through Stage C1. The implementation is deliberately
limited to one-key, immediately persisted controls and one proof page. It does
not attempt to describe every existing settings interaction through a new
abstraction. Stage C2 remains an optional, page-by-page improvement.
Accepted and implemented through Stage C1 and two bounded Stage C2
landing-page improvements. The shared specification remains deliberately
limited to one-key, immediately persisted controls. Complex pages retain their
existing renderers instead of being forced through a general abstraction.
## Context
@@ -42,7 +42,7 @@ responsibilities:
which run after a successful save.
These responsibilities are not all declarative setting data. In particular,
Remote Configuration, Hatch, Maintenance, Setup, and Selector contain dynamic
Remote Configuration, Hatch, Maintenance, Help, and Selector contain dynamic
lists, Svelte components, diagnostic results, multi-step actions, and
destructive confirmations. Encoding those interactions in a general settings
DSL would increase the abstraction before a second renderer had proved which
@@ -140,6 +140,51 @@ by the catalogue, while the imperative renderer continues to pass the same
emoji to its existing menu button. This preserves the established visual
identity without adding host-DOM manipulation.
### Compose the native landing page around common tasks
The declarative root is a composition of native groups and catalogue pages,
not a second flat copy of the legacy tab menu. General Settings contains the
native Appearance, Logging, and Extra menus child pages. Their standard
`SettingSpec` controls remain searchable without crowding the root. The small
Quick Setup actions are native action rows on the root. The old Setup child
page is not retained: its feature-level controls move to Extra menus, its full
reset moves to Maintenance, and its online guidance becomes Help and
troubleshooting. The pane-based interface exposes Quick Setup as a pane and
renders the same controls within General Settings.
Remote Configuration and Sync Settings remain catalogue pages. Obsidian's
native group contract permits navigable pages as group items, so both pages are
placed inside an explicit Synchronisation group. This keeps them near the top
for narrow mobile displays while preventing the unheaded page entries from
appearing to continue the preceding Quick Setup group. The root order reflects
the current task:
| Current state | First root sections |
| --------------------------- | ----------------------------------------------------------------------------------- |
| Synchronisation is inactive | Quick Setup, Synchronisation (Remote Configuration and Sync Settings), then General |
| Synchronisation is active | Synchronisation (Remote Configuration and Sync Settings), General, then Quick Setup |
Set up other devices follows the Quick Setup and General groups when the
plug-in is configured. The remaining destinations are grouped explicitly:
| Group | Pages |
| ------------------------ | ---------------------------------------- |
| Maintenance and recovery | Maintenance and Hatch |
| Extra features | Selector and Customisation sync |
| Advanced settings | Advanced, Power users, and Patches |
| Help and information | Help and troubleshooting, and Change Log |
This prevents Obsidian from presenting them as one undifferentiated 'Detailed
settings' continuation. Changing a setting which can move or reveal a page
requests a catalogue refresh after persistence. External setting reloads use
the same boundary. Constructing the definitions still performs no persistence,
service, file, database, or network operation.
The imperative renderer retains its existing default-page selection: Quick Setup for
an inactive configuration and General for an active configuration. The landing
composition is therefore a native 1.13 improvement rather than a behaviour
change for earlier supported Obsidian versions.
The custom `SettingPage` adapter class will be constructed lazily from the
1.13-or-later path. `SettingPage` may remain a normal runtime import because the
bundle reads Obsidian exports through its namespace object, but the import must
@@ -267,8 +312,7 @@ custom row or custom page:
- password inputs;
- a control which maps one displayed value to several stored keys, such as
`syncMode`;
- a control with an `onSaved` service, event, restart, rebuild, or re-render
effect;
- a control whose save effect cannot remain an explicit tab-owned handler;
- button clusters, dynamic lists, Svelte components, rich diagnostic output,
or destructive actions; and
- styling which exists only to support the old wizard or tab menu.
@@ -375,10 +419,11 @@ unrelated workflows:
- configuration-level page visibility.
It has no current `onSaved` handler, Svelte component, staged Apply group, or
destructive action. General is not the first proof because changing the display
language re-renders the interface and other controls emit status events after
saving. Those effects should remain imperative until the standard binding has
been proven.
destructive action. General was not the first proof because changing the
display language re-renders the interface and other controls emit status events
after saving. After the standard binding was proven, these effects remained
explicit, tab-owned saved handlers while their one-key controls adopted
`SettingSpec`.
The first native activation does not also divide other pages into searchable
rows. It exposes their established pane renderers as custom pages, limited to
@@ -438,8 +483,13 @@ smaller.
After activation, an individual custom page may be replaced with native groups,
actions, and rendered rows where the existing panel boundary maps cleanly to
Obsidian's definitions. This is optional follow-up work rather than a condition
of Stage C1. Complex workflows may remain custom pages indefinitely.
Obsidian's definitions. The bounded improvement converts the General and
Logging controls and the simple Quick Setup actions, then organises Appearance,
Logging, and Extra menus as child pages of General Settings. It also removes
the now-misleading Setup child page and assigns its remaining responsibilities
to their existing owners: Extra menus, Maintenance, and Help and
troubleshooting. Further conversions remain optional follow-up work rather than
a condition of Stage C1. Complex workflows may remain custom pages indefinitely.
Stage C2 must not introduce a general action or lifecycle language. Each page
conversion should be justified by useful settings-search coverage and retain
@@ -461,12 +511,21 @@ Stage B focused unit tests verify:
- rendering the Advanced specifications through `LiveSyncSetting` preserves
the current save behaviour.
Stage C1 focused unit tests verify:
Stage C1 and the landing-page focused unit tests verify:
- the page catalogue contains all 12 existing pages with stable, unique
- the page catalogue contains all 13 pane-based destinations with stable, unique
identifiers and names;
- Advanced is the only native-items page, while the other 11 pages retain
custom factories;
- Appearance, Logging, Extra menus, and Advanced are native-items child pages,
and ten child pages retain custom factories;
- inactive and active configurations use their specified landing-page order;
- Remote Configuration and Sync Settings remain native navigable pages inside
the separate Synchronisation group;
- maintenance, extra features, advanced settings, and help have explicit page
groups, and the old Setup child page is absent;
- all eight General and Logging controls are registered once, with their
existing conditional visibility;
- the three Extra menus controls are registered once and refresh page
visibility after persistence;
- every standard setting key is registered once;
- reads use the editing buffer;
- writes use `saveSettings([key])` and never `plugin.settings`;
@@ -477,7 +536,11 @@ Stage C1 focused unit tests verify:
Real-Obsidian verification on 1.13 or later confirms:
- native page navigation opens every page;
- the common landing controls and actions render before native page navigation;
- the Quick Setup action opens the maintained onboarding dialogue;
- Remote Configuration remains visible without initial scrolling in mobile
test mode;
- native page navigation opens every remaining child page;
- Advanced controls appear in global settings search;
- Advanced values persist and are restored after reopening settings;
- CouchDB-dependent controls and Advanced-mode visibility update correctly;
@@ -506,7 +569,7 @@ runtime and accessible native page names on 1.13 or later. Individual scenarios
must not duplicate version checks or retain selectors for a menu which the
declarative renderer does not create.
The accepted implementation was exercised against the official Obsidian
The initial Stage C1 implementation was exercised against the official Obsidian
1.13.4 arm64 AppImage with SHA-256
`20d0b13c6d40bb3d7e73d9b4be6d2e21dfcc145b2106a747d0c1b81e651dabfe`.
That run opened all 12 pages from the native page catalogue, found the Advanced
@@ -518,6 +581,18 @@ persistence of the same Advanced value. The shared E2E navigator owns both the
separate settings renderer used by Obsidian 1.13 and the legacy
`.sls-setting-menu-btn` interface.
The Stage C2 landing composition was then exercised on Obsidian 1.13.4. With
synchronisation inactive, the real interface rendered Quick Setup, a separate
Synchronisation group containing Remote Configuration and Sync Settings, and a
General Settings group containing Appearance, Logging, and Extra menus in the
specified order. It opened all 14 nested settings pages, found the Advanced
control through global settings search, and restored its saved value after
reopening settings. In mobile test mode, Remote Configuration remained inside
the initial viewport below the two Quick Setup actions and the Synchronisation
heading. The complete scenario also passed with the same bundle on Obsidian
1.12.7, confirming that the imperative fallback retained its navigation and
save behaviour.
## Expansion Checkpoints
Review the scope with the maintainer before any implementation adds one of the
@@ -529,7 +604,7 @@ following:
- a replacement for the current onboarding workflow;
- a Commonlib setting metadata contract change;
- a minimum Obsidian version increase; or
- conversion of Remote Configuration, Hatch, Maintenance, Setup, or the
- further conversion of Remote Configuration, Hatch, Maintenance, Help, or the
Svelte-based Selector controls.
These may become worthwhile after the first proof, but none is required to
docs/settings.md
+28 -16
View File
@@ -4,6 +4,19 @@ NOTE: This document not completed. I'll improve this doc in a while. but your co
There are many settings in Self-hosted LiveSync. This document describes each setting in detail (not how-to). Configuration and settings are divided into several categories and indicated by icons. The icon is as follows:
On Obsidian 1.13 or later, the root settings page is organised by task. When synchronisation is inactive, **Quick Setup** appears first. Once any synchronisation mode is active, **Synchronisation** and **General Settings** move ahead of **Quick Setup**. **Set up other devices** appears after this plug-in has been configured. Earlier supported Obsidian versions retain a pane-based interface with the same controls.
| Icon | Root group | Contents or availability |
| :--: | ------------------------ | ------------------------------------------------------------- |
| 🧙‍♂️ | Quick Setup | Setup URI, onboarding, and enable actions |
| 🔄 | Synchronisation | Remote Configuration and Sync Settings |
| ⚙️ | General Settings | Appearance, Logging, and Extra menus |
| 📲 | Set up other devices | Copy a Setup URI or show its QR code after configuration |
| 🛠️ | Maintenance and recovery | Maintenance and Hatch |
| 🧩 | Extra features | Selector and Customisation sync when advanced features appear |
| 🔧 | Advanced settings | Advanced, Power users, and Patches when their modes appear |
| ℹ️ | Help and information | Help and troubleshooting, and Change Log |
## Feature maturity for 1.0
The following status applies to optional and compatibility features in the 1.0 line:
@@ -18,7 +31,7 @@ The following status applies to optional and compatibility features in the 1.0 l
| Icon | Description |
| :--: | ------------------------------------------------------------------ |
| 💬 | [0. Change Log](#0-change-log) |
| 🧙‍♂️ | [1. Setup](#1-setup) |
| 🧙‍♂️ | [1. Quick Setup and Extra menus](#1-quick-setup-and-extra-menus) |
| ⚙️ | [2. General Settings](#2-general-settings) |
| 🛰️ | [3. Remote Configuration](#3-remote-configuration) |
| 🔄 | [4. Sync Settings](#4-sync-settings) |
@@ -34,17 +47,19 @@ The following status applies to optional and compatibility features in the 1.0 l
This pane always shows the current release history. It does not track whether a particular plug-in version has been read and does not open automatically after an ordinary update.
Internal database or settings compatibility reviews use a separate safety dialogue, not this pane. The dialogue explains why remote synchronisation has been paused and preserves the automatic synchronisation choices which were configured before the update. A configured Vault which was copied, restored, or opened in a new Obsidian profile can require this review because its device-local acknowledgement is not part of the Vault data. An empty local database is not accepted as evidence that it is safe to continue. An existing unconfigured Vault remains in onboarding without this synchronisation warning; its missing acknowledgement is not filled in automatically, so it is evaluated if the Vault is configured later. Closing the dialogue keeps synchronisation paused. When the detected state can be handled by the running version, the explicit resume action records the current internal database version and restores the configured behaviour. A persistent Notice and the `Review why synchronisation is paused` command reopen the review. An older installation cannot dismiss a pause caused by a newer database or settings version.
Internal database or settings compatibility reviews use a separate safety dialogue, not this pane. After the Obsidian layout is ready, a pending review opens as **Synchronisation paused for compatibility review**. The dialogue explains why remote synchronisation has been paused and preserves the automatic synchronisation choices which were configured before the update. Closing it or selecting **Keep synchronisation paused** leaves synchronisation paused. Use the persistent Notice's **Review why** link, or run the `Review why synchronisation is paused` command, to reopen it. Opening **Change Log** does not acknowledge the review.
## 1. Setup
A configured Vault which was copied, restored, or opened in a new Obsidian profile can require this review because its device-local acknowledgement is not part of the Vault data. An empty local database is not accepted as evidence that it is safe to continue. An existing unconfigured Vault remains in onboarding without this synchronisation warning; its missing acknowledgement is not filled in automatically, so it is evaluated if the Vault is configured later. When the detected state can be handled by the running version, **Resume synchronisation** records the current internal database version and restores the configured behaviour. An older installation cannot dismiss a pause caused by a newer database or settings version.
This pane is used for setting up Self-hosted LiveSync. There are several options to set up Self-hosted LiveSync.
## 1. Quick Setup and Extra menus
An unconfigured installation does not open the onboarding dialogue automatically or scan the Vault into the local database. A long-lived Notice offers the onboarding action. If the Notice is dismissed, open **Self-hosted LiveSync settings** → **Setup** → **Rerun Onboarding Wizard**.
Quick Setup contains the actions used to configure Self-hosted LiveSync. On Obsidian 1.13 or later these actions appear on the root settings page. In the pane-based interface, they remain available together on the **Quick Setup** pane.
An unconfigured installation does not open the onboarding dialogue automatically or scan the Vault into the local database. A long-lived Notice offers the onboarding action. If the Notice is dismissed, use **Rerun Onboarding Wizard** in the root **Quick Setup** group on Obsidian 1.13 or later. On earlier supported Obsidian versions, open **Self-hosted LiveSync settings** → **Quick Setup** → **Rerun Onboarding Wizard**.
Choose the new-device path when this device owns the files which should initialise synchronisation. Choose the existing-device path when it should receive an established remote state. The wizard reserves Rebuild or Fetch respectively before enabling the settings and requesting a restart, so the selected initialisation runs before the ordinary start-up scan.
### 1. Quick Setup
### 1. Setup actions
Most preferred method to setup Self-hosted LiveSync. You can setup Self-hosted LiveSync with a few clicks.
@@ -64,22 +79,15 @@ Completing manual CouchDB, Object Storage, or P2P setup creates the correspondin
This button only appears when the setup was not completed. If you have completed the setup manually, you can enable LiveSync on this device by this button.
### 2. To setup other devices
### 2. Set up other devices
#### Copy the current settings to a Setup URI
You can copy the current settings as a new setup URI. And this URI can be used to setup the other devices as [Use the copied setup URI](#use-the-copied-setup-uri).
### 3. Reset
### 3. Extra menus
#### Discard existing settings and databases
Reset the Self-hosted LiveSync settings and databases.
**Hazardous operation. Please be careful when using this.**
### 4. Enable extra and advanced features
To keep the set-up dialogue simple, some panes are hidden in default. You can enable them here.
To keep the settings dialogue concise, some menus and features are hidden by default. On Obsidian 1.13 or later, enable them through **General Settings** → **Extra menus**. In the pane-based interface, the same controls appear in General Settings.
#### Enable advanced features
@@ -1085,4 +1093,8 @@ Use it only when the Vault, local database, and remote are healthy, and every re
### 7. Reset
#### Discard existing settings and databases
Reset the Self-hosted LiveSync settings and local database. This is a hazardous operation; make a backup before using it.
#### Delete local database to reset or uninstall Self-hosted LiveSync
docs/troubleshooting.md
+8
View File
@@ -47,6 +47,14 @@ Do not switch to P2P or reset the database as the first response. Check:
If the remote is healthy but one device's local database is not, use [Reset Synchronisation on This Device](recovery.md#reset-synchronisation-on-this-device) only after backing up unsynchronised local files.
## Synchronisation is paused for compatibility review
A compatibility review is separate from the Change Log. It can appear after an internal database or settings-format change, or when a configured Vault is copied, restored, or opened in a new Obsidian profile without its device-local acknowledgement.
The **Synchronisation paused for compatibility review** dialogue opens after the Obsidian layout is ready. If it has been closed, use the persistent Notice's **Review why** link, or run `Review why synchronisation is paused` from the command palette. Opening **Change Log** does not clear the pause.
Review the stated reason before continuing. When **Resume synchronisation** is available, first update every synchronising device, then use that action to record the current internal database version and restore the configured synchronisation behaviour. If the action is unavailable, the running installation is older than the recorded database or settings format. Update that installation instead of resetting the database merely to remove the warning.
## Files are missing or excluded
Check Obsidian's `Detect all file extensions`, LiveSync selectors, ignore files, file-size limits, modification-time limits, and Hidden File Sync rules. A filtered file is different from a file which reached the database but could not be reconstructed from its chunks.