From 1e13fdacda04aca0c07eb7aa6f495d27c4188a0c Mon Sep 17 00:00:00 2001 From: Arijit Basu Date: Sat, 3 Jul 2021 14:54:37 +0530 Subject: [PATCH] Use footer links Tool used: https://github.com/sayanarijit/md-footer --- docs/en/src/SUMMARY.md | 77 ++++++++++----- docs/en/src/alternatives.md | 41 +++++--- docs/en/src/awesome-integrations.md | 26 ++++-- docs/en/src/awesome-plugins.md | 62 ++++++++---- docs/en/src/community.md | 8 +- docs/en/src/configuration.md | 22 +++-- docs/en/src/configure.md | 8 +- docs/en/src/contribute.md | 12 ++- docs/en/src/default-key-bindings.md | 14 ++- docs/en/src/filtering.md | 14 ++- docs/en/src/general-config.md | 33 ++++--- docs/en/src/install.md | 79 ++++++++++------ docs/en/src/installing-plugins.md | 2 +- docs/en/src/integration.md | 5 +- docs/en/src/introduction.md | 20 ++-- docs/en/src/key-bindings.md | 2 +- docs/en/src/layouts.md | 92 +++++++++++------- docs/en/src/message.md | 140 +++++++++++++++++----------- docs/en/src/modes.md | 100 +++++++++++++------- docs/en/src/node_types.md | 43 +++++---- docs/en/src/plugin.md | 11 ++- docs/en/src/post-install.md | 11 ++- docs/en/src/quickstart.md | 8 +- docs/en/src/sorting.md | 11 ++- docs/en/src/style.md | 24 +++-- docs/en/src/todo.md | 18 +++- docs/en/src/upgrade-guide.md | 111 +++++++++++++++------- docs/en/src/writing-plugins.md | 17 +++- 28 files changed, 674 insertions(+), 337 deletions(-) diff --git a/docs/en/src/SUMMARY.md b/docs/en/src/SUMMARY.md index c27f39b..12fd853 100644 --- a/docs/en/src/SUMMARY.md +++ b/docs/en/src/SUMMARY.md @@ -1,28 +1,55 @@ A hackable, minimal, fast TUI file explorer =========================================== -- [Introduction](introduction.md) -- [Quickstart](quickstart.md) - - [Install](install.md) - - [Post Install](post-install.md) -- [Configuration](configuration.md) - - [General Config](general-config.md) - - [Modes](modes.md) - - [Message](message.md) - - [Layouts](layouts.md) - - [Node Types](node_types.md) - - [Style](style.md) - - [Sorting](sorting.md) - - [Filtering](filtering.md) -- [Default Key Bindings](default-key-bindings.md) -- [Plugin](plugin.md) - - [Installing Plugins](installing-plugins.md) - - [Writing Plugins](writing-plugins.md) - - [Awesome Plugins](awesome-plugins.md) -- [Integration](integration.md) - - [Awesome Integrations](awesome-integrations.md) -- [TODO](todo.md) -- [Alternatives](alternatives.md) -- [Upgrade Guide](upgrade-guide.md) -- [Community](community.md) -- [Contribute](contribute.md) +- [Introduction][1] +- [Quickstart][2] + - [Install][3] + - [Post Install][4] +- [Configuration][5] + - [General Config][6] + - [Modes][7] + - [Message][8] + - [Layouts][9] + - [Node Types][10] + - [Style][11] + - [Sorting][12] + - [Filtering][13] +- [Default Key Bindings][14] +- [Plugin][15] + - [Installing Plugins][16] + - [Writing Plugins][17] + - [Awesome Plugins][18] +- [Integration][19] + - [Awesome Integrations][20] +- [TODO][21] +- [Alternatives][22] +- [Upgrade Guide][23] +- [Community][24] +- [Contribute][25] + + +[1]:introduction.md +[2]:quickstart.md +[3]:install.md +[4]:post-install.md +[5]:configuration.md +[6]:general-config.md +[7]:modes.md +[8]:message.md +[9]:layouts.md +[10]:node_types.md +[11]:style.md +[12]:sorting.md +[13]:filtering.md +[14]:default-key-bindings.md +[15]:plugin.md +[16]:installing-plugins.md +[17]:writing-plugins.md +[18]:awesome-plugins.md +[19]:integration.md +[20]:awesome-integrations.md +[21]:todo.md +[22]:alternatives.md +[23]:upgrade-guide.md +[24]:community.md +[25]:contribute.md \ No newline at end of file diff --git a/docs/en/src/alternatives.md b/docs/en/src/alternatives.md index ee2872f..36a4bfe 100644 --- a/docs/en/src/alternatives.md +++ b/docs/en/src/alternatives.md @@ -3,17 +3,32 @@ Alternatives These are the alternative TUI/CLI file managers/explorers you might want to check out (in no particular order). -- [nnn](https://github.com/jarun/nnn/) -- [vifm](https://github.com/vifm/vifm) -- [ranger](https://github.com/ranger/ranger) -- [lf](https://github.com/gokcehan/lf) -- [joshuto](https://github.com/kamiyaa/joshuto) -- [fff](https://github.com/dylanaraps/fff) -- [mc](https://github.com/MidnightCommander/mc) -- [broot](https://github.com/Canop/broot) -- [hunter](https://github.com/rabite0/hunter) -- [noice](https://github.com/RichardHyde/noice) -- [clifm](https://github.com/pasqu4le/clifm) -- [clifm](https://github.com/leo-arch/clifm) (non curses) +- [nnn][1] +- [vifm][2] +- [ranger][3] +- [lf][4] +- [joshuto][5] +- [fff][6] +- [mc][7] +- [broot][8] +- [hunter][9] +- [noice][10] +- [clifm][11] +- [clifm][12] (non curses) -[add more](community.md) +[add more][13] + + +[1]:https://github.com/jarun/nnn/ +[2]:https://github.com/vifm/vifm +[3]:https://github.com/ranger/ranger +[4]:https://github.com/gokcehan/lf +[5]:https://github.com/kamiyaa/joshuto +[6]:https://github.com/dylanaraps/fff +[7]:https://github.com/MidnightCommander/mc +[8]:https://github.com/Canop/broot +[9]:https://github.com/rabite0/hunter +[10]:https://github.com/RichardHyde/noice +[11]:https://github.com/pasqu4le/clifm +[12]:https://github.com/leo-arch/clifm +[13]:community.md \ No newline at end of file diff --git a/docs/en/src/awesome-integrations.md b/docs/en/src/awesome-integrations.md index 2c128ca..1debf94 100644 --- a/docs/en/src/awesome-integrations.md +++ b/docs/en/src/awesome-integrations.md @@ -4,31 +4,41 @@ Awesome Integrations Here's a list of awesome xplr integrations that you might want to check out. If none of the following integrations work for you, you can create your own and -[let us know](https://github.com/sayanarijit/xplr/discussions/categories/show-and-tell). +[let us know][1]. Categories ---------- -- [Editor](#editor) -- [Shell](#shell) -- [Security Tools](#security-tools) +- [Editor][2] +- [Shell][3] +- [Security Tools][4] Editor ------ -- [xplr.vim](https://github.com/sayanarijit/xplr.vim) -- [vim-floaterm](https://github.com/voldikss/vim-floaterm#xplr) +- [xplr.vim][5] +- [vim-floaterm][6] Shell ----- -- [powerlevel10k](https://github.com/romkatv/powerlevel10k/blob/191d1b89e325ee3b6d2d75a394654aaf4f077a7c/internal/p10k.zsh#L4756-L4768) +- [powerlevel10k][7] Security Tools -------------- -- [gpg-tui](https://github.com/orhun/gpg-tui#importreceive) +- [gpg-tui][8] + + +[1]:https://github.com/sayanarijit/xplr/discussions/categories/show-and-tell +[2]:#editor +[3]:#shell +[4]:#security-tools +[5]:https://github.com/sayanarijit/xplr.vim +[6]:https://github.com/voldikss/vim-floaterm#xplr +[7]:https://github.com/romkatv/powerlevel10k/blob/191d1b89e325ee3b6d2d75a394654aaf4f077a7c/internal/p10k.zsh#L4756-L4768 +[8]:https://github.com/orhun/gpg-tui#importreceive \ No newline at end of file diff --git a/docs/en/src/awesome-plugins.md b/docs/en/src/awesome-plugins.md index b3db158..80d14bb 100644 --- a/docs/en/src/awesome-plugins.md +++ b/docs/en/src/awesome-plugins.md @@ -3,52 +3,74 @@ Awesome Plugins Here's a list of awesome xplr plugins that you might want to check out. If none of the following plugins work for you, it's very easy to -[write your own](./writing-plugins.md). +[write your own][1]. Categories ---------- -- [Integration](#integration) -- [Theme](#theme) +- [Integration][2] +- [Theme][3] Integration ----------- -- [dragon.xplr](https://github.com/sayanarijit/dragon.xplr) - Drag and drop files using [dragon](https://github.com/mwh/dragon). +- [dragon.xplr][4] + Drag and drop files using [dragon][5]. -- [dua-cli.xplr](https://github.com/sayanarijit/dua-cli.xplr) - Get the disk usage using [dua-cli](https://github.com/Byron/dua-cli) with +- [dua-cli.xplr][6] + Get the disk usage using [dua-cli][7] with selection support. -- [fzf.xplr](https://github.com/sayanarijit/fzf.xplr) - Fuzzy search using [fzf](https://github.com/junegunn/fzf) to focus on a file +- [fzf.xplr][8] + Fuzzy search using [fzf][9] to focus on a file or enter into a directory. -- [preview-tabbed.xplr](https://github.com/sayanarijit/preview-tabbed.xplr) - Preview paths using suckless [tabbed](https://tools.suckless.org/tabbed/) and - [nnn preview-tabbed](https://github.com/jarun/nnn/blob/master/plugins/preview-tabbed). +- [preview-tabbed.xplr][10] + Preview paths using suckless [tabbed][11] and + [nnn preview-tabbed][12]. -- [trash-cli.xplr](https://github.com/sayanarijit/trash-cli.xplr) +- [trash-cli.xplr][13] Trash files and directories using - [trash-cli](https://github.com/andreafrancia/trash-cli). + [trash-cli][14]. -- [xclip.xplr](https://github.com/sayanarijit/xclip.xplr) +- [xclip.xplr][15] Copy and paste with system clipboard using - [xclip](https://github.com/astrand/xclip). + [xclip][16]. -- [zoxide.xplr](https://github.com/sayanarijit/zoxide.xplr) - Change directory using the [zoxide](https://github.com/ajeetdsouza/zoxide) +- [zoxide.xplr][17] + Change directory using the [zoxide][18] database. Theme ----- -- [material-landscape.xplr](https://github.com/sayanarijit/material-landscape.xplr) +- [material-landscape.xplr][19] Material Landscape -- [material-landscape2.xplr](https://github.com/sayanarijit/material-landscape2.xplr) +- [material-landscape2.xplr][20] Material Landscape 2 + + +[1]:./writing-plugins.md +[2]:#integration +[3]:#theme +[4]:https://github.com/sayanarijit/dragon.xplr +[5]:https://github.com/mwh/dragon +[6]:https://github.com/sayanarijit/dua-cli.xplr +[7]:https://github.com/Byron/dua-cli +[8]:https://github.com/sayanarijit/fzf.xplr +[9]:https://github.com/junegunn/fzf +[10]:https://github.com/sayanarijit/preview-tabbed.xplr +[11]:https://tools.suckless.org/tabbed/ +[12]:https://github.com/jarun/nnn/blob/master/plugins/preview-tabbed +[13]:https://github.com/sayanarijit/trash-cli.xplr +[14]:https://github.com/andreafrancia/trash-cli +[15]:https://github.com/sayanarijit/xclip.xplr +[16]:https://github.com/astrand/xclip +[17]:https://github.com/sayanarijit/zoxide.xplr +[18]:https://github.com/ajeetdsouza/zoxide +[19]:https://github.com/sayanarijit/material-landscape.xplr +[20]:https://github.com/sayanarijit/material-landscape2.xplr \ No newline at end of file diff --git a/docs/en/src/community.md b/docs/en/src/community.md index 47511c0..f03bcc0 100644 --- a/docs/en/src/community.md +++ b/docs/en/src/community.md @@ -5,7 +5,11 @@ Building an active community of awesome people and learning stuff together is one of my reasons to publish this tool and maintain it. Hence, please feel free to reach out via your preferred way. -- Real-time chat lovers can [**join our discord channel**](https://discord.gg/JmasSPCcz3). -- Forum discussion veterans can [**start a new GitHub discussion**](https://github.com/sayanarijit/xplr/discussions). +- Real-time chat lovers can [**join our discord channel**][1]. +- Forum discussion veterans can [**start a new GitHub discussion**][2]. BTW I like Miyazaki and Shinkai works. + + +[1]:https://discord.gg/JmasSPCcz3 +[2]:https://github.com/sayanarijit/xplr/discussions \ No newline at end of file diff --git a/docs/en/src/configuration.md b/docs/en/src/configuration.md index 5aca223..7a8f69d 100644 --- a/docs/en/src/configuration.md +++ b/docs/en/src/configuration.md @@ -1,9 +1,9 @@ Configuration ============= -xplr can be configured using [Lua](https://www.lua.org/) via a special file +xplr can be configured using [Lua][1] via a special file named `init.lua` -([example](https://github.com/sayanarijit/xplr/blob/main/src/init.lua)), which +([example][2]), which can be placed in `~/.config/xplr/` (user specific) or `/etc/xplr/` (global) depending on the use case. @@ -20,7 +20,7 @@ How Config Is Loaded -------------------- When xplr loads, it first executes the built-in -[init.lua](https://github.com/sayanarijit/xplr/blob/main/src/init.lua) to set +[init.lua][2] to set the default values, which is then overwritten by another config file, if found using the following lookup order: @@ -33,7 +33,15 @@ config The xplr configuration, exposed as `xplr.config` Lua API contains the following fields: -- [general](general-config.md) -- [modes](modes.md) -- [layouts](layouts.md) -- [node_types](node_types.md) +- [general][3] +- [modes][4] +- [layouts][5] +- [node_types][6] + + +[1]:https://www.lua.org/ +[2]:https://github.com/sayanarijit/xplr/blob/main/src/init.lua +[3]:general-config.md +[4]:modes.md +[5]:layouts.md +[6]:node_types.md \ No newline at end of file diff --git a/docs/en/src/configure.md b/docs/en/src/configure.md index cbc66fe..24faff9 100644 --- a/docs/en/src/configure.md +++ b/docs/en/src/configure.md @@ -14,14 +14,14 @@ echo version = '"'${version:?}'"' > ~/.config/xplr/init.lua ``` Then -**[copy from here](https://github.com/sayanarijit/xplr/blob/main/src/init.lua)** +**[copy from here][1]** and remove / comment out what you don't want to customize. > **Note:** You don't generally need to create the config file. You can use the > default configuration for basic operations. However, creating the config file > is recommended because the project is in its early stage and the defaults > might change. Creating the config file will save you from unexpected behavior -> when you [upgrade](upgrade-guide.md). +> when you [upgrade][2]. > Also, the default configuration is very minimal (just enough to get you > started) and you'll probably want to adjust it to suit your workflow. @@ -32,3 +32,7 @@ Run ``` xplr ``` + + +[1]:https://github.com/sayanarijit/xplr/blob/main/src/init.lua +[2]:upgrade-guide.md \ No newline at end of file diff --git a/docs/en/src/contribute.md b/docs/en/src/contribute.md index 7186be8..ddeab8a 100644 --- a/docs/en/src/contribute.md +++ b/docs/en/src/contribute.md @@ -2,7 +2,7 @@ If you like xplr, and want to contribute, that would be really awesome. You can contribute to this project in the following ways -- Contribute your time and expertise (read [CONTRIBUTING.md](https://github.com/sayanarijit/xplr/blob/main/CONTRIBUTING.md) for instructions). +- Contribute your time and expertise (read [CONTRIBUTING.md][1] for instructions). - **Developers:** You can help me improve my code, fix things, implement features etc. - **Repository maintainers:** You can save the users from the pain of managing xplr in their system manually. - **Code Reviewers:** Teach me your ways of code. @@ -11,9 +11,15 @@ You can contribute to this project in the following ways - Contribute by donating. - - You can [fuel me with coins of encouragement](https://opencollective.com/xplr) or [buy me a coffee](https://ko-fi.com/sayanarijit). + - You can [fuel me with coins of encouragement][2] or [buy me a coffee][3]. -For further queries or concern related to `xplr`, [just ask us](community.md). +For further queries or concern related to `xplr`, [just ask us][4]. ### Backers + + +[1]:https://github.com/sayanarijit/xplr/blob/main/CONTRIBUTING.md +[2]:https://opencollective.com/xplr +[3]:https://ko-fi.com/sayanarijit +[4]:community.md \ No newline at end of file diff --git a/docs/en/src/default-key-bindings.md b/docs/en/src/default-key-bindings.md index 573f6cf..8200abb 100644 --- a/docs/en/src/default-key-bindings.md +++ b/docs/en/src/default-key-bindings.md @@ -1,12 +1,12 @@ Default Key Bindings ==================== -The default key binding is inspired by [vim](https://www.vim.org/) and slightly -overlaps with [nnn](https://github.com/jarun/nnn/), but it's supposed to be +The default key binding is inspired by [vim][1] and slightly +overlaps with [nnn][2], but it's supposed to be customized as per user requirements. -When you press `?` in [default mode](#default), you can see the complete list -of [modes](modes.md) and the key mappings for each mode. +When you press `?` in [default mode][3], you can see the complete list +of [modes][4] and the key mappings for each mode. ### default @@ -256,3 +256,9 @@ of [modes](modes.md) and the key mappings for each mode. 4 | | no help or selection ctrl-c | | terminate esc | | cancel + + +[1]:https://www.vim.org/ +[2]:https://github.com/jarun/nnn/ +[3]:#default +[4]:modes.md \ No newline at end of file diff --git a/docs/en/src/filtering.md b/docs/en/src/filtering.md index dd07911..bcfa804 100644 --- a/docs/en/src/filtering.md +++ b/docs/en/src/filtering.md @@ -15,7 +15,7 @@ the condition: *relative path does not start with `.`*, then by the condition: *absolute path contains `abc` (case insensitive)*, and finally by the condition: *relative path does not contain `xyz`* (case insensitive). -Each part of this pipeline is called [Node Filter Applicable](#node-filter-applicable). +Each part of this pipeline is called [Node Filter Applicable][1]. Node Filter Applicable @@ -23,8 +23,8 @@ Node Filter Applicable It contains the following information: -- [filter](#filter) -- [input](#input) +- [filter][2] +- [input][3] ### filter @@ -83,5 +83,11 @@ ToggleNodeFilter = { } ``` -Here, `ToggleNodeFilter` is a [message](message.md) that adds or removes +Here, `ToggleNodeFilter` is a [message][4] that adds or removes (toggles) the filter applied. + + +[1]:#node-filter-applicable +[2]:#filter +[3]:#input +[4]:message.md \ No newline at end of file diff --git a/docs/en/src/general-config.md b/docs/en/src/general-config.md index 6b238df..0c9968b 100644 --- a/docs/en/src/general-config.md +++ b/docs/en/src/general-config.md @@ -51,7 +51,7 @@ This is the shape of the cursor visible when the input buffer contains some stri cursor.style ------------ -Type: [Style](style.md) +Type: [Style][1] Style of the cursor. @@ -61,7 +61,7 @@ initial_layout Type: string -The name of one of the [layout](layouts.md) to use when xplr loads. +The name of one of the [layout][2] to use when xplr loads. initial_mode @@ -69,13 +69,13 @@ initial_mode Type: string -The name of one of the [mode](modes.md) to use when xplr loads. +The name of one of the [mode][3] to use when xplr loads. initial_sorting --------------- -Type: list of [Node Sorter Applicable](sorting.md#node-sorter-applicable) +Type: list of [Node Sorter Applicable][4] Initial group if sorters applied to the nodes list in the table. @@ -83,7 +83,7 @@ Initial group if sorters applied to the nodes list in the table. table.style ----------- -Type: [Style](style.md) +Type: [Style][1] Default style of the table. @@ -99,7 +99,7 @@ Default spacing of the columns in the table. table.col_widths ---------------- -Type: nullable list of [Constraint](layouts.md#constraint) +Type: nullable list of [Constraint][5] Width of each column in the table. @@ -114,7 +114,7 @@ Height of the table header. table.header.style --------------- -Type: [Style](style.md) +Type: [Style][1] Style of table header. @@ -125,7 +125,7 @@ table.header.cols Type: List of column configuration Each column config contains `format` field (string) and `style` field -([Style](style.md)), that define the content and style of header. +([Style][1]), that define the content and style of header. table.row.height @@ -139,7 +139,7 @@ Height of each row in the table. table.row.style --------------- -Type: [Style](style.md) +Type: [Style][1] Style of table rows. @@ -150,11 +150,11 @@ table.row.cols Type: List of column configuration Each column config contains `format` field (string) and `style` field -([Style](style.md)). +([Style][1]). -However, unlike [table.header.cols](#tableheadercols), the `format` field here +However, unlike [table.header.cols][6], the `format` field here points to a Lua function that receives a -[special argument](https://docs.rs/xplr/latest/xplr/ui/struct.NodeUiMetadata.html) +[special argument][7] as input and returns a string that will be displayed in the column. TODO: Document the argument fields here. @@ -198,3 +198,12 @@ xplr.config.general.table.col_widths = { ------------ TODO: Continue documentation + + +[1]:style.md +[2]:layouts.md +[3]:modes.md +[4]:sorting.md#node-sorter-applicable +[5]:layouts.md#constraint +[6]:#tableheadercols +[7]:https://docs.rs/xplr/latest/xplr/ui/struct.NodeUiMetadata.html \ No newline at end of file diff --git a/docs/en/src/install.md b/docs/en/src/install.md index ee001db..8d6bcc7 100644 --- a/docs/en/src/install.md +++ b/docs/en/src/install.md @@ -4,15 +4,15 @@ Install You can install xplr using one of the following ways. Each has their own advantages and limitations. -For example, the [Direct Download](#direct-download), -[From crates.io](#from-a-hrefhttpscratesiocratesxplrcratesioa), and -[Build From Source](#build-from-source) methods allow the users to install the +For example, the [Direct Download][1], +[From crates.io][2], and +[Build From Source][3] methods allow the users to install the latest possible version of xplr, but they have one common drawback - the user will need to keep an eye on the releases, and manually upgrade xplr when a new version is available. One way to keep an eye of the releases is to -[watch the repository](https://github.com/sayanarijit/xplr/watchers). +[watch the repository][4]. Community Maintained Repositories @@ -21,18 +21,18 @@ Community Maintained Repositories xplr can be installed from one of the following community maintained repositories: -[![packaging status](https://repology.org/badge/vertical-allrepos/xplr.svg)](https://repology.org/project/xplr/versions) +[![packaging status][5]][6] ### Arch Linux -#### [Official Community Repo](https://archlinux.org/packages/community/x86_64/xplr) +#### [Official Community Repo][7] ``` sudo pacman -S xplr ``` -#### [AUR](https://aur.archlinux.org/packages/?O=0&SeB=n&K=xplr&outdated=&SB=n&SO=a&PP=50&do_Search=Go) +#### [AUR][8] Binary version: @@ -48,11 +48,11 @@ paru -S xplr-git ### Void Linux -#### [void-templates by shubham](https://github.com/shubham-cpp/void-pkg-templates) +#### [void-templates by shubham][9] ### Nix(OS) -#### [Nixpkgs](https://github.com/NixOS/nixpkgs/blob/master/pkgs/applications/misc/xplr) +#### [Nixpkgs][10] ``` nix-env -f https://github.com/NixOS/nixpkgs/tarball/master -iA xplr @@ -60,14 +60,14 @@ nix-env -f https://github.com/NixOS/nixpkgs/tarball/master -iA xplr ### macOS -#### [MacPorts](https://ports.macports.org/port/xplr) +#### [MacPorts][11] ``` sudo port selfupdate sudo port install xplr ``` -#### [Homebrew](https://formulae.brew.sh/formula/xplr) +#### [Homebrew][12] Stable branch: @@ -83,7 +83,7 @@ brew install --head xplr ### FreeBSD -#### [ports](https://cgit.freebsd.org/ports/plain/misc/xplr/) +#### [ports][13] ``` cd /usr/ports/misc/xplr @@ -92,7 +92,7 @@ make install ### NetBSD -#### [pkgsrc](https://pkgsrc.se/sysutils/xplr) +#### [pkgsrc][14] ``` pkgin install xplr @@ -110,12 +110,12 @@ Direct Download --------------- One can directly download the standalone binary from the -[releases](https://github.com/sayanarijit/xplr/releases). +[releases][15]. Currently, the following options are available for direct download: -- [Linux](https://github.com/sayanarijit/xplr/releases/latest/download/xplr-linux.tar.gz) -- [macOS](https://github.com/sayanarijit/xplr/releases/latest/download/xplr-macos.tar.gz) +- [Linux][16] +- [macOS][17] Command-line instructions: @@ -133,14 +133,14 @@ sudo mv xplr /usr/local/bin/ ``` -From [crates.io](https://crates.io/crates/xplr) +From [crates.io][18] ----------------------------------------------- Prerequisites: -- [Rust toolchain](https://www.rust-lang.org/tools/install), -- [gcc](https://gcc.gnu.org/) -- [make](https://www.gnu.org/software/make/) +- [Rust toolchain][19], +- [gcc][20] +- [make][21] Command-line instructions: @@ -154,10 +154,10 @@ Build From Source Prerequisites: -- [git](https://git-scm.com/) -- [Rust toolchain](https://www.rust-lang.org/tools/install) -- [gcc](https://gcc.gnu.org/) -- [make](https://www.gnu.org/software/make/) +- [git][22] +- [Rust toolchain][19] +- [gcc][20] +- [make][21] Command-line instructions: @@ -177,9 +177,9 @@ sudo cp target/release/xplr /usr/local/bin/ Android ------- -### [Termux](https://termux.com/) +### [Termux][23] -[![xplr-termuxfd3c398d3cf4bcbc.md.jpg](https://s3.gifyu.com/images/xplr-termuxfd3c398d3cf4bcbc.md.jpg)](https://gifyu.com/image/tF2D) +[![xplr-termuxfd3c398d3cf4bcbc.md.jpg][24]][25] > Please note that xplr isn't heavily tested on Termux, hence things might > need a little tweaking and fixing for a smooth usage experience. @@ -215,3 +215,30 @@ Android ```bash ~/.cargo/bin/xplr ``` + + +[1]:#direct-download +[2]:#from-a-hrefhttpscratesiocratesxplrcratesioa +[3]:#build-from-source +[4]:https://github.com/sayanarijit/xplr/watchers +[5]:https://repology.org/badge/vertical-allrepos/xplr.svg +[6]:https://repology.org/project/xplr/versions +[7]:https://archlinux.org/packages/community/x86_64/xplr +[8]:https://aur.archlinux.org/packages/?O=0&SeB=n&K=xplr&outdated=&SB=n&SO=a&PP=50&do_Search=Go +[9]:https://github.com/shubham-cpp/void-pkg-templates +[10]:https://github.com/NixOS/nixpkgs/blob/master/pkgs/applications/misc/xplr +[11]:https://ports.macports.org/port/xplr +[12]:https://formulae.brew.sh/formula/xplr +[13]:https://cgit.freebsd.org/ports/plain/misc/xplr/ +[14]:https://pkgsrc.se/sysutils/xplr +[15]:https://github.com/sayanarijit/xplr/releases +[16]:https://github.com/sayanarijit/xplr/releases/latest/download/xplr-linux.tar.gz +[17]:https://github.com/sayanarijit/xplr/releases/latest/download/xplr-macos.tar.gz +[18]:https://crates.io/crates/xplr +[19]:https://www.rust-lang.org/tools/install +[20]:https://gcc.gnu.org/ +[21]:https://www.gnu.org/software/make/ +[22]:https://git-scm.com/ +[23]:https://termux.com/ +[24]:https://s3.gifyu.com/images/xplr-termuxfd3c398d3cf4bcbc.md.jpg +[25]:https://gifyu.com/image/tF2D \ No newline at end of file diff --git a/docs/en/src/installing-plugins.md b/docs/en/src/installing-plugins.md index 47e57db..45b05be 100644 --- a/docs/en/src/installing-plugins.md +++ b/docs/en/src/installing-plugins.md @@ -25,4 +25,4 @@ following procedure: -- The setup arguments might differ for different plugins. -- Visit the project README for setup instructions. - ``` + ``` \ No newline at end of file diff --git a/docs/en/src/integration.md b/docs/en/src/integration.md index fce28b5..8b13d05 100644 --- a/docs/en/src/integration.md +++ b/docs/en/src/integration.md @@ -4,4 +4,7 @@ Integration xplr is designed to integrate well with other tools and commands. It can be used as a file picker or a pluggable file manager. -- [Awesome Integrations](awesome-integrations.md) +- [Awesome Integrations][1] + + +[1]:awesome-integrations.md \ No newline at end of file diff --git a/docs/en/src/introduction.md b/docs/en/src/introduction.md index 2e1222c..5d9108d 100644 --- a/docs/en/src/introduction.md +++ b/docs/en/src/introduction.md @@ -25,9 +25,9 @@ set of operations and make it behave just the way you want. A few things you can do with the xplr configuration -- [Hack the layout](layouts.md) -- [Hack the key bindings](modes.md) -- [Extend with plugins](awesome-plugins.md) +- [Hack the layout][1] +- [Hack the key bindings][2] +- [Extend with plugins][3] ## Fast @@ -35,7 +35,7 @@ A few things you can do with the xplr configuration Although speed is not the primary concern, xplr is already fast enough so that you can take it out for a walk into your `node_modules` or `/nix/store` any time you want. I currently -[measure the most commonly used operations](https://github.com/sayanarijit/xplr/tree/main/benches) +[measure the most commonly used operations][4] and I have seen it improve significantly over time, and it's only the start. **Tip:** A quick and easy way to optimize UI rendering is reducing the number @@ -59,7 +59,7 @@ will also be considered in the decision-making. ## Other features -- [Embedded LuaJIT](https://github.com/sayanarijit/xplr/discussions/183) for +- [Embedded LuaJIT][5] for portability and extensibility. - **Switchable recover mode:** Saves you from doing unwanted things when in a hurry. @@ -101,7 +101,7 @@ will also be considered in the decision-making. - **Auto refresh state:** Auto refresh app state when the `$PWD` changes. - **Manually refresh UI** when other apps mess it up. - **FIFO-based previews:** Easy to manage FIFO file that can be used to - [integrate with previewers](https://github.com/sayanarijit/xplr/pull/229). + [integrate with previewers][6]. - **Different quit options:** - Quit with success without any output (`q`). - Quit with success and the result printed on stdout (`enter`). @@ -112,3 +112,11 @@ will also be considered in the decision-making. - Quit with success and the selection printed on stdout (`:` `q` `s`). - Quit with failure (`ctrl-c`). + + +[1]:layouts.md +[2]:modes.md +[3]:awesome-plugins.md +[4]:https://github.com/sayanarijit/xplr/tree/main/benches +[5]:https://github.com/sayanarijit/xplr/discussions/183 +[6]:https://github.com/sayanarijit/xplr/pull/229 \ No newline at end of file diff --git a/docs/en/src/key-bindings.md b/docs/en/src/key-bindings.md index fc333e3..9bd82af 100644 --- a/docs/en/src/key-bindings.md +++ b/docs/en/src/key-bindings.md @@ -1 +1 @@ -# Key Bindings +# Key Bindings \ No newline at end of file diff --git a/docs/en/src/layouts.md b/docs/en/src/layouts.md index 94ec11b..67e3b68 100644 --- a/docs/en/src/layouts.md +++ b/docs/en/src/layouts.md @@ -7,8 +7,8 @@ placement and size of the panels, how they look etc. This is configuration exposed via the `xplr.config.layouts` API. It contains the following fields: -- [builtin](#builtin) -- [custom](#custom) +- [builtin][1] +- [custom][2] The users can switch between these layouts at run-time. @@ -16,38 +16,38 @@ The users can switch between these layouts at run-time. builtin ------- -Type: mapping of string and [Layout](#layout) +Type: mapping of string and [Layout][3] This is exposed by the `xplr.config.layouts.builtin` API. xplr by default provides the following builtin layouts: -- [default](#default) -- [no_help](#no_help) -- [no_selection](#no_selection) -- [no_help_no_selection](#no_help_no_selection) +- [default][4] +- [no_help][5] +- [no_selection][6] +- [no_help_no_selection][7] ### default -Type: [Layout](#layout) +Type: [Layout][3] This is the default layout we see when we run xplr. ### no_help -Type: [Layout](#layout) +Type: [Layout][3] This layout hides the help menu. ### no_selection -Type: [Layout](#layout) +Type: [Layout][3] This layout hides the selection panel. ### no_help_no_selection -Type: [Layout](#layout) +Type: [Layout][3] This layout hides both the help menu and the selection panel. @@ -55,7 +55,7 @@ This layout hides both the help menu and the selection panel. custom ------ -Type: mapping of string and [Layout](#layout) +Type: mapping of string and [Layout][3] This is exposed by the `xplr.config.layouts.custom` API. @@ -75,14 +75,14 @@ Layout A layout can be one of the following: -- ["Nothing"](#nothing) -- ["Table"](#table) -- ["InputAndLogs"](#inputandlogs) -- ["Selection"](#selection) -- ["HelpMenu"](#helpmenu) -- ["SortAndFilter"](#sortandfilter) -- { [Horizontal](#horizontal) = { config = [Layout Config](#layout-config), splits = { [Layout](#layout), ... } } -- { [Vertical](#vertical) = { config = [Layout Config](#layout-config), splits = { [Layout](#layout), ... } } +- ["Nothing"][8] +- ["Table"][9] +- ["InputAndLogs"][10] +- ["Selection"][11] +- ["HelpMenu"][12] +- ["SortAndFilter"][13] +- { [Horizontal][14] = { config = [Layout Config][15], splits = { [Layout][3], ... } } +- { [Vertical][16] = { config = [Layout Config][15], splits = { [Layout][3], ... } } ### Nothing @@ -117,8 +117,8 @@ This is a special layout that splits the panel into two horizontal parts. It contains the following information: -- [config](#layout-config) -- [splits](#splits) +- [config][15] +- [splits][17] ### Vertical @@ -126,8 +126,8 @@ This is a special layout that splits the panel into two vertical parts. It contains the following information: -- [config](#layout-config) -- [splits](#splits) +- [config][15] +- [splits][17] Layout Config @@ -135,10 +135,10 @@ Layout Config A layout config contains the following information: -- [margin](#margin) -- [horizontal_margin](#horizontal_margin) -- [vertical_margin](#vertical_margin) -- [constraints](#constraints) +- [margin][18] +- [horizontal_margin][19] +- [vertical_margin][20] +- [constraints][21] ### margin @@ -150,17 +150,17 @@ The width of the margin in all direction. Type: nullable integer -The width of the horizontal margins. Overwrites the [margin](#margin) value. +The width of the horizontal margins. Overwrites the [margin][18] value. ### vertical_Margin Type: nullable integer -The width of the vertical margins. Overwrites the [margin](#margin) value. +The width of the vertical margins. Overwrites the [margin][18] value. ### constraints -Type: nullable list of [Constraint](#constraint) +Type: nullable list of [Constraint][22] The constraints applied on the layout. @@ -194,7 +194,7 @@ TODO: document each constraint. splits ------ -Type: list of [Layout](#layout) +Type: list of [Layout][3] The list of child layouts to fit into the parent layout. @@ -202,7 +202,7 @@ The list of child layouts to fit into the parent layout. Example ------- -[![layout.png](https://s6.gifyu.com/images/layout.png)](https://gifyu.com/image/1X38) +[![layout.png][23]][24] ```lua xplr.config.layouts.builtin.default = { @@ -223,3 +223,29 @@ xplr.config.layouts.builtin.default = { } } ``` + + +[1]:#builtin +[2]:#custom +[3]:#layout +[4]:#default +[5]:#no_help +[6]:#no_selection +[7]:#no_help_no_selection +[8]:#nothing +[9]:#table +[10]:#inputandlogs +[11]:#selection +[12]:#helpmenu +[13]:#sortandfilter +[14]:#horizontal +[15]:#layout-config +[16]:#vertical +[17]:#splits +[18]:#margin +[19]:#horizontal_margin +[20]:#vertical_margin +[21]:#constraints +[22]:#constraint +[23]:https://s6.gifyu.com/images/layout.png +[24]:https://gifyu.com/image/1X38 \ No newline at end of file diff --git a/docs/en/src/message.md b/docs/en/src/message.md index 4d74587..2b3d75f 100644 --- a/docs/en/src/message.md +++ b/docs/en/src/message.md @@ -2,29 +2,29 @@ Message ======= You can think of xplr as a server. Just like web servers listen to HTTP -requests, xplr listens to [messages](#full-list-of-messages). +requests, xplr listens to [messages][1]. You can send these messages to an xplr session in the following ways: -- Via [key bindings](modes.md#key-bindings) -- Via [Lua function calls](#lua-function-calls) -- Via shell command using the [input pipe](#input-pipe) +- Via [key bindings][2] +- Via [Lua function calls][3] +- Via shell command using the [input pipe][4] Format ------ -To send messages using the [key bindings](modes.md#key-bindings) or -[Lua functions calls](#lua-functions-calls), messages are represented in -[Lua](https://www.lua.org/) syntax. For example: +To send messages using the [key bindings][2] or +[Lua function calls][3], messages are represented in +[Lua][5] syntax. For example: - "Quit" - { FocusPath = "/path/to/file" } - { Call = { command = "bash", args = { "-c", "read -p test" } } } -However, to send messages using the [input pipe](#input-pipe), they need to be +However, to send messages using the [input pipe][4], they need to be represented using -[YAML](http://yaml.org/) (or [JSON](https://www.json.org)) syntax. For example: +[YAML][6] (or [JSON][7]) syntax. For example: - Quit - FocusPath: "/path/to/file" @@ -266,7 +266,7 @@ Reset the input buffer back to null. It will not show in the UI. **YAML:** `SwitchMode: string` -Switch input [mode](modes.md). +Switch input [mode][8]. > **NOTE:** To be specific about which mode to switch to, use `SwitchModeBuiltin` or `SwitchModeCustom` instead. @@ -279,7 +279,7 @@ Switch input [mode](modes.md). **YAML:** `SwitchModeBuiltin: string` -Switch to a [builtin mode](modes.md#builtin). +Switch to a [builtin mode][9]. **YAML Example:** `SwitchModeBuiltin: default` @@ -289,7 +289,7 @@ Switch to a [builtin mode](modes.md#builtin). **YAML:** `SwitchModeCustom: string` -Switch to a [custom mode](modes.md#custom). +Switch to a [custom mode][10]. **YAML Example:** `SwitchModeCustom: my_custom_mode` @@ -305,7 +305,7 @@ Pop the last mode from the history and switch to it. **YAML:** `SwitchLayout: string` -Switch [layout](layouts.md). +Switch [layout][11]. > **NOTE:** To be specific about which layout to switch to, use `SwitchLayoutBuiltin` or `SwitchLayoutCustom` instead. @@ -318,7 +318,7 @@ Switch [layout](layouts.md). **YAML:** `SwitchLayoutBuiltin: string` -Switch to a [builtin layout](layouts.md#builtin). +Switch to a [builtin layout][12]. **YAML Example:** `SwitchLayoutBuiltin: default` @@ -328,7 +328,7 @@ Switch to a [builtin layout](layouts.md#builtin). **YAML:** `SwitchLayoutCustom: string` -Switch to a [custom layout](layouts.md#custom). +Switch to a [custom layout][13]. **YAML Example:** `SwitchLayoutCustom: my_custom_layout` @@ -364,8 +364,8 @@ stderr will be piped to null. So it's non-interactive. **YAML:** `CallLua: string` Call a Lua function. -A [`CallLuaArg`](#calllua-argument) object will be passed to the -[function](#lua-function-calls) as argument. +A [`CallLuaArg`][14] object will be passed to the +[function][3] as argument. The function can optionally return a list of messages for xplr to handle after the executing the function. @@ -478,51 +478,51 @@ Toggle selection by file path. Clear the selection. -### { AddNodeFilter = { filter = [Filter](filtering.md#filter), input = "string" } +### { AddNodeFilter = { filter = [Filter][15], input = "string" } **YAML:** `AddNodeFilter: { filter = Filter, input = string }` -Add a [filter](filtering.md) to exclude nodes while exploring directories. +Add a [filter][16] to exclude nodes while exploring directories. **YAML Example:** `AddNodeFilter: { filter: RelativePathDoesStartWith, input: foo }` **Lua Example:** `{ AddNodeFilter = { filter = "RelativePathDoesStartWith", input = "foo" } }` -### { RemoveNodeFilter = { filter = [Filter](filtering.md#filter), input = "string" } +### { RemoveNodeFilter = { filter = [Filter][15], input = "string" } **YAML:** `RemoveNodeFilter: { filter = Filter, input = string` -Remove an existing [filter](filtering.md). +Remove an existing [filter][16]. **YAML Example:** `RemoveNodeFilter: { filter: RelativePathDoesStartWith, input: foo }` **Lua Example:** `{ RemoveNodeFilter: { filter: "RelativePathDoesStartWith", input: "foo" } }` -### { ToggleNodeFilter = { filter = [Filter](filtering.md#filter), input = "string" } +### { ToggleNodeFilter = { filter = [Filter][15], input = "string" } **YAML:** `ToggleNodeFilter: { filter = Filter, input = string }` -Remove a [filter](filtering.md) if it exists, else, add a it. +Remove a [filter][16] if it exists, else, add a it. **YAML Example:** `ToggleNodeFilter: { filter: RelativePathDoesStartWith, input: foo }` **Lua Example:** `{ ToggleNodeFilter = { filter = "RelativePathDoesStartWith", input = "foo" } }` -### { AddNodeFilterFromInput = [Filter](filtering.md#filter) } +### { AddNodeFilterFromInput = [Filter][15] } **YAML:** `AddNodeFilterFromInput: Filter` -Add a node [filter](filtering.md) reading the input from the buffer. +Add a node [filter][16] reading the input from the buffer. **YAML Example:** `AddNodeFilterFromInput: RelativePathDoesStartWith` **Lua Example:** `{ AddNodeFilterFromInput = "RelativePathDoesStartWith" }` -### { RemoveNodeFilterFromInput = [Filter](filtering.md#filter) } +### { RemoveNodeFilterFromInput = [Filter][15] } **YAML:** `RemoveNodeFilterFromInput: Filter` -Remove a node [filter](filtering.md) reading the input from the buffer. +Remove a node [filter][16] reading the input from the buffer. **YAML Example:** `RemoveNodeFilterFromInput: RelativePathDoesStartWith` @@ -532,56 +532,56 @@ Remove a node [filter](filtering.md) reading the input from the buffer. **YAML:** `RemoveLastNodeFilter` -Remove the last node [filter](filtering.md). +Remove the last node [filter][16]. ### "ResetNodeFilters" **YAML:** `ResetNodeFilters` -Reset the node [filters](filtering.md) back to the default configuration. +Reset the node [filters][16] back to the default configuration. ### "ClearNodeFilters" **YAML:** `ClearNodeFilters` -Clear all the node [filters](filtering.md). +Clear all the node [filters][16]. -### { AddNodeSorter = { sorter = [Sorter](sorting.md#sorter), reverse = bool } } +### { AddNodeSorter = { sorter = [Sorter][17], reverse = bool } } **YAML:** `AddNodeSorter: { sorter: Sorter, reverse = bool }` -Add a [sorter](sorting.md#sorter) to sort nodes while exploring directories. +Add a [sorter][17] to sort nodes while exploring directories. **YAML Example:** `AddNodeSorter: { sorter: ByRelativePath, reverse: false }` **YAML Example:** `{ AddNodeSorter = { sorter = "ByRelativePath", reverse = false } }` -### { RemoveNodeSorter = [Sorter](sorting.md#sorter) } +### { RemoveNodeSorter = [Sorter][17] } **YAML:** `RemoveNodeSorter: Sorter` -Remove an existing [sorter](sorting.md#sorter). +Remove an existing [sorter][17]. **YAML Example:** `RemoveNodeSorter: ByRelativePath` **Lua Example:** `{ RemoveNodeSorter = "ByRelativePath" }` -### { ReverseNodeSorter = [Sorter](sorting.md#sorter) } +### { ReverseNodeSorter = [Sorter][17] } **YAML:** `ReverseNodeSorter: Sorter` -Reverse a node [sorter](sorting.md#sorter). +Reverse a node [sorter][17]. **YAML Example:** `ReverseNodeSorter: ByRelativePath` **Lua Example:** `{ ReverseNodeSorter = "ByRelativePath" }` -### { ToggleNodeSorter = { sorter = [Sorter](sorting.md#sorter), reverse = bool } } +### { ToggleNodeSorter = { sorter = [Sorter][17], reverse = bool } } **YAML:** `ToggleNodeSorter: { sorter: Sorter, reverse = bool }` -Remove a [sorter](sorting.md#sorter) if it exists, else, add a it. +Remove a [sorter][17] if it exists, else, add a it. **YAML Example:** `ToggleSorterSorter: {sorter: ByRelativePath, reverse: false }` @@ -591,25 +591,25 @@ Remove a [sorter](sorting.md#sorter) if it exists, else, add a it. **YAML:** `ReverseNodeSorters` -Reverse the node [sorters](sorting.md#sorter). +Reverse the node [sorters][17]. ### "RemoveLastNodeSorter" **YAML:** `RemoveLastNodeSorter` -Remove the last node [sorter](sorting.md#sorter). +Remove the last node [sorter][17]. ### "ResetNodeSorters" **YAML:** `ResetNodeSorters` -Reset the node [sorters](sorting.md#sorter) back to the default configuration. +Reset the node [sorters][17] back to the default configuration. ### "ClearNodeSorters" **YAML:** `ClearNodeSorters` -Clear all the node [sorters](sorting.md#sorter). +Clear all the node [sorters][17]. ### "EnableMouse" @@ -756,7 +756,7 @@ xplr allows users to define lua functions using the `xplr.fn.custom` Lua API. These functions can be called using messages like `CallLua`, `CallLuaSilently`. -When called the function receives a [special argument](#calllua-argument) that +When called the function receives a [special argument][14] that contains some useful information. The function can optionally return a list of messages which will be handled by xplr. @@ -783,7 +783,7 @@ It contains the following information: - last_modes TODO: Document each. For now, refer to the -[rust doc](https://docs.rs/xplr/latest/xplr/app/struct.CallLuaArg.html#fields). +[rust doc][18]. ### Example: @@ -826,7 +826,7 @@ information and send messages via environment variables and temporary files called "pipe"s. These environment variables and files are only available when a command is being executed. -Visit the [**fzf integration tutorial**](modes.md#tutorial-adding-a-new-mode) +Visit the [**fzf integration tutorial**][19] for example. ### Environment variables @@ -864,24 +864,24 @@ called "pipe"s. Current there is only one input pipe. -- [XPLR_PIPE_MSG_IN](#xplr_pipe_msg_in) +- [XPLR_PIPE_MSG_IN][20] #### Output pipes `XPLR_PIPE_*_OUT` are the output pipes that contain data which cannot be exposed directly via environment variables, like multi-line string. -- [XPLR_PIPE_SELECTION_OUT](#xplr_pipe_selection_out) -- [XPLR_PIPE_GLOBAL_HELP_MENU_OUT](#xplr_pipe_global_help_menu_out) -- [XPLR_PIPE_LOGS_OUT](#xplr_pipe_logs_out) -- [XPLR_PIPE_RESULT_OUT](#xplr_pipe_result_out) -- [XPLR_PIPE_HISTORY_OUT](#xplr_pipe_history_out) -- [XPLR_PIPE_DIRECTORY_NODES_OUT](#xplr_pipe_directory_nodes_out) +- [XPLR_PIPE_SELECTION_OUT][21] +- [XPLR_PIPE_GLOBAL_HELP_MENU_OUT][22] +- [XPLR_PIPE_LOGS_OUT][23] +- [XPLR_PIPE_RESULT_OUT][24] +- [XPLR_PIPE_HISTORY_OUT][25] +- [XPLR_PIPE_DIRECTORY_NODES_OUT][26] #### XPLR_PIPE_MSG_IN -Append new-line delimited messages to this pipe in [YAML](https://www.yaml.org) -(or [JSON](https://www.json.org)) syntax. These messages will be read and +Append new-line delimited messages to this pipe in [YAML][27] +(or [JSON][7]) syntax. These messages will be read and handled by xplr after the command execution. #### XPLR_PIPE_SELECTION_OUT @@ -907,7 +907,7 @@ New-line delimited list of last visited paths (similar to jump list in vim). #### XPLR_PIPE_DIRECTORY_NODES_OUT New-line delimited list of paths, filtered and sorted as displayed in the -[files table](layouts.md#table). +[files table][28]. ### Example: @@ -934,3 +934,33 @@ xplr.config.modes.builtin.default.key_bindings.on_key.space = { -- name. Enter your name to receive a nice greeting and to know your location. ``` + + +[1]:#full-list-of-messages +[2]:modes.md#key-bindings +[3]:#lua-function-calls +[4]:#input-pipe +[5]:https://www.lua.org/ +[6]:http://yaml.org/ +[7]:https://www.json.org +[8]:modes.md +[9]:modes.md#builtin +[10]:modes.md#custom +[11]:layouts.md +[12]:layouts.md#builtin +[13]:layouts.md#custom +[14]:#calllua-argument +[15]:filtering.md#filter +[16]:filtering.md +[17]:sorting.md#sorter +[18]:https://docs.rs/xplr/latest/xplr/app/struct.CallLuaArg.html#fields +[19]:modes.md#tutorial-adding-a-new-mode +[20]:#xplr_pipe_msg_in +[21]:#xplr_pipe_selection_out +[22]:#xplr_pipe_global_help_menu_out +[23]:#xplr_pipe_logs_out +[24]:#xplr_pipe_result_out +[25]:#xplr_pipe_history_out +[26]:#xplr_pipe_directory_nodes_out +[27]:https://www.yaml.org +[28]:layouts.md#table \ No newline at end of file diff --git a/docs/en/src/modes.md b/docs/en/src/modes.md index c440954..36204cb 100644 --- a/docs/en/src/modes.md +++ b/docs/en/src/modes.md @@ -9,14 +9,14 @@ The modes can be configured using the `xplr.config.modes` Lua API. It contains the following fields: -- [builtin](#builtin) -- [custom](#custom) +- [builtin][1] +- [custom][2] builtin ------- -Type: mapping of string and [Mode](#mode) +Type: mapping of string and [Mode][3] This is exposed by the `xplr.config.modes.builtin` API. @@ -41,14 +41,14 @@ xplr by default provides the following builtin modes: - switch_layout - quit -Visit the [Default Key Bindings](default-key-bindings.md) to see what each mode +Visit the [Default Key Bindings][4] to see what each mode does. custom ------ -Type: mapping of string and [Mode](#mode) +Type: mapping of string and [Mode][3] This is exposed by the `xplr.config.modes.custom` API. @@ -84,10 +84,10 @@ Mode A mode contains the following information: -- [name](#name) -- [help](#help) -- [extra_help](#extra_help) -- [key_bindings](#key_bindings) +- [name][5] +- [help][6] +- [extra_help][7] +- [key_bindings][8] ### name @@ -111,7 +111,7 @@ help menu. ### key_bindings -Type: [Key Bindings](#key-bindings) +Type: [Key Bindings][9] The key bindings available in that mode. @@ -121,50 +121,50 @@ Key Bindings Key bindings define how each keyboard input will be handled in a specific mode. -See the [default key bindings](default-key-bindings.md) for example. +See the [default key bindings][4] for example. Key bindings contains the following information: -- [on_key](#on_key) -- [on_alphabet](#on_alphabet) -- [on_number](#on_number) -- [on_special_character](#on_special_character) -- [default](#default) +- [on_key][10] +- [on_alphabet][11] +- [on_number][12] +- [on_special_character][13] +- [default][14] ### on_key -Type: mapping of [Key](#key) to nullable [Action](#action) +Type: mapping of [Key][15] to nullable [Action][16] Defines what to do when a specific key is pressed. ### on_alphabet -Type: nullable [Action](#action) +Type: nullable [Action][16] An action to perform if the keyboard input is an alphabet and is not mapped via -the [on_key](#on_key) field. +the [on_key][10] field. ### on_number -Type: nullable [Action](#action) +Type: nullable [Action][16] An action to perform if the keyboard input is a number and is not mapped via -the [on_key](#on_key) field. +the [on_key][10] field. ### on_special_character -Type: nullable [Action](#action) +Type: nullable [Action][16] An action to perform if the keyboard input is a special character and is not -mapped via the [on_key](#on_key) field. +mapped via the [on_key][10] field. ### default -Type: nullable [Action](#action) +Type: nullable [Action][16] Default action to perform in case of a keyboard input not mapped via any of the -[on_key](#on_key), [on_alphabet](#on_alphabet), [on_number](#on_number) or -[on_special_character](#on_special_character) field. +[on_key][10], [on_alphabet][11], [on_number][12] or +[on_special_character][13] field. Key @@ -227,7 +227,7 @@ Action An action contains the following information: - help -- [messages](#messages) +- [messages][17] ### help @@ -238,7 +238,7 @@ menu. ### messages -Type: A list of [Message](message.md) to send. +Type: A list of [Message][18] to send. The list of messages to send when a key is pressed. @@ -246,8 +246,8 @@ The list of messages to send when a key is pressed. Tutorial: Adding a New Mode --------------------------- -Assuming xplr is [installed](install.md) and [setup](post-install.md), let's -add our own mode to integrate xplr with [fzf](https://github.com/junegunn/fzf). +Assuming xplr is [installed][19] and [setup][20], let's +add our own mode to integrate xplr with [fzf][21]. We'll call it `fzxplr` mode. @@ -290,11 +290,11 @@ As you can see, the key `F` in mode `fzxplr` (the name can be anything) executes a script in `bash`. `BashExec`, `PopMode`, `SwitchModeBuiltin`, `ChangeDirectory` and `FocusPath` -are [messages](message.md), `$XPLR_PIPE_MSG_IN`, +are [messages][18], `$XPLR_PIPE_MSG_IN`, `$XPLR_PIPE_DIRECTORY_NODES_OUT` are -[environment variables](message.md#environment-variables) exported by `xplr` +[environment variables][22] exported by `xplr` before executing the command. They contain the path to the -[input](message.md#input-pipe) and [output](message.md#output-pipes) pipes that +[input][23] and [output][24] pipes that allows external tools to interact with `xplr`. Now that we have our new mode ready, let's add an entry point to this mode via @@ -311,8 +311,38 @@ xplr.config.modes.builtin.default.key_bindings.on_key["F"] = { Now let's try out the new `xplr`-`fzf` integration. -[![xplr-fzf.gif](https://s3.gifyu.com/images/xplr-fzf.gif)](https://gifyu.com/image/tW86) +[![xplr-fzf.gif][25]][26] ----- -Visit [Awesome Plugins](awesome-plugins.md) for more [integration](awesome-plugins.md#integration) options. +Visit [Awesome Plugins][27] for more [integration][28] options. + + +[1]:#builtin +[2]:#custom +[3]:#mode +[4]:default-key-bindings.md +[5]:#name +[6]:#help +[7]:#extra_help +[8]:#key_bindings +[9]:#key-bindings +[10]:#on_key +[11]:#on_alphabet +[12]:#on_number +[13]:#on_special_character +[14]:#default +[15]:#key +[16]:#action +[17]:#messages +[18]:message.md +[19]:install.md +[20]:post-install.md +[21]:https://github.com/junegunn/fzf +[22]:message.md#environment-variables +[23]:message.md#input-pipe +[24]:message.md#output-pipes +[25]:https://s3.gifyu.com/images/xplr-fzf.gif +[26]:https://gifyu.com/image/tW86 +[27]:awesome-plugins.md +[28]:awesome-plugins.md#integration \ No newline at end of file diff --git a/docs/en/src/node_types.md b/docs/en/src/node_types.md index 03d86ac..bf1ef6a 100644 --- a/docs/en/src/node_types.md +++ b/docs/en/src/node_types.md @@ -8,12 +8,12 @@ This can be configured using the `xplr.config.node_types` Lua API. It contains the following fields: -- [directory](#directory) -- [file](#file) -- [symlink](#symlink) -- [mime_essence](#mime_essence) -- [extension](#extension) -- [special](#special) +- [directory][1] +- [file][2] +- [symlink][3] +- [mime_essence][4] +- [extension][5] +- [special][6] One node can fall into multiple categories. For example, a node can have the extension `md`, and be a `file`. In that case, the properties from the more @@ -26,7 +26,7 @@ The priority is: ### directory -Type: [NodeType Config](#nodetype-config) +Type: [NodeType Config][7] Properties related to directories are defined here. @@ -42,7 +42,7 @@ xplr.config.node_types.directory.style.add_modifiers = { "Bold" } ### file -Type: [NodeType Config](#nodetype-config) +Type: [NodeType Config][7] Properties related to regular files are defined here. @@ -58,7 +58,7 @@ xplr.config.node_types.file.style.fg = "White" ### symlink -Type: [NodeType Config](#nodetype-config) +Type: [NodeType Config][7] Properties related to symlink are defined here. @@ -72,7 +72,7 @@ xplr.config.node_types.symlink.style.add_modifiers = { "Italic" } ### mime_essence -Type: mapping of mime-type and mapping of mime-subtype and [NodeType Config](#nodetype-config) +Type: mapping of mime-type and mapping of mime-subtype and [NodeType Config][7] Properties related to files with specific mime types are defined here. @@ -98,7 +98,7 @@ xplr.config.node_types.mime_essence = { ### extension -Type: mapping of extension and [NodeType Config](#nodetype-config) +Type: mapping of extension and [NodeType Config][7] Properties related to files with specific extension are defined here. @@ -111,7 +111,7 @@ xplr.config.node_types.extension.rs = { meta = { icon = "🦀" } } ### special -Type: mapping of name and [NodeType Config](#nodetype-config) +Type: mapping of name and [NodeType Config][7] Properties related to files and directories with special names are defined here. @@ -129,16 +129,16 @@ NodeType Config A node-type config contains the following fields: -- [meta](#meta) -- [style](style.md) +- [meta][8] +- [style][9] ### meta Type: mapping of string and string A meta field can contain custom metadata about a node. By default, the "icon" -metadata is set for the [directory](#directory), [file](#file), and -[symlink](#symlink) nodes. +metadata is set for the [directory][1], [file][2], and +[symlink][3] nodes. Example: @@ -150,3 +150,14 @@ xplr.config.node_types.file = { } } ``` + + +[1]:#directory +[2]:#file +[3]:#symlink +[4]:#mime_essence +[5]:#extension +[6]:#special +[7]:#nodetype-config +[8]:#meta +[9]:style.md \ No newline at end of file diff --git a/docs/en/src/plugin.md b/docs/en/src/plugin.md index ca931e8..21ac2a1 100644 --- a/docs/en/src/plugin.md +++ b/docs/en/src/plugin.md @@ -4,6 +4,11 @@ Plugin xplr supports pluggable Lua modules that can be used to easily configure or extend xplr UI and functionalities. -- [Installing Plugins](installing-plugins.md) -- [Writing Plugins](writing-plugins.md) -- [Awesome Plugins](awesome-plugins.md) +- [Installing Plugins][1] +- [Writing Plugins][2] +- [Awesome Plugins][3] + + +[1]:installing-plugins.md +[2]:writing-plugins.md +[3]:awesome-plugins.md \ No newline at end of file diff --git a/docs/en/src/post-install.md b/docs/en/src/post-install.md index 11db79c..7ab05e4 100644 --- a/docs/en/src/post-install.md +++ b/docs/en/src/post-install.md @@ -1,7 +1,7 @@ Post Install ============ -Once [installed](install.md), use the following steps to setup and run xplr. +Once [installed][1], use the following steps to setup and run xplr. Create the customizable config file ----------------------------------- @@ -17,14 +17,14 @@ echo version = '"'${version:?}'"' > ~/.config/xplr/init.lua ``` Then -**[copy from here](https://github.com/sayanarijit/xplr/blob/main/src/init.lua)** +**[copy from here][2]** and remove / comment out what you don't want to customize. > **Note:** You don't generally need to create the config file. You can use the > default configuration for basic operations. However, creating the config file > is recommended because the project is in its early stage and the defaults > might change. Creating the config file will save you from unexpected behavior -> when you [upgrade](upgrade-guide.md). +> when you [upgrade][3]. > Also, the default configuration is meant to be overwritten to suit your > workflow. @@ -35,3 +35,8 @@ Run ``` xplr ``` + + +[1]:install.md +[2]:https://github.com/sayanarijit/xplr/blob/main/src/init.lua +[3]:upgrade-guide.md \ No newline at end of file diff --git a/docs/en/src/quickstart.md b/docs/en/src/quickstart.md index 7578100..3cab8dc 100644 --- a/docs/en/src/quickstart.md +++ b/docs/en/src/quickstart.md @@ -4,5 +4,9 @@ Quickstart Nice to you have here! Let's quickly start our xplr journey with the following steps: -- [Install](install.md) -- [Post Install](post-install.md) +- [Install][1] +- [Post Install][2] + + +[1]:install.md +[2]:post-install.md \ No newline at end of file diff --git a/docs/en/src/sorting.md b/docs/en/src/sorting.md index 6f64908..21b2b23 100644 --- a/docs/en/src/sorting.md +++ b/docs/en/src/sorting.md @@ -17,7 +17,7 @@ the node is a symlink. The arrows denote the order. -Each part of this pipeline is called [Node Sorter Applicable](#node-sorter-applicable). +Each part of this pipeline is called [Node Sorter Applicable][1]. Node Sorter Applicable @@ -25,8 +25,8 @@ Node Sorter Applicable It contains the following information: -- [sorter](#sorter) -- [reverse](#reverse) +- [sorter][2] +- [reverse][3] ### sorter @@ -81,3 +81,8 @@ xplr.config.general.initial_sorting = { ``` This snippet defines the initial sorting logic to be applied when xplr loads. + + +[1]:#node-sorter-applicable +[2]:#sorter +[3]:#reverse \ No newline at end of file diff --git a/docs/en/src/style.md b/docs/en/src/style.md index cf34faf..7910aa3 100644 --- a/docs/en/src/style.md +++ b/docs/en/src/style.md @@ -3,35 +3,35 @@ Style A style object contains the following information: -- [fg](#fg) -- [bg](#bg) -- [add_modifiers](#add_modifiers) -- [sub_modifiers](#sub_modifiers) +- [fg][1] +- [bg][2] +- [add_modifiers][3] +- [sub_modifiers][4] ### fg -Type: nullable [Color](#color) +Type: nullable [Color][5] The foreground color. ### bg -Type: nullable [Color](#color) +Type: nullable [Color][5] The background color. ### add_modifiers -Type: nullable list of [Modifier](#modifier) +Type: nullable list of [Modifier][6] Modifiers to add. ### sub_modifiers -Type: nullable list of [Modifier](#modifier) +Type: nullable list of [Modifier][6] Modifiers to remove. @@ -87,3 +87,11 @@ xplr.config.general.cursor.style.bg = { Rgb = { 100, 150, 200 } } xplr.config.general.cursor.style.add_modifiers = { "Bold", "Italic" } xplr.config.general.cursor.style.sub_modifiers = { "Hidden" } ``` + + +[1]:#fg +[2]:#bg +[3]:#add_modifiers +[4]:#sub_modifiers +[5]:#color +[6]:#modifier \ No newline at end of file diff --git a/docs/en/src/todo.md b/docs/en/src/todo.md index 530a65b..0969329 100644 --- a/docs/en/src/todo.md +++ b/docs/en/src/todo.md @@ -8,8 +8,8 @@ TODO - [x] logging support. - [x] Version compatibility instructions. - [x] Implement CLI arguments. -- ~Add support for tabs and/or panes (non native)~ [hacked](https://github.com/sayanarijit/xplr/wiki/Hacks#spawn-multiple-sessions-in-different-windows) | [discussion](https://github.com/sayanarijit/xplr/discussions/15) -- ~Implement bookmarks.~ [hacked](https://github.com/sayanarijit/xplr/wiki/Hacks#bookmark) +- ~Add support for tabs and/or panes (non native)~ [hacked][1] | [discussion][2] +- ~Implement bookmarks.~ [hacked][3] - [x] Add sorting support. - [x] Add filter support. - [x] File previews. @@ -20,9 +20,17 @@ TODO - [x] ~Customize~ switch UI in run-time. - [ ] More tests and benchmarks. - [ ] Measure code coverage. -- [ ] Improve the [vim plugin](https://github.com/sayanarijit/xplr.vim). +- [ ] Improve the [vim plugin][4]. - [ ] Cleanup, refactor, optimize. -[add more](https://github.com/sayanarijit/xplr/discussions/2) +[add more][5] -Like this project so far? **[Please consider contributing](contribute.md).** +Like this project so far? **[Please consider contributing][6].** + + +[1]:https://github.com/sayanarijit/xplr/wiki/Hacks#spawn-multiple-sessions-in-different-windows +[2]:https://github.com/sayanarijit/xplr/discussions/15 +[3]:https://github.com/sayanarijit/xplr/wiki/Hacks#bookmark +[4]:https://github.com/sayanarijit/xplr.vim +[5]:https://github.com/sayanarijit/xplr/discussions/2 +[6]:contribute.md \ No newline at end of file diff --git a/docs/en/src/upgrade-guide.md b/docs/en/src/upgrade-guide.md index cf2b067..29c473c 100644 --- a/docs/en/src/upgrade-guide.md +++ b/docs/en/src/upgrade-guide.md @@ -7,7 +7,7 @@ When you upgrade xplr, you might see an error like this Incompatible script version in: /home/sayanarijit/.config/xplr/init.lua. The script version is: 0.9.0, the required version is: 0.10.1. Visit https://github.com/sayanarijit/xplr/wiki/Upgrade-Guide ``` -All you need to do is follow the [instructions](#instructions) starting from +All you need to do is follow the [instructions][1] starting from your config version, all the way to the required version.
@@ -46,13 +46,13 @@ compatibility. ### Instructions -#### [v0.13.7](https://github.com/sayanarijit/xplr/releases/tag/v0.13.7) -> [v0.14.3](https://github.com/sayanarijit/xplr/releases/tag/v0.14.3) +#### [v0.13.7][2] -> [v0.14.3][3] - macOS users need to place their config file (`init.lua`) in `$HOME/.config/xplr/` or `/etc/xplr/`. - Library users please refer to the latest API docs. - Check out the new messages: `{Start|Stop|Toggle}Fifo`. These enable support - for [FIFO based file previews](https://github.com/sayanarijit/xplr/pull/229#issue-662426960). + for [FIFO based file previews][4]. - You can disable the recover mode using `config.general.disable_recover_mode = true`. - Try running `xplr --help`. Yes, CLI has been implemented. - Since version `v0.14.3`, `StartFifo` and `ToggleFifo` will write to the FIFO @@ -60,19 +60,19 @@ compatibility. - Since version `v0.14.3`, general config `xplr.config.start_fifo` is available which can be set to a file path to start a fifo when xplr starts. -Like this project so far? **[Please consider contributing](contribute.md)**. +Like this project so far? **[Please consider contributing][5]**. -#### [v0.12.1](https://github.com/sayanarijit/xplr/releases/tag/v0.12.1) -> [v0.13.7](https://github.com/sayanarijit/xplr/releases/tag/v0.13.7) -- Lua functions called using [`CallLua`](https://docs.rs/xplr/latest/xplr/app/enum.ExternalMsg.html#variant.CallLua) and [`CallLuaSilently`](https://docs.rs/xplr/latest/xplr/app/enum.ExternalMsg.html#variant.CallLuaSilently) messages will receive [`CallLuaArg`](https://docs.rs/xplr/latest/xplr/app/struct.CallLuaArg.html) object as the function argument (instead of the [`App`](https://docs.rs/xplr/latest/xplr/app/struct.App.html) object). +#### [v0.12.1][6] -> [v0.13.7][2] +- Lua functions called using [`CallLua`][7] and [`CallLuaSilently`][8] messages will receive [`CallLuaArg`][9] object as the function argument (instead of the [`App`][10] object). - Each `node_types` config will inherit defaults from matching less specifig `node_types` config and overwrite them. - Since version `v0.13.2`, you don't need to use/send `Refresh` anymore. It will be auto-handled by xplr. -#### [v0.11.1](https://github.com/sayanarijit/xplr/releases/tag/v0.11.1) -> [v0.12.1](https://github.com/sayanarijit/xplr/releases/tag/v0.12.1) +#### [v0.11.1][11] -> [v0.12.1][6] - `xplr.config.node_types.mime_essence` has split into type and subtype. Hence, instead of `xplr.config.node_types.mime_essence["text/plain"] = ..` use `xplr.config.node_types.mime_essence["text"] = { plain = .. }`. - You can also define `xplr.config.node_types.mime_essence["text"]["*"]` that will match all text types (`text/*`). -#### [v0.10.2](https://github.com/sayanarijit/xplr/releases/tag/v0.10.2) -> [v0.11.1](https://github.com/sayanarijit/xplr/releases/tag/v0.11.1) +#### [v0.10.2][12] -> [v0.11.1][11] - `remaps:` has been removed to avoid confusion. Use lua assignments instead. For e.g. @@ -80,19 +80,19 @@ compatibility. xplr.config.modes.builtin.default.key_bindings.on_key["v"] = xplr.config.modes.builtin.default.key_bindings.on_key.space ``` -#### [v0.9.1](https://github.com/sayanarijit/xplr/releases/tag/v0.9.1) -> [v0.10.2](https://github.com/sayanarijit/xplr/releases/tag/v0.10.2) +#### [v0.9.1][13] -> [v0.10.2][12] -- [`config.yml`](https://github.com/sayanarijit/xplr/blob/85696ded7a/src/config.yml) has been fully replaced with [`init.lua`](https://github.com/sayanarijit/xplr/blob/main/src/init.lua). If you have a lot of customization in your `config.yml`, [xplr-yml2lua](https://github.com/sayanarijit/xplr-yml2lua) can help you with migrating it to `init.lua`. -- `Handlebars` templates has been replaced with [Lua functions](https://github.com/sayanarijit/xplr/blob/bfdb7736b99bc3c5ae53e7d621ba0e7ca2299b14/src/init.lua#L2005-L2064). You can either remove the customizations or overwrite the functions accordingly. -- Added new messages `CallLua` and `CallLuaSilently` to call lua functions. The app state will be passed as input to the functions, and the returned messages will be handled by xplr. `CallLua` and `CallLuaSilently` are more flexible (and probably faster) alternatives to `Call`, `CallSilently`, `BashExec` and `BashExecSilently`. [e.g.](https://github.com/sayanarijit/xplr/pull/177#issue-650643573) +- [`config.yml`][14] has been fully replaced with [`init.lua`][15]. If you have a lot of customization in your `config.yml`, [xplr-yml2lua][16] can help you with migrating it to `init.lua`. +- `Handlebars` templates has been replaced with [Lua functions][17]. You can either remove the customizations or overwrite the functions accordingly. +- Added new messages `CallLua` and `CallLuaSilently` to call lua functions. The app state will be passed as input to the functions, and the returned messages will be handled by xplr. `CallLua` and `CallLuaSilently` are more flexible (and probably faster) alternatives to `Call`, `CallSilently`, `BashExec` and `BashExecSilently`. [e.g.][18] -#### [v0.9.0](https://github.com/sayanarijit/xplr/releases/tag/v0.9.0) -> [v0.9.1](https://github.com/sayanarijit/xplr/releases/tag/v0.9.1) +#### [v0.9.0][19] -> [v0.9.1][13] - You can now set `remaps: {key: null}` to un-map a key. - `gx` will open the item under focus. - New key map `:sx` will open the selected items. -#### [v0.8.0](https://github.com/sayanarijit/xplr/releases/tag/v0.8.0) -> [v0.9.0](https://github.com/sayanarijit/xplr/releases/tag/v0.9.0) +#### [v0.8.0][20] -> [v0.9.0][19] Your previous config should mostly work fine. However, in case you are using `SwitchMode` heavily in your custom config, follow along. @@ -102,7 +102,7 @@ Your previous config should mostly work fine. However, in case you are using `Sw - Introduced new message `LogWarning`, similar to other `Log*` messages. - Creating files and directories has been optimized for batch creation. -#### [v0.7.2](https://github.com/sayanarijit/xplr/releases/tag/v0.7.2) -> [v0.8.0](https://github.com/sayanarijit/xplr/releases/tag/v0.8.0) +#### [v0.7.2][21] -> [v0.8.0][20] If you have made changes to the config file, @@ -110,18 +110,18 @@ If you have made changes to the config file, - Pipe `$XPLR_PIPE_FOCUS_OUT` has been removed. Use `$XPLR_FOCUS_PATH` env var instead. - You might want to review your path escaping logics. For e.g. use `echo FocusPath: "'"$PWD"'" >> $PIPE` instead of `echo "FocusPath: $PWD" >> $PIPE`. -#### [v0.7.0](https://github.com/sayanarijit/xplr/releases/tag/v0.7.0) -> [v0.7.2](https://github.com/sayanarijit/xplr/releases/tag/v0.7.2) +#### [v0.7.0][22] -> [v0.7.2][21] - Just update the `version` in your config file. - For version >= `v0.7.1`, you might want to free up or remap the `tab` key in `search` mode to enable easy selection during search. -#### [v0.6.0](https://github.com/sayanarijit/xplr/releases/tag/v0.6.0) -> [v0.7.0](https://github.com/sayanarijit/xplr/releases/tag/v0.7.0) +#### [v0.6.0][23] -> [v0.7.0][22] If you haven't made any changes in the config file, you should be fine just updating the version number. Else, - You can make the `Table: ...`, `InputAndLogs: ...` layout values null and define the common properties in the `general.panel_ui` instead. -#### [v0.5.13](https://github.com/sayanarijit/xplr/releases/tag/v0.5.13) -> [v0.6.0](https://github.com/sayanarijit/xplr/releases/tag/v0.6.0) +#### [v0.5.13][24] -> [v0.6.0][23] If you haven't made any changes in the config file, you should be fine just updating the version number. Else, @@ -131,14 +131,14 @@ If you haven't made any changes in the config file, you should be fine just upda Optionally, checkout this new theme to learn more about what's new. -#### [v0.5.0](https://github.com/sayanarijit/xplr/releases/tag/v0.5.0) -> [v0.5.13](https://github.com/sayanarijit/xplr/releases/tag/v0.5.13) +#### [v0.5.0][25] -> [v0.5.13][24] - Just update the `version` in your config file. - For versions >= `v0.5.8`, you can set `$OPENER` env var to declare a global GUI file opener (to open files using keys `gx`). - You might also want to update other mappings to handle files with names starting with `-` (hiphen). For example, instead of `rm ${filename}` use `rm -- ${filename}`. Same goes for `cp`, `mv`, `cat`, `touch` etc. - For version >= `v0.5.13`, you might want to use the more specific `SwitchModeBuiltin` and `SwitchModeCustom` messages instead of the general `SwitchMode` message. -#### [v0.4.3](https://github.com/sayanarijit/xplr/releases/tag/v0.4.3) -> [v0.5.0](https://github.com/sayanarijit/xplr/releases/tag/v0.5.0) +#### [v0.4.3][26] -> [v0.5.0][25] If you haven't have any changes in the config file, you should be fine just updating the version number. @@ -152,32 +152,32 @@ Else do the following - You might want to use the new UI variables. - Update your config version to `v0.5.0`. -#### [v0.4.2](https://github.com/sayanarijit/xplr/releases/tag/v0.4.2) -> [v0.4.3](https://github.com/sayanarijit/xplr/releases/tag/v0.4.3) +#### [v0.4.2][27] -> [v0.4.3][26] -If you have customized `general.table.row.cols`, you might want to [update it](https://github.com/sayanarijit/xplr/blob/af1cda5762/src/config.yml#L46-L48) to use the new variables with better symlink support. +If you have customized `general.table.row.cols`, you might want to [update it][28] to use the new variables with better symlink support. -#### [v0.4.1](https://github.com/sayanarijit/xplr/releases/tag/v0.4.1) -> [v0.4.2](https://github.com/sayanarijit/xplr/releases/tag/v0.4.2) +#### [v0.4.1][29] -> [v0.4.2][27] In case you have mapped the keys `q`, `ctrl-i` and `ctrl-o`, you may want to revisit the default mode key bindings and remap accordingly to use the new functionalities. -#### [v0.3.13](https://github.com/sayanarijit/xplr/releases/tag/v0.3.13) -> [v0.4.1](https://github.com/sayanarijit/xplr/releases/tag/v0.4.1) +#### [v0.3.13][30] -> [v0.4.1][29] -A lot has changed (apologies). But I promise from now on, upgrading will be much less painful (thanks to [@maximbaz](https://github.com/maximbaz)'s valuable [inputs](https://github.com/sayanarijit/xplr/issues/45#issue-854447104) and [code reviews](https://github.com/sayanarijit/xplr/pull/47)). +A lot has changed (apologies). But I promise from now on, upgrading will be much less painful (thanks to [@maximbaz][31]'s valuable [inputs][32] and [code reviews][33]). So, to start with the upgrade, let's remove everything from your config file except the `version` field and your custom modifications. If `version` is the only thing remaining, update it to `v0.4.1` and you are done. Else, do the following -- Rename `general.focused_ui` to `general.focus_ui` ([see here](https://github.com/sayanarijit/xplr/blob/055c1083d6/src/config.yml#L124)). -- Rename `filetypes` to `node_types`. ([see here](https://github.com/sayanarijit/xplr/blob/055c1083d6/src/config.yml#L145)) -- Rename `custom` field to `meta`. ([see here](https://github.com/sayanarijit/xplr/blob/055c1083d6/src/config.yml#L154-L155)) -- Move `icon` to `meta.icon`. ([see here](https://github.com/sayanarijit/xplr/blob/055c1083d6/src/config.yml#L45)) -- Rename `normal_ui` to `default_ui`. ([see here](https://github.com/sayanarijit/xplr/blob/055c1083d6/src/config.yml#L114)) -- Split `modes` into `modes.builtin` and `modes.custom` ([see here](https://github.com/sayanarijit/xplr/blob/055c1083d6/src/config.yml#L180-L181)). Migrate your custom modes to `modes.custom`. And copy only the changes in the in-built modes in `modes.builtin`. +- Rename `general.focused_ui` to `general.focus_ui` ([see here][34]). +- Rename `filetypes` to `node_types`. ([see here][35]) +- Rename `custom` field to `meta`. ([see here][36]) +- Move `icon` to `meta.icon`. ([see here][37]) +- Rename `normal_ui` to `default_ui`. ([see here][38]) +- Split `modes` into `modes.builtin` and `modes.custom` ([see here][39]). Migrate your custom modes to `modes.custom`. And copy only the changes in the in-built modes in `modes.builtin`. - Finally, update the `version` to `v0.4.1`. -#### [v0.3.8](https://github.com/sayanarijit/xplr/releases/tag/v0.3.8) -> [v0.3.13](https://github.com/sayanarijit/xplr/releases/tag/v0.3.13) +#### [v0.3.8][40] -> [v0.3.13][30] Your current config should work fine. However, you might want to replace some `Call` and `BashExec` messages with `CallSilently` and `BashExecSilently` to remove the flickering of the screen. If you haven't made any changes to the configuration, you can delete and regenerate it. @@ -188,7 +188,7 @@ Else, do the following - Search for `Call` and `BashExec` in the new config. - Compare and probably replace the associated actions in your current config -#### [v0.3.0](https://github.com/sayanarijit/xplr/releases/tag/v0.3.0) -> [v0.3.8](https://github.com/sayanarijit/xplr/releases/tag/v0.3.8) +#### [v0.3.0][41] -> [v0.3.8][40] Your current config should work fine. However, you might want to replace some `ResetNodeFilters` messages with `RemoveNodeFilter` and `RemoveNodeFilterFromInput` to get a better search and filter experience. @@ -200,7 +200,7 @@ Else, do the following - Search for `RemoveNodeFilterFromInput` in the new config. - Compare and probably replace the associated actions in your current config. -#### v0.2.14 -> [v0.3.0](https://github.com/sayanarijit/xplr/releases/tag/v0.3.0) +#### v0.2.14 -> [v0.3.0][41] If you haven't made any changes to the configuration, you can delete and regenerate it. @@ -214,3 +214,46 @@ Else do the following: - `$XPLR_LOGS` has been ported to file `$XPLR_PIPE_LOGS_OUT`. Use `cat` instead of `echo`, `<` instead of `<<<` etc. - `$XPLR_PIPE_RESULT` has been ported to file `$XPLR_PIPE_RESULT_OUT`. Use `cat` instead of `echo`, `<` instead of `<<<` etc. - Finally, update the `version` in your config file. + + +[1]:#instructions +[2]:https://github.com/sayanarijit/xplr/releases/tag/v0.13.7 +[3]:https://github.com/sayanarijit/xplr/releases/tag/v0.14.3 +[4]:https://github.com/sayanarijit/xplr/pull/229#issue-662426960 +[5]:contribute.md +[6]:https://github.com/sayanarijit/xplr/releases/tag/v0.12.1 +[7]:https://docs.rs/xplr/latest/xplr/app/enum.ExternalMsg.html#variant.CallLua +[8]:https://docs.rs/xplr/latest/xplr/app/enum.ExternalMsg.html#variant.CallLuaSilently +[9]:https://docs.rs/xplr/latest/xplr/app/struct.CallLuaArg.html +[10]:https://docs.rs/xplr/latest/xplr/app/struct.App.html +[11]:https://github.com/sayanarijit/xplr/releases/tag/v0.11.1 +[12]:https://github.com/sayanarijit/xplr/releases/tag/v0.10.2 +[13]:https://github.com/sayanarijit/xplr/releases/tag/v0.9.1 +[14]:https://github.com/sayanarijit/xplr/blob/85696ded7a/src/config.yml +[15]:https://github.com/sayanarijit/xplr/blob/main/src/init.lua +[16]:https://github.com/sayanarijit/xplr-yml2lua +[17]:https://github.com/sayanarijit/xplr/blob/bfdb7736b99bc3c5ae53e7d621ba0e7ca2299b14/src/init.lua#L2005-L2064 +[18]:https://github.com/sayanarijit/xplr/pull/177#issue-650643573 +[19]:https://github.com/sayanarijit/xplr/releases/tag/v0.9.0 +[20]:https://github.com/sayanarijit/xplr/releases/tag/v0.8.0 +[21]:https://github.com/sayanarijit/xplr/releases/tag/v0.7.2 +[22]:https://github.com/sayanarijit/xplr/releases/tag/v0.7.0 +[23]:https://github.com/sayanarijit/xplr/releases/tag/v0.6.0 +[24]:https://github.com/sayanarijit/xplr/releases/tag/v0.5.13 +[25]:https://github.com/sayanarijit/xplr/releases/tag/v0.5.0 +[26]:https://github.com/sayanarijit/xplr/releases/tag/v0.4.3 +[27]:https://github.com/sayanarijit/xplr/releases/tag/v0.4.2 +[28]:https://github.com/sayanarijit/xplr/blob/af1cda5762/src/config.yml#L46-L48 +[29]:https://github.com/sayanarijit/xplr/releases/tag/v0.4.1 +[30]:https://github.com/sayanarijit/xplr/releases/tag/v0.3.13 +[31]:https://github.com/maximbaz +[32]:https://github.com/sayanarijit/xplr/issues/45#issue-854447104 +[33]:https://github.com/sayanarijit/xplr/pull/47 +[34]:https://github.com/sayanarijit/xplr/blob/055c1083d6/src/config.yml#L124 +[35]:https://github.com/sayanarijit/xplr/blob/055c1083d6/src/config.yml#L145 +[36]:https://github.com/sayanarijit/xplr/blob/055c1083d6/src/config.yml#L154-L155 +[37]:https://github.com/sayanarijit/xplr/blob/055c1083d6/src/config.yml#L45 +[38]:https://github.com/sayanarijit/xplr/blob/055c1083d6/src/config.yml#L114 +[39]:https://github.com/sayanarijit/xplr/blob/055c1083d6/src/config.yml#L180-L181 +[40]:https://github.com/sayanarijit/xplr/releases/tag/v0.3.8 +[41]:https://github.com/sayanarijit/xplr/releases/tag/v0.3.0 \ No newline at end of file diff --git a/docs/en/src/writing-plugins.md b/docs/en/src/writing-plugins.md index 66d4553..90df7f4 100644 --- a/docs/en/src/writing-plugins.md +++ b/docs/en/src/writing-plugins.md @@ -1,7 +1,7 @@ Writing Plugins =============== -Anyone who can write [Lua](https://www.lua.org) code, can write xplr plugins. +Anyone who can write [Lua][1] code, can write xplr plugins. Just follow the instructions and best practices: @@ -26,7 +26,7 @@ plugin-name ``` You can also use -[this template](https://github.com/sayanarijit/plugin-template1.xplr). +[this template][2]. ### README.md @@ -54,13 +54,20 @@ Publishing When publishing plugins on GitHub or other repositories, it's a best practice to append `.xplr` to the name to make them distinguishable. Similar to the -`*.nvim` naming convention for [Neovim](https://neovim.io) plugins. +`*.nvim` naming convention for [Neovim][3] plugins. Finally, after publishing, don't hesitate to -[let us know](https://github.com/sayanarijit/xplr/discussions/categories/show-and-tell). +[let us know][4]. Examples -------- -Visit [Awesome Plugins](awesome-plugins.md) for xplr plugin examples. +Visit [Awesome Plugins][5] for xplr plugin examples. + + +[1]:https://www.lua.org +[2]:https://github.com/sayanarijit/plugin-template1.xplr +[3]:https://neovim.io +[4]:https://github.com/sayanarijit/xplr/discussions/categories/show-and-tell +[5]:awesome-plugins.md \ No newline at end of file