markdown-agenda.nvim

BETA: This plugin was just created. I'm using it personally during work and personal stuff, but expect some bugs. Please report them if encountered A minimal, focused agenda view for your markdown notes. Scans your notes directory for tasks with @scheduled(DATE) and @deadline(DATE) annotations and displays them in a collapsible floating window.

Features

• Agenda view - Today's tasks + weekly overview in a floating window
• Deadline urgency - Visual indicators for deadline proximity
• Overdue tracking - Never miss a deadline again
• Scheduled tasks - Plan your work with scheduled dates
• Collapsible sections - Toggle Today/Week sections with <Tab>
• Zero dependencies - Pure Lua, no external dependencies

Installation

lazy.nvim

{
  'Kamyil/markdown-agenda.nvim',
  -- Required for :MarkdownAgenda command to be available
  -- Alternatively, use: cmd = 'MarkdownAgenda' for lazy-loading on command
  lazy = false,
  opts = {
    directory = '~/notes',
  },
}

packer.nvim

use {
  'Kamyil/markdown-agenda.nvim',
  config = function()
    require('markdown-agenda').setup({
      directory = '~/notes',
    })
  end
}

Configuration

require('markdown-agenda').setup({
  -- Directory to scan for markdown files
  directory = '~/notes',
  
  -- Scan subdirectories recursively
  recursive = true,
  
  -- Date format used in your notes
  -- Options: '%Y-%m-%d' (2025-12-30), '%m/%d/%Y' (12/30/2025), '%d/%m/%Y' (30/12/2025)
  date_format = '%Y-%m-%d',
  
  -- Customize icons
  icons = {
    scheduled = '📌',
    deadline_urgent = '🔴',  -- ≤1 day
    deadline_soon = '🟡',    -- 2-4 days
    deadline_ok = '🟢',      -- >4 days
    overdue = '⚠️',
    today = '▶',
    collapsed = '▶',
    expanded = '▼',
  },
  
  -- Keymaps (set to false to disable)
  keymaps = {
    open = '<leader>na',
  },
})

Usage

Task Syntax

Add these annotations to your markdown tasks:

- [ ] Call the dentist @scheduled(2025-12-30)
- [ ] Submit report @deadline(2025-12-31)
- [ ] Important meeting @scheduled(2025-12-30) @deadline(2025-12-30)
- [-] In progress task @scheduled(2025-12-30)

Commands

• :MarkdownAgenda - Open the agenda view
• <leader>na - Open the agenda view (default keymap)

Agenda Controls

Key	Action
<Enter>	Jump to task in file
<Tab>	Toggle section (Today/Week)
<Esc> / q	Close agenda

Task States

Syntax	Meaning
- [ ]	Todo
- [-]	In progress
- [x]	Done (not shown in agenda)

Deadline Indicators

Icon	Meaning
🔴	≤1 day left
🟡	2-4 days left
🟢	>4 days left
⚠️	Overdue
📌	Scheduled (no deadline)

License

MIT