From 6548333e6277cae90a6db38b210f0d92dda2565b Mon Sep 17 00:00:00 2001 From: Prad Nukala Date: Sun, 18 Oct 2026 09:31:18 -0400 Subject: [PATCH] docs(readme): document Neovim configuration setup and keymaps --- README.md | 173 ++++++++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 155 insertions(+), 18 deletions(-) diff --git a/README.md b/README.md index 4488bde..f0f0230 100644 --- a/README.md +++ b/README.md @@ -1,12 +1,29 @@ -# AstroNvim Template +# prdlk/nvim -**NOTE:** This is for AstroNvim v6+ +Personal Neovim config built on [AstroNvim](https://github.com/AstroNvim/AstroNvim) v6 (`version = "^6"` in `lua/lazy_setup.lua`), targeting Neovim 0.12. -A template for getting started with [AstroNvim](https://github.com/AstroNvim/AstroNvim) +It started from the AstroNvim template and now adds git-aware sessions, `fff`-backed file search, multiplexer-aware split navigation, mermaid diagnostics, MDX templates, and an Oh My Pi side terminal. -## 🛠️ Installation +## Requirements -#### Make a backup of your current nvim and shared folder +| Tool | Used by | +| --- | --- | +| Neovim 0.12+, git | everything | +| Nerd Font | icons (`icons_enabled = true`) | +| `fd`, `ripgrep` | `e` / `m` pickers, grug-far | +| `cargo` (fallback only) | `fff` builds from source when no prebuilt binary downloads | +| `node` + `npm` | mermaid validator (installs `mermaid` + `jsdom` under `stdpath("data")` on first use) | +| `lazygit`, `lazydocker`, `gh` (+ `gh-dash`), `ghq` | git/GitHub/project binds | +| `tv` (television) | `` channel picker | +| `kitty`, `yazi` | neo-tree image preview (`kitten icat`) and yazi launchers | +| `omp` + `omp plugin install omp.nvim` | Oh My Pi terminal and `omp.nvim` integration | +| `uv` / a project venv | basedpyright third-party imports (`uv sync`) | + +Language servers, formatters, and linters come from the AstroCommunity packs through Mason. + +## Installation + +Back up any existing config: ```shell mv ~/.config/nvim ~/.config/nvim.bak @@ -15,20 +32,140 @@ mv ~/.local/state/nvim ~/.local/state/nvim.bak mv ~/.cache/nvim ~/.cache/nvim.bak ``` -#### Create a new user repository from this template - -Press the "Use this template" button above to create a new repository to store your user configuration. - -You can also just clone this repository directly if you do not want to track your user configuration in GitHub. - -#### Clone the repository - -```shell -git clone https://github.com// ~/.config/nvim -``` - -#### Start Neovim +Clone and start: ```shell +git clone https://github.com/prdlk/nvim ~/.config/nvim nvim ``` + +`init.lua` bootstraps lazy.nvim on first launch and installs the plugins pinned in `lazy-lock.json`. + +## Layout + +``` +init.lua lazy.nvim bootstrap, terminal title, cursor shape +lua/lazy_setup.lua AstroNvim import, leader keys (, localleader ","), lazy options +lua/community.lua AstroCommunity imports (language packs, colorscheme, statusline) +lua/plugins/ plugin specs and AstroNvim overrides, one file per concern +lua/config/ plain Lua modules used by the plugin specs +lua/polish.lua runs last; registers the u toggles +templates/mdx/ template.nvim snippets for MDX docs +scripts/ mermaid-validator.mjs (node process used by config/mermaid.lua) +zed-keymap.jsonc Zed keymap that mirrors these binds +``` + +`lua/plugins/mason.lua`, `none-ls.lua`, and `treesitter.lua` are template stubs that return `{}` early and do nothing. + +## What's included + +**Languages** (`lua/community.lua`): Go (+ golangci-lint), Rust, TypeScript, Biome, Python (basedpyright, no black/isort), HTML/CSS, Tailwind, JSON, YAML, TOML, Proto, Pkl, MDX. + +**Python**: `plugins/python.lua` points basedpyright at `$VIRTUAL_ENV`/`$CONDA_PREFIX`, then `.venv`/`venv`/`env` in the project root, then system `python3`. A project with a `uv.lock` or `poetry.lock` and no venv gets a one-time warning. Ruff organizes imports and formats. + +**Format on save** (`plugins/conform.lua`, `config/lsp_code_actions.lua`): on save, `source.organizeImports` and `source.fixAll` code actions run first, then conform formats. JavaScript buffers get the code actions but are not formatted. `uf` turns the whole pipeline on or off. + +**Sessions** (`config/session.lua`): sessions are keyed by `@`, so each worktree and branch keeps its own layout. On `VimEnter`, neo-tree opens and the saved session is restored; with no saved session, the git files picker opens instead. None of this happens when nvim is started with file arguments. Sessions save on exit. + +**Search**: `fff.nvim` handles files and grep (frecency, respects `.gitignore` and `.ignore`). snacks.picker handles everything else. `config/ignore_patterns.lua` holds the shared ignore list used by neo-tree and the snacks pickers. + +**Pane navigation** (`config/pane_nav.lua`): `` moves between Neovim splits first. At the outermost split, the move goes to herdr, tmux, or kitty, whichever is the nearest ancestor process. + +**Mermaid** (`config/mermaid.lua`): tree-sitter highlights ```` ```mermaid ```` fences in markdown/MDX and `.mmd` files. Diagnostics come from mermaid's own parser running in a node process, which exits after 5 idle minutes. Run `:MermaidCheck` to re-validate. + +**Markdown**: `:Vellum` opens a live GitHub-style preview (prdlk fork, `mdx` branch). In markdown and MDX buffers, visual `e…` applies formatting (see below). + +**AI**: Supermaven provides inline completions and a blink.cmp source. It is disabled for Python and inside the LeetCode work directory. `` toggles an Oh My Pi terminal on the right. + +**UI**: cyberdream colorscheme (muted variant), bufferline, NvChad-style heirline statusline (`laststatus = 0`), smear-cursor, neo-tree replacing mini.files. Snacks dashboard and toggleterm are disabled. + +## Keymaps + +Leader is ``; localleader is `,`. Prefixes: `` find, `` git/GitHub, `` buffers, `` assist, `u` UI toggles. + +### Files and search + +| Key | Action | +| --- | --- | +| `` | Smart picker (scoped to the git root) | +| `e` | Git files | +| `f` / `.` | Find files in cwd / in the buffer's directory | +| `w` / `z` / `` | Live grep / fuzzy grep / grep word or selection | +| `r` | Resume last find/grep | +| `e` | Pick an extension, then find files with that extension | +| `m` | Files modified today | +| `x` | URLs in the buffer (opens in browser) | +| `o` / `p` / `P` | Recent files / projects / ghq repos | +| `d` / `l` | Diagnostics / lines | +| `gw` `gd` `gm` `gp` `gc` | Workflows, Devbox/Docker, Makefiles, package.json, `.ai/` files | +| `` | LSP symbols | +| `` | Template picker (also takes over `` in normal mode) | +| `` | Television channels | +| `` | Find & replace (grug-far; linewise visual selection limits the range) | +| `` | Toggle neo-tree | + +File pickers open the selection with `:tab drop` on `` and in a vsplit on ``. + +### Editing and navigation + +| Key | Action | +| --- | --- | +| `f` / `F` | Flash: label word starts / search-and-label | +| `s` / `S` | Flash jump / Flash treesitter | +| `J` / `K` | Next / previous diagnostic | +| `H` / `L` | Previous / next buffer | +| `]]` / `[[` | Next / previous LSP reference | +| `vv` / `T` | Select all / go to top | +| visual `D` / `R` | Delete / replace every occurrence of the selection | +| `` | Paste from system clipboard | + +`plugins/astrocore.lua` also maps `F` to `za` (toggle fold), which conflicts with the Flash `F` bind. + +### Buffers, windows, saving + +| Key | Action | +| --- | --- | +| `` | Save if modified, otherwise buffer picker | +| `` | Save buffer | +| `` | Save if modified, then close buffer | +| `` | Close window; save all and quit if it's the last one | +| `ZZ` / `` | Save all and quit | +| `b` / `f` / `` | Pick buffer / find buffers / close all other buffers | + +`` is remapped to save, so the built-in window prefix is not available on it. + +### Git and GitHub + +| Key | Action | +| --- | --- | +| `` | lazygit | +| `` | CodeDiff review workspace | +| `d` / `` | Git diff / branches picker | +| `` / `I` | GitHub issues (open / all) | +| `` / `P` | GitHub PRs (open / all) | +| `o` | Open the repo on the web | +| `` | lazydocker | + +### Assist + +| Key | Action | +| --- | --- | +| `a` | Code actions | +| `s` / `S` | Document / workspace symbols (`` in the picker sends results to Trouble) | +| `d` | Diagnostics (`` sends results to Trouble) | +| `` | Toggle Supermaven | +| `` | Toggle Oh My Pi terminal | + +LSP binds are created only when the attached server supports the method (`plugins/astrolsp.lua`). + +### Markdown (visual mode, markdown/MDX buffers) + +`ei` italic, `eb` bold, `ec` inline code, `ex` link, `el` / `eL` unordered / ordered list, `eC` code block. + +### UI toggles + +`u` + `d` diagnostics, `l` diagnostic virtual lines, `f` format on save, `n` line numbers, `r` relative numbers, `w` wrap, `s` spell, `c` conceal, `i` inlay hints, `t` treesitter, `I` indent guides, `x` dim, `z` zen, `Z` zoom, `a` animations, `S` smooth scroll, `p` / `h` profiler. + +## Development + +Lua is formatted with StyLua (`.stylua.toml`) and linted with Selene (`selene.toml`, `neovim.yml`). Run `:Lazy update` to update plugins, then commit `lazy-lock.json`.