obsorg.nvim

A lightweight Neovim plugin for managing TODO tasks in Markdown files with an Org-mode inspired workflow. Perfect for Obsidian users who want org-mode style task management in their notes.

✨ Features

• 📝 TODO Management - Track tasks with multiple states (TODO/DOING/DONE/CANCELLED)
• 🗓️ Interactive Calendar - Visual date picker with Vim-style navigation
• 📊 Compact Agenda View - Org-mode inspired weekly agenda
• ⏰ Scheduled & Deadlines - SCHEDULED dates with time, DEADLINE dates
• 🎨 Syntax Highlighting - Color-coded task states and dates
• ⌨️ Quick Keybindings - Efficient keyboard shortcuts for all operations
• 🔍 Smart Parsing - Scans all markdown files in your vault

📸 Screenshots

Compact Agenda View

Week Agenda:    Sunday, January 5, 2025
Thursday, January 2, 2025:
  TODO     Old task :project:
Sunday, January 5, 2025:
  10:00 TODO     Buy groceries :personal:
  14:00 DOING    Write report :work:
Monday, January 6, 2025:
  09:00 TODO     Team meeting :meetings:
Unscheduled:
  TODO     Learn Neovim API :learning:

Interactive Calendar

╔═══════════════════════════════╗
║  January 2025                 ║
╠═══════════════════════════════╣
║ Mo Tu We Th Fr Sa Su          ║
╟───────────────────────────────╢
║        1  2  3  4  5          ║
║  6  7  8  9 10 11 12          ║
║ 13 14[15]16 17 18 19          ║
╠═══════════════════════════════╣
║ ← → : Month  ↑ ↓ : Year       ║
║ h j k l : Day                 ║
║ Enter : Select  q : Cancel    ║
╚═══════════════════════════════╝

📦 Installation

lazy.nvim

{
  "RuslanGagushin/obsorg.nvim",
  config = function()
    require("obsorg").setup({
      notes_dir = vim.fn.expand("~/notes"),  -- Your notes directory
    })
  end,
}

packer.nvim

use {
  'RuslanGagushin/obsorg.nvim',
  config = function()
    require('obsorg').setup({
      notes_dir = vim.fn.expand("~/notes"),
    })
  end
}

Manual

git clone https://github.com/RuslanGagushin/obsorg.nvim ~/.config/nvim/pack/plugins/start/obsorg.nvim

Then in your init.lua:

require('obsorg').setup()

🚀 Usage

Task Format

- TODO Buy groceries
  SCHEDULED: 2025-01-05 10:00

- DOING Write report
  DEADLINE: 2025-01-10

- DONE Read book

Commands

Command	Description
:OrgAgenda	Open Org Agenda view
:OrgTodoToggle	Cycle TODO state
:OrgScheduled	Insert SCHEDULED date
:OrgDeadline	Insert DEADLINE date
:OrgTodoInsert	Create new TODO

Keybindings

In Markdown files:

Key	Action
<leader>oa	Open Agenda
<leader>ot	Toggle TODO state
<leader>os	Add SCHEDULED (with calendar)
<leader>od	Add DEADLINE (with calendar)
<leader>oi	Insert new TODO

In Agenda view:

Key	Action
<CR>	Go to task
t	Toggle TODO state
r	Refresh agenda
q	Close agenda

In Calendar:

Key	Action
h/l or ←/→	Previous/Next day or month
j/k or ↑/↓	Week up/down or year
t	Jump to today
<CR>	Select date
q or Esc	Cancel

⚙️ Configuration

Default Configuration

require("obsorg").setup({
  -- Notes directory (supports Obsidian vaults)
  notes_dir = vim.fn.expand("~/notes"),
  
  -- TODO state keywords (cycle through with <leader>ot)
  todo_keywords = { "TODO", "DOING", "DONE", "CANCELLED" },
  
  -- Date formats
  date_format = "%Y-%m-%d",
  datetime_format = "%Y-%m-%d %H:%M",
  
  -- Syntax highlighting colors
  colors = {
    TODO = "DiagnosticWarn",      -- Yellow
    DOING = "DiagnosticInfo",     -- Blue
    DONE = "DiagnosticOk",        -- Green
    CANCELLED = "DiagnosticHint", -- Gray
    deadline = "DiagnosticError", -- Red
    scheduled = "DiagnosticInfo", -- Blue
  },
})

Custom TODO Keywords

require("obsorg").setup({
  todo_keywords = { "TODO", "IN_PROGRESS", "DONE", "WONT_DO" },
})

Custom Date Format

require("obsorg").setup({
  date_format = "%d.%m.%Y",           -- 05.01.2025
  datetime_format = "%d.%m.%Y %H:%M", -- 05.01.2025 14:30
})

Custom Colors

require("obsorg").setup({
  colors = {
    TODO = "Function",
    DOING = "String",
    DONE = "Comment",
    CANCELLED = "NonText",
  },
})

🎯 Use Cases

GTD (Getting Things Done)

• Inbox: Tasks without dates (Unscheduled section)
• Planning: Add dates with calendar
• Review: Check Agenda daily
• Execute: Toggle states as you work

Obsidian Integration

Perfect for Obsidian users:

• Works seamlessly with your vault
• Respects your folder structure
• No conflicts with Obsidian syntax

Time Blocking

• Use SCHEDULED with times
• View your day in Agenda
• Track time commitments

🔧 Requirements

• Neovim >= 0.9.0
• No external dependencies!

📚 Similar Projects

• orgmode.nvim - Full Emacs org-mode implementation
• neorg - Note-taking with custom format
• obsidian.nvim - Obsidian integration

Why obsorg.nvim?

• ✅ Works with plain Markdown
• ✅ Lightweight and fast
• ✅ Org-mode inspired workflow
• ✅ Perfect for Obsidian users
• ✅ No learning curve

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing)
5. Open a Pull Request

📝 License

MIT License - see LICENSE file for details

🙏 Acknowledgments

• Inspired by Emacs org-mode
• Built for the Obsidian community
• Powered by Neovim

📬 Contact

• Issues: GitHub Issues
• Discussions: GitHub Discussions

---

Made with ❤️ for the Neovim community