https://github.com/maniebra/nvim-xdoc
Markdown-style notes & docs embedded in your code – beautifully rendered inside Neovim.
https://github.com/maniebra/nvim-xdoc
docs documentation neovim neovim-documentation neovim-plugin neovim-plugin-lua neovim-plugins nvim nvim-plugin nvim-plugins
Last synced: 2 months ago
JSON representation
Markdown-style notes & docs embedded in your code – beautifully rendered inside Neovim.
- Host: GitHub
- URL: https://github.com/maniebra/nvim-xdoc
- Owner: maniebra
- Created: 2025-04-02T08:00:35.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2025-04-09T20:08:22.000Z (2 months ago)
- Last Synced: 2025-04-13T09:18:45.571Z (2 months ago)
- Topics: docs, documentation, neovim, neovim-documentation, neovim-plugin, neovim-plugin-lua, neovim-plugins, nvim, nvim-plugin, nvim-plugins
- Language: Lua
- Homepage:
- Size: 13.7 KB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# NVIM-XDoc
> Markdown-style notes & docs embedded in your code – beautifully rendered inside Neovim.
## ✨ What is nvim-xdoc?
`nvim-xdoc` is a lightweight Neovim plugin that turns specially-formatted comments into rendered, boxed virtual text. Think of it like Markdown for your comments – but rendered right inside your code, folding the raw comments away and replacing them with stylized visual blocks.
Perfect for:
- Writing inline documentation
- Making TODO sections pop
- Embedding notes, instructions, or explanations right in your codebase
---
## 📸 Example
```lua
--
-- # Quick Start
-- ## How to use xdoc
-- - Write structured comments
-- - They get rendered as boxes
--
```
```c
//
// # Quick Start
// ## How to use xdoc
// - Write structured comments
// - They get rendered as boxes
//
```
⬇️ becomes
```
┌──────────────────────────────┐
│ # Quick Start │
│ ## How to use xdoc │
│ - Write structured comments │
│ - They get rendered as boxes │
└──────────────────────────────┘
```
The raw comments are folded away for a clean view!
---
## ⚙️ Installation
With [lazy.nvim](https://github.com/folke/lazy.nvim):
```lua
{
"maniebra/nvim-xdoc",
config = function()
require("xdoc").setup()
end,
}
```
Or with `packer`:
```lua
use {
"maniebra/nvim-xdoc",
config = function()
require("xdoc").setup()
end,
}
```
---
## 🔧 Configuration
```lua
require("xdoc").setup({
auto_render = true,
comment_syntax = {
lua = "--",
python = "#",
rust = "//",
-- add your filetypes
},
style = {
header1 = { fg = "#FFD700", bold = true, italic = true },
bullet = { fg = "#00FFFF" },
}
})
```
---
## 🧠 How It Works
- Comments are parsed based on your filetype’s syntax.
- Comments surrounded by blank comment lines are grouped and parsed.
- If formatted with Markdown-style headings (`#`, `##`, `-`), they're highlighted accordingly.
- The raw comment block is **folded**, and a rendered **virtual text box** is shown instead.
---
## 🚀 Usage
Once set up, `xdoc` just works when you enter **Normal mode** or when the **window is resized**.
You can manually toggle the preview with:
```lua
require("xdoc").toggle_preview()
```
---
## 🎨 Highlight Groups
You can customize these in your colorscheme or config:
- `XDocHeader` – for `# Heading`
- `XDocSubheader` – for `## Subheading`
- `XDocMinor` – for `### Minor heading`
- `XDocBullet` – for `- list items`
- `XDocText` – fallback text style
---
## 🧪 Supported Languages (out of the box)
- Lua
- Python
- JavaScript / TypeScript
- C / C++ / Java / Kotlin / Go / Rust
- Shell (`.sh`)
Feel free to extend `comment_syntax` in your config!
---
## 📣 Contributing
PRs, issues, and suggestions are always welcome! Let's make Neovim commenting more elegant together. 🖋️