1 +#
Yazi Nugu dotfiles design 7 +Make Yazi a first-class, dotfiles-managed terminal file manager configuration that uses the personal Nugu theme and integrates tastefully with existing tools. The result should feel native to the rest of the dotfiles without turning Yazi into a large plugin project.
11 +- Do not vendor third-party plugin repositories into dotfiles.
12 +- Do not add bookmarks or session/autosession plugins.
13 +- Do not replace Yazi defaults wholesale.
14 +- Do not add a Space leader layer; keep Space for selection.
15 +- Do not implement Jujutsu (`jj`) Yazi plugin support in v1.
16 +- Do not add heavyweight statusline alternatives beyond the chosen minimal statusline plugin.
20 +- Live Yazi config currently lives in `~/.config/yazi` and contains only:
21 + - `theme.toml`, selecting the `noctalia` flavor.
22 + - `flavors/noctalia.yazi/flavor.toml`.
23 +- Dotfiles do not currently manage `~/.config/yazi`.
24 +- Nugu already provides generated themes for Ghostty, Helix, and WezTerm.
25 +- Existing dotfiles favor declarative config, Nushell automation, generated theme artifacts, and symlink manifests.
26 +- Relevant available tools include `nvim`, `git`, `jj`, `glow`, `bat`, `mpv`, `wl-copy`, `fzf`, `zoxide`, `fd`, `rg`, `jq`, `7z`, `ffmpeg`, `magick`, `resvg`, `pdftoppm`, `ouch`, and `hexyl`.
30 +###
Dotfiles ownership 32 +Create a new `yazi/` directory in the dotfiles repository. It will be symlinked to `~/.config/yazi` through the host symlink manifests, consistent with other applications.
46 + └── nugu-light.yazi/
50 +The symlink manifest should map:
57 +Linux desktop host manifests should receive this mapping: `desktop.symlinks`, `fedora.symlinks`, and `x230.symlinks`. `termux.symlinks` and Windows manifests can be added later if Yazi is used there.
59 +###
Plugin package hygiene 61 +Yazi plugins will be managed with `ya pkg`. The committed source of truth is `yazi/package.toml`, not the installed plugin directories.
63 +- Commit `package.toml`.
64 +- Ignore `yazi/plugins/`.
65 +- Do not vendor plugin repositories.
66 +- Restore plugins on a new machine with `ya pkg install`.
68 +The generated Nugu flavors are not third-party plugin clutter. They are first-party generated artifacts and should be committed.
72 +Add a `nugu/yazi.nu` generator that maps Nugu palette roles to Yazi's flavor schema.
74 +Extend `nugu/justfile` with a `yazi` recipe that:
76 +1. Builds or reads the Nugu palette.
77 +2. Generates dark and light flavor files under `output/yazi/` or directly writes `../yazi/flavors/nugu-{dark,light}.yazi/flavor.toml`.
78 +3. Keeps generated Yazi flavor output reproducible.
80 +Extend `nugu/justfile install` to include the Yazi generation step.
82 +`yazi/theme.toml` will select Nugu:
90 +Yazi will use separate generated Nugu dark and light flavors so terminal light/dark switching has matching colors.
94 +The Yazi flavor should use Nugu semantic palette roles rather than raw arbitrary colors.
96 +Suggested role mapping:
98 +- App/status backgrounds: `ui.backdrop`.
99 +- Main text: `content.normal`.
100 +- File manager borders: `ui.unfocus` or `ui.minor`.
101 +- Active UI elements: `ui.accent` and `ui.important_local`.
102 +- Selected counts/markers: `content.focus` and `ui.important_local`.
103 +- Warnings/errors: `warning` and `error`.
105 + - modified: `warning`
106 + - added: `content.focus`
107 + - untracked: `content.accent`
109 + - ignored: `content.minor`
111 +The initial flavor should style enough of Yazi to feel intentionally Nugu without duplicating the full Noctalia icon table. Existing Yazi default icons can remain unless they clash visually.
113 +##
Yazi behavior config 115 +`yazi/yazi.toml` should be minimal and override defaults only where the dotfiles imply a preference.
117 +Planned manager settings:
123 +sort_dir_first = true
127 +Use default pane ratio `[1, 4, 3]` unless testing shows preview feels cramped.
129 +Preview/opening behavior:
131 +- Keep built-in JSON, PDF, image, video, and archive previews where they work well.
132 +- Use `piper` selectively for tools already present:
133 + - Markdown preview via `glow`.
134 + - Fallback binary preview via `hexyl`.
135 +- Use `ouch` for archive preview/extract behavior where it improves over defaults.
136 +- Use `nvim` as blocking editor.
137 +- Use `mpv` for media.
138 +- Use `xdg-open` for general open behavior.
142 +- Configure `git.yazi` fetchers for files and directories.
143 +- Do not configure `vcs-files` in v1.
144 +- Do not attempt inline `jj` status in v1.
146 +##
Lua initialization 148 +`yazi/init.lua` should only initialize selected plugins and avoid custom UI rewrites.
153 +require("full-border"):setup { type = ui.Border.PLAIN }
154 +require("git"):setup { order = 1500 }
155 +require("yaziline"):setup { separator_style = "liney" }
158 +Additional plugin setup can be added only if required by the chosen plugin's documented API. Avoid overriding core Yazi UI build functions.
162 +Use `[[mgr.prepend_keymap]]` only. Preserve Yazi defaults and add targeted improvements.
166 +- Space remains selection.
167 +- `g`, `t`, `c`, and existing Yazi prefix groups remain native Yazi-style groups.
168 +- No full keymap replacement.
169 +- Avoid terminal-fragile Alt bindings when a normal sequence is available.
175 +| `l` | `plugin smart-enter` |
176 +| `<Enter>` | `plugin smart-enter` |
177 +| `p` | `plugin smart-paste` |
178 +| `f` | `plugin smart-filter` |
179 +| `T` | `plugin toggle-pane min-preview` |
180 +| `F` | `plugin toggle-pane max-preview` |
181 +| `c m` | `plugin chmod` |
182 +| `c D` | `plugin diff` |
183 +| `!` | blocking `$SHELL` in current directory |
184 +| `g w` | `cd ~/Workspace` |
185 +| `g k` | `cd ~/Workspace/dotfiles` |
186 +| `g n` | `cd ~/Notes` |
187 +| `g y` | `cd ~/.config/yazi` |
188 +| `g r` | change to repo root using `git rev-parse --show-toplevel` or `jj root` |
192 +- Override input `<Esc>` to close the input immediately, avoiding Yazi input's vi-normal mode when the intent is simple cancellation.
196 +Install and lock these plugins in `yazi/package.toml`:
198 +- `yazi-rs/plugins:full-border`
199 +- `yazi-rs/plugins:toggle-pane`
200 +- `yazi-rs/plugins:smart-enter`
201 +- `yazi-rs/plugins:smart-filter`
202 +- `yazi-rs/plugins:smart-paste`
203 +- `yazi-rs/plugins:git`
204 +- `yazi-rs/plugins:chmod`
205 +- `yazi-rs/plugins:diff`
206 +- `yazi-rs/plugins:piper`
208 +- `llanosrocas/yaziline`
210 +Deferred plugins and integrations:
212 +- Custom `jj` plugin.
213 +- `vcs-files` and `git-files`.
215 +- Session/autosession plugins.
216 +- `lazygit` plugin until the `lazygit` binary is installed.
217 +- `starship`, `yatline`, `simple-status`, and other statusline alternatives.
218 +- `mount`, `sudo`, and clipboard plugins.
220 +##
Validation strategy 222 +Functional validation:
224 +1. Generate Nugu Yazi flavor.
225 +2. Run `ya pkg install` from the Yazi config directory.
226 +3. Run `yazi --debug` to inspect merged config and schema issues.
227 +4. Launch Yazi with `YAZI_LOG=debug` if plugin errors occur.
228 +5. Check keybindings in Yazi help.
230 + - hidden files visible by default
231 + - `l`/Enter smart-enter behavior
232 + - `p` smart-paste behavior
233 + - `f` smart-filter behavior
234 + - `T` and `F` pane behavior
235 + - `c m` chmod prompt
236 + - `c D` diff behavior
237 + - Markdown preview via glow
238 + - archive handling via ouch
239 + - git signs in a Git repo
243 +1. Ensure `yazi/plugins/` is ignored.
244 +2. Ensure `yazi/flavors/nugu-dark.yazi/flavor.toml` and `yazi/flavors/nugu-light.yazi/flavor.toml` are tracked.
245 +3. Ensure symlink manifest tests still pass.
246 +4. Ensure regenerating Nugu Yazi flavor produces no unexpected diff.
248 +##
Implementation phases 250 +1. Add Yazi dotfiles skeleton and symlink manifest entries.
251 +2. Add Nugu Yazi generator and generated flavor.
252 +3. Add Yazi config files (`theme.toml`, `yazi.toml`, `keymap.toml`, `init.lua`).
253 +4. Install and lock selected plugins via `ya pkg`.
254 +5. Add ignore rules for installed plugin artifacts.
255 +6. Validate with Yazi, Nugu generation, and dotfiles checks.
257 +##
Open follow-ups after v1 259 +- Add a local custom Yazi plugin for `jj` changed files or inline status signs.
260 +- Consider adding a `just yazi` or root-level dotfiles recipe for Yazi validation.
261 +- Consider adding `lazygit` integration if the binary is installed later.