Checkmate.nvim：Neovim 下的 Markdown 任务管理专家

Checkmate.nvim：Neovim 下的 Markdown 任务管理专家

checkmate.nvim A simple yet sophisticated Neovim To-do plugin 项目地址: https://gitcode.com/gh_mirrors/ch/checkmate.nvim

项目概述

Checkmate.nvim 是一款专为 Neovim 0.10 及以上版本设计的 Markdown 任务列表管理插件。它以纯 Markdown 格式存储待办事项，同时提供了丰富的可视化界面和高度可定制的功能，让开发者能够在熟悉的编辑环境中高效管理任务。

核心特性

1. 原生 Markdown 兼容性

   • 使用标准 Markdown 语法存储任务项
   • 兼容其他 Markdown 编辑器查看和编辑
   • 自动转换标准语法为美化后的显示形式

2. 丰富的任务管理功能

   • 支持 Unicode 符号美化任务项
   • 可视化模式批量操作
   • 智能任务状态切换逻辑
   • 已完成任务归档功能（实验性）

3. 元数据标注系统

   • 支持 @tag(value) 形式的自定义标注
   • 内置常用标注如 @started、@done、@priority
   • 可扩展自定义标注类型

4. 可视化增强

   • 可定制的标记符号和颜色方案
   • 任务完成度统计显示
   • 语法检查功能确保格式正确

安装指南

前置要求

• Neovim 0.10 或更高版本

使用 Lazy.nvim 安装

{
    "bngarren/checkmate.nvim",
    ft = "markdown", -- 仅对 Markdown 文件按需加载
    opts = {
        -- 自定义配置
        -- 留空则使用默认值
    },
}

使用教程

1. 创建/打开任务文件

Checkmate 会自动识别以下模式的 Markdown 文件：

• TODO.md
• todo.md
• *.todo.md

可通过配置文件自定义识别模式。

2. 添加任务项

方法一：使用快捷键（推荐）

• 默认快捷键：<leader>Tn

方法二：使用命令

:CheckmateCreate

方法三：手动输入 Markdown

- [ ] 未完成任务
- [x] 已完成任务

退出插入模式后，插件会自动美化显示格式。

3. 任务管理操作

| 操作 | 命令 | 默认快捷键 | |------|------|-----------| | 切换状态 | :CheckmateToggle | <leader>Tt | | 标记完成 | :CheckmateCheck | <leader>Tc | | 标记未完成 | :CheckmateUncheck | <leader>Tu | | 移除所有元数据 | :CheckmateRemoveAllMetadata | - | | 归档已完成任务 | :CheckmateArchive | <leader>Ta | | 语法检查 | :CheckmateLint | - |

可视化模式技巧：选中多个任务后使用上述命令可批量操作。

高级配置详解

Checkmate 提供了丰富的配置选项，以下是关键配置项说明：

基础配置

{
    enabled = true,  -- 是否启用插件
    notify = true,   -- 是否显示通知
    files = {"TODO.md", "todo.md", "*.todo.md"}, -- 匹配文件模式
    
    -- 日志设置
    log = {
        level = "info",  -- 日志级别
        use_file = true, -- 记录到文件
        use_buffer = true -- 输出到缓冲区
    },
    
    default_list_marker = "-", -- 默认列表标记符号
    enter_insert_after_new = true, -- 创建后进入插入模式
    todo_action_depth = 1, -- 任务操作深度
}

任务标记符号定制

todo_markers = {
    unchecked = " ",  -- 未完成标记
    checked = "x"     -- 已完成标记
}

智能切换行为

smart_toggle = {
    enabled = true,
    check_down = "direct_children", -- 父任务完成时影响子任务
    uncheck_down = "none",         -- 父任务取消时不影响子任务
    check_up = "direct_children",  -- 所有子任务完成时父任务自动完成
    uncheck_up = "direct_children" -- 任一子任务取消时父任务自动取消
}

任务计数显示

show_todo_count = true, -- 是否显示任务计数
todo_count_position = "eol", -- 显示位置（行尾或行内）
todo_count_formatter = function(completed, total)
    return string.format("[%d/%d]", completed, total)
end,
todo_count_recursive = true -- 是否递归统计嵌套任务

样式定制

style = {
    list_marker_unordered = { fg = "#FFA500" }, -- 无序列表标记
    unchecked_marker = { fg = "#FF0000", bold = true }, -- 未完成标记
    checked_marker = { fg = "#00FF00", italic = true }, -- 已完成标记
    -- 更多样式项...
}

元数据系统

metadata = {
    started = {
        aliases = {"initiated", "began"},
        style = { fg = "#FFA07A" },
        get_value = function() return os.date("%Y-%m-%d") end,
        key = "<leader>Ts",
        sort_order = 1
    },
    -- 可添加更多自定义元数据
}

最佳实践

1. 项目任务管理

   • 在项目根目录创建 PROJECT.todo.md
   • 使用层级结构组织任务
   • 利用 @priority(high) 标注重要任务

2. 个人待办事项

   • 使用 @started(日期) 记录开始时间
   • 定期使用 :CheckmateArchive 归档已完成任务
   • 通过 :CheckmateLint 保持格式规范

3. 团队协作

   • 使用 @assignee(姓名) 自定义标注分配任务
   • 通过标准的 Markdown 格式实现跨平台协作

常见问题解答

Q：如何修改默认快捷键？

A：在配置中覆盖 keys 设置：

keys = {
    toggle = "<leader>tt", -- 修改切换快捷键
    create = "<leader>tn", -- 修改创建快捷键
    -- 其他操作...
}

Q：为什么我的颜色没有生效？

A：确保你的 colorscheme 支持自定义高亮组，或手动指定完整的颜色值。

Q：如何添加自定义元数据标签？

A：在 metadata 配置中添加新项：

metadata = {
    mytag = {
        style = { fg = "#FF00FF" },
        get_value = function() return "custom" end,
        key = "<leader>Tm"
    }
}

Checkmate.nvim 通过将简单的 Markdown 语法与强大的任务管理功能相结合，为 Neovim 用户提供了一套完整的任务管理解决方案。无论是个人使用还是团队协作，都能显著提升工作效率。

checkmate.nvim A simple yet sophisticated Neovim To-do plugin 项目地址: https://gitcode.com/gh_mirrors/ch/checkmate.nvim