celeste3z/celeste_comment.nvim

github

editing-supportcomment

5

0

0

0

CREATED

2026-07-08

UPDATED

2026-07-19

---

• Features
• Comparison
• Showcase
• Requirements
• Installation
  • vim.pack (Neovim 0.12+)
  • lazy.nvim
• Default Configuration
• Details
• What it doesn't do
• Limitations
• Future work
• Acknowledgments

Features

• Line comment toggle
• Block comment toggle
• Linewise/Blockwise/Auto-detect comment textobject (can work without treesitter)
• Vscode-style indent algorithm, line comment fallback to block comment
• Dot-repeatable, count support
• Real cursor sticky
• Invert comment per line
• Force add / Force remove line comment
• Insert mode line comment toggle
• Insert comment above / below / at end of line
• Case insensitive comment detection
• Relaxed block detection
• Precise edit tracking (via TextEdits)
• Multi line comment string uncomment — detects and removes multiple line comment strings (e.g. Rust //, ///, //!)

Comparison

Showcase

Requirements

• Neovim >= 0.12

Installation

[!IMPORTANT]

• Breaking changes may occur in MINOR version bumps (e.g. 0.1.0 → 0.2.0).
• PATCH bumps (e.g. 0.1.0 → 0.1.1) are backward compatible.
• Pinning to a specific version or commit is recommended.

vim.pack (Neovim 0.12+)

vim.pack.add({ { src = "https://github.com/celeste3z/celeste_comment.nvim", name = "celeste_comment", version = vim.version.range("*") } })

require("celeste_comment").setup({})

lazy.nvim

{ "celeste3z/celeste_comment.nvim", lazy = false, opts = {} }

Default Configuration

{
  -- Restore cursor position after commenting.
  keep_cursor            = true,

  -- Insert space between comment marker and text.
  insert_space           = true,

  -- Place comment at start of line, skip indent alignment
  line_comment_no_indent = false,

  -- Match comment markers case-insensitively (e.g. `@REM` vs `@rem` vs `@rEm`)
  case_insensitive       = false,

  -- Trim whitespace before detecting block tokens.
  block_relaxed_detect   = true,

  -- Max lines to search for block comment pairs.
  block_textobj_nlines   = 200,

  -- How to handle empty lines during comment toggle.
  -- See `:help celeste_comment-configuration` for more details
  -- Possible values: "never" | "mixed" | "always"
  ignore_empty_lines     = "always",

  -- Fallback to block comment when line comment wraps.
  -- See `:help celeste_comment-configuration` for more details
  -- Possible values: "never" | "if_line_cms_wrapped"
  fallback_to_block      = "if_line_cms_wrapped",

  -- Log level (nvim-0.13+). Ignored on older versions.
  log_level              = vim.log.levels.OFF,

  mappings = {
    -- Line comment by motion (n)
    line_toggle          = "gc",
    -- Line comment current line (n)
    line_toggle_cur      = "gcc",
    -- Line comment visual selection (x)
    line_toggle_visual   = "gc",
    -- Insert mode line toggle (i), example `{"<M-/>", "<M-_>"}`
    line_toggle_insert   = "",

    -- Block comment by motion (n, x)
    block_toggle         = "gb",
    -- Block comment current line (n)
    block_toggle_cur     = "gbc",
    -- Block comment visual selection (x)
    block_toggle_visual  = "gb",

    -- Linewise textobject (o)
    line_textobject      = "gc",
    -- Blockwise textobject (o)
    block_textobject     = "gb",
    -- Auto textobject (o, x), example 'ga'
    auto_textobject      = "",
    -- Auto uncomment (n), example `gcu`
    uncomment_auto       = "",

    -- Insert comment below (n), example `gco`
    line_add_below       = "",
    -- Insert comment above (n), example `gcO`
    line_add_above       = "",
    -- Insert comment at end of line (n), example `gcA`
    line_add_eol         = "",

    -- Invert comment per line (n, x), example `gcI`
    line_invert          = "",
    -- Force add line comment (n, x), example `gCC`
    line_force_add       = "",
    -- Force remove line comment (n, x), example `gCU`
    line_force_remove    = "",

    -- Cursor sticky dot-repeat
    dot_repeat           = ".",
  },

  hooks = {
    -- Called before commit edits, receives context
    pre_commit_edits     = nil,
    -- Custom comment string resolver function
    cms_conf_resolver    = nil,
  },
}

See :help celeste_comment-configuration for details.

Details

See :help celeste_comment for the full documentation, including all configuration options, mappings, hooks, API reference, and usage examples.

What it doesn't do

• Cover all cases — This plugin's aim is to handle the vast majority of common scenarios, not every possible case. Known textobject edge cases and unusual comment patterns are acknowledged but not planned to fix.
• Doc comment
• Header comment

Limitations

• Auto-detect textobject accuracy — textobject_auto() first checks whether the current line contains a line comment. In languages like Lua where -- is used for both line comments (--) and block comments (--[[ ]]), a line starting with -- may be misidentified as a line comment, leading to incorrect textobject selection.

• Regex-based textobject range — Pattern matching can produce false positives in certain scenarios. For example, comment-like tokens inside strings may be mistakenly treated as actual comments. Additionally, the scan range is capped by block_textobj_nlines (default 200), so textobject detection may not work beyond that limit.

• Visual block mode (<C-v>) — Selection is treated as linewise; the entire selected lines are block-commented rather than inserting comment markers per column. For column-wise comment operations, consider using a plugin like multicursor.nvim.

Future work

• Integrated with Neovim's builtin multicursor.

Acknowledgments

• VSCode — The indent algorithm is ported from VSCode's comment implementation. Most of its test cases have also been ported to this plugin's test suite. This plugin is highly inspired by it.

• mini.comment — Its code style and linewise textobject implementation served as a reference for this plugin's development.

• Comment.nvim — Part of the built-in language comment string table was adapted from Comment.nvim.