mirror of
https://github.com/uthvah/sync-embeds.git
synced 2026-07-22 06:43:40 +00:00
Revise README for improved clarity
Updated README to enhance clarity and add user trust metrics.
This commit is contained in:
Verity
GitHub
parent
a8e5ee3144
commit
a35f2e2c6f
1 changed files with 44 additions and 102 deletions
146
README.md
146
README.md
|
|
@ -1,9 +1,11 @@
|
|||
|
||||
<div align="center">
|
||||
|
||||
# ✨ Sync Embeds for Obsidian
|
||||
|
||||
### The missing Notion-style synced block for Obsidian.
|
||||
|
||||
[](#installation)
|
||||
[](https://github.com/uthvah/sync-embeds/releases/latest)
|
||||
[](https://github.com/uthvah/sync-embeds/blob/main/LICENSE)
|
||||
|
||||
|
|
@ -11,11 +13,11 @@
|
|||
|
||||
---
|
||||
|
||||
**Sync Embeds** transforms standard Obsidian embeds into live, two-way synced blocks. Edit any note or section directly from where you embed it, without ever needing to open the source file.
|
||||
**Sync Embeds** transforms standard Obsidian transclusions into live, editable, two-way synced blocks. Edit any note (or specific header section) directly from where you embed it, without ever needing to open the source file.
|
||||
|
||||
It's designed to feel seamless, stable, and completely native to the Obsidian experience.
|
||||
Trusted by over 14,000 users, it's designed to feel seamless, stable, and completely native to the Obsidian experience.
|
||||
|
||||
|
||||
https://github.com/user-attachments/assets/68d20937-b4a0-4790-9aa8-34f670e42893
|
||||
|
||||
> *Edit any embed, anywhere, and have it instantly save to the original note.*
|
||||
|
||||
|
|
@ -23,21 +25,20 @@ It's designed to feel seamless, stable, and completely native to the Obsidian ex
|
|||
|
||||
## Core Features
|
||||
|
||||
- 🔄 **Live Two-Way Syncing** — Edit an embed and see the changes reflected in the source note instantly. No more context switching.
|
||||
- ⌨️ **Full Keyboard Shortcut Support** — The #1 limitation is solved. Use all your familiar hotkeys for checkboxes, formatting, lists, and headers, directly within an embed.
|
||||
- 🎯 **Embed Specific Sections** — Isolate and edit just a single header section from a note using the standard `![[My Note#My Header]]` syntax. Perfect for managing tasks or project sections from a central dashboard.
|
||||
- 🎨 **Smart Header Management** — Section embeds automatically enforce header hierarchy. Use Alt+2-6 hotkeys to insert headers with intelligent restrictions.
|
||||
- 🚀 **Dynamic Patterns** — Create embeds that automatically update based on dates, times, or the current note title. Perfect for daily notes and project dashboards.
|
||||
- 🎭 **Custom Display Names** — Show friendly aliases instead of raw file paths for cleaner, more readable embeds.
|
||||
- ⚡ **Lightweight & Stable** — Built from the ground up to be robust, with lazy loading, smart caching, and a focus on performance.
|
||||
- 🔄 **Live "Two-Way Syncing"** — Edit an embed and see the changes reflected in the source note instantly. No "saving," no lag, no context switching.
|
||||
- ⌨️ **Full Keyboard Shortcut Support** — The #1 limitation of native embeds is solved. Use all your familiar hotkeys for checkboxes (`Ctrl/Cmd+L`), formatting (`Ctrl/Cmd+B/I`), lists, and headers, directly within an embed.
|
||||
- 🎯 **Section & Header Embeds** — Isolate and edit just a single section from a note using the standard `![[My Note#My Header]]` syntax. Perfect for managing active tasks from a central dashboard.
|
||||
- 🚀 **Dynamic Patterns (For Daily Notes)** — Create embeds that automatically update based on dates or note titles (e.g., `{{date}}`).
|
||||
- 🎨 **Smart Header Management** — Section embeds intelligently enforce header hierarchy to prevent your markdown structure from breaking.
|
||||
- 🎭 **Custom Display Names** — Show friendly aliases instead of raw file paths for cleaner, more readable page elements.
|
||||
|
||||
---
|
||||
|
||||
## How it Works
|
||||
|
||||
Instead of just rendering the content, Sync Embeds creates a hidden, fully functional editor pane for the source note. It then re-parents the visual part of that editor directly into your current document. This means you are interacting with a real editor instance, providing a truly native feel.
|
||||
Instead of just rendering a read-only preview, Sync Embeds creates a hidden, fully functional editor pane for the source note. It then seamlessly "re-parents" the visual part of that editor directly into your current document.
|
||||
|
||||
For section embeds, an intelligent viewport system restricts editing to only the target section while maintaining full synchronization with the source file.
|
||||
This means you are interacting with a *real* editor instance. When editing a specific section, an intelligent viewport system restricts editing to only the target header while maintaining full synchronization with the source file.
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -45,34 +46,30 @@ For section embeds, an intelligent viewport system restricts editing to only the
|
|||
|
||||
### From Community Plugins (Recommended)
|
||||
|
||||
_Coming Soon! This plugin is currently awaiting review to be added to the official Community Plugins browser._
|
||||
Sync Embeds is officially available in the Obsidian Community Store!
|
||||
|
||||
### Using BRAT (Beta)
|
||||
👉 ****
|
||||
|
||||
1. Install the [BRAT](https://github.com/TfTHacker/obsidian42-brat) plugin from the Community Plugins browser.
|
||||
2. In Obsidian, go to `Settings` → `BRAT` → `Add Beta plugin`.
|
||||
3. Enter `uthvah/sync-embeds` as the repository.
|
||||
4. BRAT will install the plugin. Enable it under `Settings` → `Community plugins`.
|
||||
|
||||
### Manual Installation
|
||||
*Or install manually via the app:*
|
||||
1. Open Obsidian **Settings** → **Community Plugins**.
|
||||
2. Click **Browse** and search for `Sync Embeds`.
|
||||
3. Click **Install**, then **Enable**.
|
||||
|
||||
### Manual Installation (GitHub)
|
||||
1. Go to the [latest release](https://github.com/uthvah/sync-embeds/releases/latest).
|
||||
2. Download the `main.js`, `manifest.json`, and `styles.css` files.
|
||||
2. Download `main.js`, `manifest.json`, and `styles.css`.
|
||||
3. In your Obsidian vault, navigate to `.obsidian/plugins/`.
|
||||
4. Create a new folder named `sync-embeds`.
|
||||
5. Copy the downloaded files into this new folder.
|
||||
6. Restart Obsidian, then enable the plugin under `Settings` → `Community plugins`.
|
||||
4. Create a new folder named `sync-embeds` and paste the downloaded files inside.
|
||||
5. Restart Obsidian, then enable the plugin under **Settings** → **Community plugins**.
|
||||
|
||||
---
|
||||
|
||||
## Usage
|
||||
|
||||
Using Sync Embeds is simple. Just wrap your standard embed syntax inside a `sync` code block.
|
||||
Using Sync Embeds is simple. Wrap your standard embed syntax inside a `sync` code block.
|
||||
|
||||
### Basic Synced Block
|
||||
|
||||
Use the `sync` code block language identifier:
|
||||
|
||||
````markdown
|
||||
```sync
|
||||
![[My Note To Edit]]
|
||||
|
|
@ -81,29 +78,17 @@ Use the `sync` code block language identifier:
|
|||
|
||||
### Embed a Specific Section
|
||||
|
||||
You can also embed just a single header section:
|
||||
Isolate and edit a specific header:
|
||||
|
||||
````markdown
|
||||
```sync
|
||||
![[My Note To Edit#A Specific Heading]]
|
||||
![[Project Alpha#Active Tasks]]
|
||||
```
|
||||
````
|
||||
|
||||
### Multiple Embeds
|
||||
### Dynamic Patterns (Automations)
|
||||
|
||||
Create dashboards by embedding multiple notes or sections:
|
||||
|
||||
````markdown
|
||||
```sync
|
||||
![[Daily Notes/2024-03-15|Today]]
|
||||
![[Daily Notes/2024-03-14|Yesterday]]
|
||||
![[Tasks#Inbox|My Tasks]]
|
||||
```
|
||||
````
|
||||
|
||||
### Dynamic Patterns
|
||||
|
||||
Create embeds that automatically adapt to the current context:
|
||||
Create embeds that automatically adapt to the current context. Perfect for templating!
|
||||
|
||||
````markdown
|
||||
```sync
|
||||
|
|
@ -113,15 +98,15 @@ Create embeds that automatically adapt to the current context:
|
|||
```
|
||||
````
|
||||
|
||||
**Available patterns:**
|
||||
- `{{date:FORMAT}}` — Current date in any format (e.g., `YYYY-MM-DD`, `DD MMM YYYY`)
|
||||
**Available dynamic variables:**
|
||||
- `{{date:FORMAT}}` — Current date (e.g., `YYYY-MM-DD`, `DD MMM YYYY`)
|
||||
- `{{date±Xu:FORMAT}}` — Date offsets: `d` (days), `w` (weeks), `m` (months), `y` (years)
|
||||
- `{{time:FORMAT}}` — Current time (e.g., `HH:mm`, `hh:mm A`)
|
||||
- `{{title}}` — Current note's title
|
||||
|
||||
### Custom Options
|
||||
|
||||
Override global settings for individual embeds:
|
||||
Override global settings for individual embeds right in the alias:
|
||||
|
||||
````markdown
|
||||
```sync
|
||||
|
|
@ -137,55 +122,20 @@ Override global settings for individual embeds:
|
|||
|
||||
---
|
||||
|
||||
## Smart Features
|
||||
## Use Cases & Inspiration
|
||||
|
||||
### Header Management
|
||||
|
||||
Use **Alt+2** through **Alt+6** to insert or toggle headers (H2-H6):
|
||||
- Press once on plain text → Convert to header
|
||||
- Press again on header → Remove formatting
|
||||
- Press different level → Change header level
|
||||
|
||||
In section embeds, header hierarchy is automatically enforced:
|
||||
- **H2 section** → Only H3-H6 allowed
|
||||
- **H3 section** → Only H4-H6 allowed
|
||||
|
||||
Typing `#` at the start of a line is intelligently blocked in section embeds to prevent hierarchy violations.
|
||||
|
||||
### Keyboard Shortcuts
|
||||
|
||||
All your favorite Obsidian shortcuts work inside embeds:
|
||||
- **Ctrl/Cmd+B** — Bold
|
||||
- **Ctrl/Cmd+I** — Italic
|
||||
- **Ctrl/Cmd+K** — Insert link
|
||||
- **Ctrl/Cmd+E** — Toggle checklist
|
||||
- **Alt+2-6** — Insert headers
|
||||
- And many more!
|
||||
|
||||
### Customization
|
||||
|
||||
Fine-tune appearance and behavior in **Settings → Sync Embeds**:
|
||||
- Embed height and maximum height
|
||||
- Gap between multiple embeds
|
||||
- Properties collapse behavior
|
||||
- Inline title visibility
|
||||
- Focus highlighting
|
||||
- Lazy loading threshold
|
||||
|
||||
---
|
||||
|
||||
## Use Cases
|
||||
|
||||
### Daily Note Dashboard
|
||||
### 1. The Daily Note Dashboard
|
||||
Keep your daily note clean while managing recurring items:
|
||||
````markdown
|
||||
```sync
|
||||
![[Daily/{{date:YYYY-MM-DD}}|📅 Today]]
|
||||
![[Daily/{{date-1d:YYYY-MM-DD}}|Yesterday]]
|
||||
![[Tasks#{{date:YYYY-MM-DD}}|Today's Tasks]]
|
||||
![[Master Tasks#{{date:YYYY-MM-DD}}|Today's Tasks]]
|
||||
```
|
||||
````
|
||||
|
||||
### Project Overview
|
||||
### 2. The Project Overview
|
||||
View and edit different parts of a large project from a single pane:
|
||||
````markdown
|
||||
```sync
|
||||
![[Projects/{{title}}#Overview|Summary{height:300px}]]
|
||||
|
|
@ -194,20 +144,6 @@ Fine-tune appearance and behavior in **Settings → Sync Embeds**:
|
|||
```
|
||||
````
|
||||
|
||||
### Meeting Notes
|
||||
````markdown
|
||||
```sync
|
||||
![[Meetings/{{date:YYYY-MM-DD}}#Action Items|Today's Actions]]
|
||||
![[Meetings/{{date-1w:YYYY-MM-DD}}#Follow-ups|Last Week]]
|
||||
```
|
||||
````
|
||||
|
||||
---
|
||||
|
||||
## Philosophy
|
||||
|
||||
The goal of Sync Embeds is to make your notes more dynamic and interconnected. It removes the friction of editing transcluded content, allowing you to build powerful dashboards, manage recurring tasks, and maintain a single source of truth for blocks of information without ever leaving the note you're working on.
|
||||
|
||||
---
|
||||
|
||||
## Contributing & Feedback
|
||||
|
|
@ -221,6 +157,12 @@ This plugin was built with and for the community. If you find a bug, have a feat
|
|||
|
||||
<div align="center">
|
||||
|
||||
**If you find this plugin helpful, please consider starring ⭐ the repository!**
|
||||
### Support Development
|
||||
|
||||
Sync Embeds is provided entirely for free. If this plugin has improved your workflow or saved you time, consider supporting its continued development!
|
||||
|
||||
<a href="https://ko-fi.com/uthvah" target="_blank"><img src="https://cdn.ko-fi.com/cdn/kofi3.png?v=3" alt="Buy Me A Coffee" height="35" width="130"></a>
|
||||
|
||||
**Leave a ⭐ on the repository, if you like!!**
|
||||
|
||||
</div>
|
||||
|
|
|
|||
Loading…
Reference in a new issue