Bidirectional Markdown Sync keeps your task data and individual Markdown task files in lockstep. Every change you make in the plugin UI is written to a .md file, and every edit you make to a .md file is picked up by the plugin automatically.

How It Works

Automatic JSON → Markdown Sync

Whenever you add, update, or delete a task through the plugin UI, the corresponding Markdown file is created, updated, or removed automatically. Files are stored at:

{projectsBasePath}/{Project Name}/Tasks/{TaskTitle}.md

The default projectsBasePath is Project Planner. If a task is renamed, the old file is deleted and a new one is created with the updated title.

Automatic Markdown → JSON Sync

When you modify, create, or delete a Markdown task file directly (for example, in the Obsidian editor or through an external tool), the plugin detects the change via Obsidian's metadata cache and updates the project's task file to match.

Initial Sync

On plugin startup (when Sync on Startup is enabled), a full reconciliation runs: existing Markdown files are compared against the task data and any discrepancies are resolved.

Warning

If you use Obsidian Sync across multiple devices, enable Sync on Startup with caution. Simultaneous edits on different devices can cause last-write-wins conflicts. Consider disabling Sync on Startup and using the manual Sync All Tasks Now button after confirming your vault is fully synced.

Task Markdown Format

Each synced task file follows this structure:

---
id: f8e7d6c5-b4a3-2190-fedc-ba0987654321
title: Design landing page
status: In Progress
completed: false
priority: High
parentId: null
bucketId: bucket-uuid-2
startDate: 2026-02-01
dueDate: 2026-02-14
createdDate: 2026-01-20
lastModifiedDate: 2026-02-03
tags:
  - tag-uuid-1
collapsed: false
dependencies:
  - FS:other-task-uuid
effortCompleted: 4
effortRemaining: 6
percentComplete: 40
costType: hourly
---

Create the initial wireframes and high-fidelity mockups.

## Subtasks
- [x] Wireframe
- [ ] Hi-fi mockup

## Dependencies
- FS: [[other-task-title]]

## Links
- [Figma file](https://figma.com/...)

---
*Managed by Project Planner — do not remove the frontmatter.*

YAML Frontmatter Fields

Required Fields

  • id — UUID v4 unique identifier
  • title — task display name
  • status — current status label (must match a configured status name)
  • completed — true or false

Optional Fields

  • parentId — UUID of the parent task, or null
  • priority — Low, Medium, High, or Critical
  • bucketId — UUID of the Board bucket
  • startDate / dueDate / createdDate / lastModifiedDate — YYYY-MM-DD format
  • tags — YAML list of tag ID strings
  • collapsed — whether child tasks are collapsed in Grid view
  • dependencies — YAML list using the format TYPE:TASK_ID; supported types are FS (Finish-to-Start), SS (Start-to-Start), FF (Finish-to-Finish), and SF (Start-to-Finish)
  • effortCompleted / effortRemaining — hours of work done and remaining
  • percentComplete — 0–100; auto-calculated from effort values
  • costType — fixed or hourly
  • cardPreview — what to show on Board cards: none, checklist, or description

Settings

  1. Enable Markdown Sync

    Toggle on Settings → Markdown Sync → Enable Markdown Sync. This activates bidirectional sync for all existing and new tasks.

  2. Auto-Create Task Notes

    When enabled, a Markdown file is automatically created for every new task added through the UI. Disable this if you prefer to create notes selectively.

  3. Sync on Startup

    Runs a full reconciliation when the plugin loads. Recommended for single-device workflows.

    Warning

    If you use Obsidian Sync, disable this setting to avoid conflicts from unsettled remote changes.

  4. Sync All Tasks Now

    A manual button that triggers an immediate full sync. Use this after resolving conflicts or receiving remote vault changes.

Creating Tasks from Markdown

You can create a new task entirely from a Markdown file:

  1. Create a new .md file inside the correct {projectsBasePath}/{Project Name}/Tasks/ folder.
  2. Add valid YAML frontmatter with at least the required fields.
  3. Save the file. The plugin will detect it via the metadata cache and add the task to the project automatically.

Minimal Example

---
id: 550e8400-e29b-41d4-a716-446655440000
title: Review pull request
status: To Do
completed: false
---

Check the latest PR for the auth module.

Tip

Generate a valid UUID quickly by running crypto.randomUUID() in the Obsidian developer console (Ctrl+Shift+I → Console), or use any online UUID generator.

Conflict Resolution

To prevent recursive write loops, Project Planner uses a syncInProgress guard set. When a sync operation starts, the affected task ID is added to the set. A 1000 ms timeout clears each entry, ensuring the complementary watcher (task file or Markdown) ignores the echoed change.

If both sources are modified simultaneously, the last write wins. In practice this means:

  • UI changes overwrite file changes made within the same 1000 ms window.
  • File changes overwrite UI changes if the file is saved after the UI write completes.

Use Cases

  • Manual editing: Tweak task details in your favorite text editor while the plugin keeps everything in sync.
  • Bulk operations: Use find-and-replace across Markdown files to rename tags, update statuses, or reassign priorities in bulk.
  • Version control: Commit individual task files to Git for granular change history. Task data lives inside the vault (not in .obsidian/) so it is fully Git-trackable.
  • Templates: Create task template files with preset frontmatter and duplicate them for recurring workflows.
  • Plugin integration: Other Obsidian plugins (Dataview, Templater, etc.) can read and write to the Markdown files.

Limitations

  • Last save wins: There is no merge strategy — the most recent write always takes precedence.
  • Subtask and link IDs are regenerated: When syncing from Markdown to JSON, subtask and link IDs are regenerated because Markdown does not store them.
  • New file detection is event-driven: Newly created Markdown files are detected via the metadataCache resolve event, so sync fires as soon as Obsidian finishes parsing the file — no fixed delay.
  • Board view leaf-only: In Board view, only leaf-level tasks (tasks without children) are displayed. Parent tasks created from Markdown will appear in Grid or Timeline views.

Troubleshooting

Tasks Not Syncing

  1. Verify Enable Markdown Sync is toggled on in settings.
  2. Ensure the Markdown file is inside the correct {projectsBasePath}/{Project Name}/Tasks/ folder.
  3. Check that the YAML frontmatter contains all required fields (id, title, status, completed).
  4. Reload the plugin (Ctrl+P → "Reload without saving").

Duplicate Tasks Appearing

  • Duplicates can occur if the same id exists in more than one Markdown file. Remove or correct the duplicate file.
  • If you manually copy a task file, change the id in the frontmatter to a new UUID.

Resolving Conflicts

  • Disable Markdown Sync temporarily.
  • Decide which source (task file or Markdown) is authoritative.
  • Delete the non-authoritative version.
  • Re-enable sync and trigger Sync All Tasks Now.

Debugging

Open the Obsidian developer console (Ctrl+Shift+I) and look for sync-related messages:

[TaskSync] Markdown→JSON sync: updated task "Design landing page"
[TaskSync] JSON→Markdown sync: wrote file "Project Planner/My Project/Tasks/Design landing page.md"

Related Documentation