地圖 (Jido) is a lightweight Unix TUI file explorer designed for speed and simplicity.
brookjeynes.dev
1# 地圖 (Jido)
2
3
4
5**Jido** is a lightweight Unix TUI file explorer designed for speed and
6simplicity.
7
8The name 地圖 (지도) translates to "map" in English, reflecting Jido's
9purpose: helping you navigate and explore your file system with ease. With
10Vim-like bindings and a minimalist interface, Jido focuses on speed and
11simplicity.
12
13Jido is built with Zig v`0.15.2`.
14
15- [Installation](#installation)
16- [Integrations](#integrations)
17- [Key manual](#key-manual)
18- [Configuration](#configuration)
19- [Contributing](#contributing)
20
21## Installation
22To install Jido, check the "Releases" page or build locally
23via `zig build --release=safe`.
24
25## Integrations
26- `pdftotext` to view PDF text previews.
27- A terminal supporting the `kitty image protocol` to view images.
28
29## Key manual
30Below are the default keybinds. Keybinds can be overwritten via the `Keybinds`
31config option. Some keybinds are unbound by default, see [Configuration](#configuration)
32for more information.
33
34```
35Global:
36<CTRL-c> :Exit.
37<CTRL-r> :Reload config.
38
39Normal mode:
40j / <Down> :Go down.
41k / <Up> :Go up.
42h / <Left> / - :Go to the parent directory.
43l / <Right> :Open item or change directory.
44g :Go to the top.
45G :Go to the bottom.
46c :Change directory via path. Will enter input mode.
47R :Rename item. Will enter input mode.
48D :Delete item.
49u :Undo delete/rename.
50d :Create directory. Will enter input mode.
51% :Create file. Will enter input mode.
52/ :Fuzzy search directory. Will enter input mode.
53. :Toggle hidden files.
54: :Allows for Jido commands to be entered. Please refer to the
55 "Command mode" section for available commands. Will enter
56 input mode.
57v :Verbose mode. Provides more information about selected entry.
58y :Yank selected item.
59p :Past yanked item.
60
61Input mode:
62<Esc> :Cancel input.
63<CR> :Confirm input.
64
65Command mode:
66<Up> / <Down> :Cycle previous commands.
67:q :Exit.
68:h :View available keybinds. 'q' to return to app.
69:config :Navigate to config directory if it exists.
70:trash :Navigate to trash directory if it exists.
71:empty_trash :Empty trash if it exists. This action cannot be undone.
72:cd <path> :Change directory via path. Will enter input mode.
73```
74
75## Configuration
76Configure `jido` by editing the external configuration file located at either:
77- `$HOME/.jido/config.json`
78- `$XDG_CONFIG_HOME/jido/config.json`.
79
80Jido will look for these env variables specifically. If they are not set, Jido
81will not be able to find the config file.
82
83An example config file can be found [here](https://github.com/BrookJeynes/jido/blob/main/example-config.json).
84
85Config schema:
86```
87Config = struct {
88 .show_hidden: bool = true,
89 .sort_dirs: bool = true,
90 .show_images: bool = true, -- Images are only supported in a terminal
91 supporting the `kitty image protocol`.
92 .preview_file: bool = true,
93 .empty_trash_on_exit: bool = false, -- Emptying the trash permanently deletes
94 all files within the trash. These
95 files are not recoverable past this
96 point.
97 .true_dir_size: bool = false, -- Display size of directory including
98 all its children. This can and will
99 cause lag on deeply nested directories.
100 .keybinds: Keybinds,
101 .styles: Styles
102}
103
104Keybinds = struct {
105 .toggle_hidden_files: ?Char = '.',
106 .delete: ?Char = 'D',
107 .rename: ?Char = 'R',
108 .create_dir: ?Char = 'd',
109 .create_file: ?Char = '%',
110 .fuzzy_find: ?Char = '/',
111 .change_dir: ?Char = 'c',
112 .enter_command_mode: ?Char = ':',
113 .jump_top: ?Char = 'g',
114 .jump_bottom: ?Char = 'G',
115 .toggle_verbose_file_information: ?Char = 'v',
116 .force_delete: ?Char = null -- Files deleted this way are
117 not recoverable
118 .yank: ?Char = 'y'
119 .paste: ?Char = 'p'
120}
121
122NotificationStyles = struct {
123 .box: vaxis.Style,
124 .err: vaxis.Style,
125 .warn: vaxis.Style,
126 .info: vaxis.Style
127}
128
129Styles = struct {
130 .selected_list_item: Style,
131 .list_item: Style,
132 .file_name: Style,
133 .file_information: Style
134 .notification: NotificationStyles,
135 .git_branch: Style
136}
137
138Style = struct {
139 .fg: Color,
140 .bg: Color,
141 .ul: Color,
142 .ul_style = .{
143 off,
144 single,
145 double,
146 curly,
147 dotted,
148 dashed
149 }
150 .bold: bool,
151 .dim: bool,
152 .italic: bool,
153 .blink: bool,
154 .reverse: bool,
155 .invisible: bool,
156 .strikethrough: bool
157}
158
159Color = enum{
160 default,
161 index: u8,
162 rgb: [3]u8
163}
164
165Char = enum(u21)
166```
167
168## Contributing
169Contributions, issues, and feature requests are always welcome via
170[GitHub](https://github.com/brookjeynes/jido) or
171[tangled](https://tangled.sh/@brookjeynes.dev/jido).