neovimcraft github

plugins configs about

jjuchara/obsidian-tasks.nvim

github github
note-taking
stars 4
issues 1
subscribers 0
forks 0
CREATED

UPDATED

Why obsidian-tasks.nvim?

Keep notes in Obsidian and stay in Neovim when it is time to execute. The plugin reads ordinary Markdown checkboxes, builds an ordered tag tree, and lets you complete or create tasks without introducing a database or rewriting your vault.

Capability
🗂️ Combine multiple vaults in one view or switch repositories with tabs inside the task view
🌳 Group tasks recursively by tag order: #work #frontend #urgent
⚡ Complete tasks with <Space> and append ✅ YYYY-MM-DD automatically
✍️ Create tasks through a guided repository, tag, start date, and deadline flow
🪟 Use a centered floating window or a regular native split
🔒 Detect stale source lines before writing and update files atomically
🧩 Run on the built-in Neovim API with no required dependencies

Installation

lazy.nvim

{
  "jjuchara/obsidian-tasks.nvim",
  opts = {
    repositories = {
      {
        name = "personal",
        alias = "Personal tasks",
        path = "~/notes/personal/Tasks.md",
      },
    },
    mappings = {
      open = "<leader>to",
      create = "<leader>ta",
    },
  },
}

Native packages

git clone https://github.com/jjuchara/obsidian-tasks.nvim \
  ~/.local/share/nvim/site/pack/plugins/start/obsidian-tasks.nvim

Then call setup() from your configuration.

Configuration

The only required option is repositories. A repository accepts either a direct path to a task file or a vault plus a relative todo_file. Its optional alias is used as the display label while name remains the repository identifier.

require("obsidian-tasks").setup({
  repositories = {
    {
      name = "personal",
      alias = "Personal tasks",        -- optional display label
      path = "~/notes/personal/Tasks.md",
    },
    {
      name = "work",
      vault = "~/notes/work",
      todo_file = "Projects/Tasks.md",
    },
  },

  view = {
    type = "float",                 -- "float" or "window"
    width = 0.5,                    -- fraction of editor width
    height = 0.5,                   -- fraction of editor height
    border = "rounded",
    title = " Obsidian tasks ",
    close_on_leave = true,          -- close a float when focus leaves it
    repository_mode = "sections",  -- "sections" or "tabs"
    window_command = "botright new",
    status = "active",             -- "active", "done", or "all"
    sort = "source",               -- "source", "deadline", or "title"
    filter = nil,                   -- optional initial tag filter, e.g. "#work"
    fold_level = 99,                -- initially expand groups through this tag depth
  },

  dates = {
    display_format = "%d.%m.%Y",  -- strftime format used in the task view
  },

  creation = {
    default_start_today = true,
    prompt_additional_tags = true,
    infinity_marker = "♾️",
  },

  completion = {
    marker = "✅",
  },

  mappings = {
    open = "<leader>to",           -- global mapping, nil disables it
    create = "<leader>ta",         -- global mapping, nil disables it
    create_in_view = "a",
    toggle = "<Space>",
    edit = "<CR>",
    delete = "d",
    undo = "u",
    open_source = "gf",
    refresh = "r",
    close = { "q", "<Esc>" },
    cycle_status = "s",
    cycle_sort = "o",
    filter = "f",
    next_repository = "<Tab>",
    previous_repository = "<S-Tab>",
  },
})

Usage

Commands

Command Action
:ObsidianTasks Open the task view
:ObsidianTasksCreate Start the guided creation flow
:ObsidianTasksRefresh Reload every open task view
:ObsidianTasksSort [source|deadline|title] Set sorting, or cycle it without an argument
:ObsidianTasksFilter [#tag|clear] Select or set a tag filter, or clear it

Task view

Key Action
a Create a task without leaving the task view
<Space> Toggle the task under the cursor
<CR> Edit task text, tags, start date, and deadline
d Delete the task under the cursor after confirmation
u Undo the latest task operation
gf Open the Markdown source at the task line
s Cycle active → done → all
o Cycle source → deadline → title sorting
f Select a tag filter or clear the active filter
za, zc, zo Toggle, close, or open the tag group under the cursor
r Refresh from disk
q, <Esc> Close the view

A floating view is modal by default: clicking another window closes it. Set view.close_on_leave = false if you prefer a persistent float. Task-view mappings must be unique. For example, do not assign both edit and open_source to <CR>. Tag filtering matches any tag on a task, remains active after refresh, and applies to every open task view. Tag groups use native Neovim folds and expose a fold column for mouse interaction. Their expanded and collapsed states are preserved across refreshes, sorting, filtering, and repository navigation. Set view.fold_level = 0 to start with top-level groups collapsed, or use a larger depth to reveal initial levels.

Creating a task

  1. Select a repository when more than one is configured.
  2. Enter the task text.
  3. Select or create the primary tag, press Space to choose the tag under the cursor, or press Enter immediately to continue without one.
  4. Choose any number of additional tags from the existing-tag list. Press Enter to continue, or press Space to toggle the tag under the cursor. Selected additional tags are marked with [x]; use + new tag... to add and select a new tag.
  5. Confirm the start date and optional deadline. Enter yesterday, today, tomorrow, an ISO date such as 2026-07-10, or a date matching dates.display_format. Leading zeroes are optional, so 7.3.2026 is accepted for %d.%m.%Y.

The completion notification shows the persisted tag path, for example #work → #gantt. When task creation starts from an open task view, the view stays open and the newly created task is focused after refresh. Dates are always stored as YYYY-MM-DD. dates.display_format changes rendered dates and the examples shown in creation prompts without modifying Markdown. Active tasks due today or tomorrow use ObsidianTasksDueSoon; overdue tasks use ObsidianTasksOverdue. Deadline sorting adds virtual #overdue, #due-soon, and #on-track groups. #due-soon covers today and tomorrow; later deadlines, completed tasks, and tasks without deadlines are #on-track.

Editing a task from the task view rewrites the Markdown task line while preserving the checkbox state, creation date, and completion date. Clearing the deadline stores the configured no-deadline marker.

Markdown format

## #work

- [ ] Ship the release #work #frontend #urgent 📅 2026-07-10
- [x] Fix the regression #work #backend ✅ 2026-07-02

Tags are significant from left to right:

#work
└── #frontend
    └── #urgent
        └── Ship the release

When a task has no inline tag, the nearest ## #tag heading is used as a fallback. YAML frontmatter and fenced code blocks are ignored.

Multiple repositories

repository_mode = "sections" renders all repositories in one buffer with repository headers. repository_mode = "tabs" shows repository tabs inside the task view and renders tasks from the active repository. Use <Tab> / <S-Tab> or click a tab to switch repositories.

Development

Run the test suite without a plugin manager:

nvim --headless -u NONE -i NONE \
  "+set rtp+=$PWD" \
  "+luafile tests/run.lua" \
  +qa

See CONTRIBUTING.md for the contribution workflow and :help obsidian-tasks for the built-in manual.

Status

The core workflow is usable today. Advanced queries, recurrence, and live filesystem watching are tracked in FUTURE.md.

License

MIT © 2026 jjuchara