README.md

mux - Yazi plugin multiplexer

This Yazi plugin enables multiple previewers per previewer entry. One can specify the previewers to cycle through and a keybinding that triggers the cycle. It uses the args to determine which previewers to call and calls the current previewers peek and seek methods accordingly.

Credits to @sxyazi for the idea (see issue comment).

NOTE: This only works with async plugins so far because this plugin itself is an async plugin. It's not possible to cross this boundary (yet). See this issue.

This means it's not possible to use the folder previewer with mux. Use piper with ls or eza for this instead.

Installation

ya pkg add peterfication/mux

Configuration

Example previewer configuration

prepend_previewers = [
  { url = "*.csv", run = "mux code file" },
  # ...
]

Example keybinding

[mgr]
prepend_keymap = [
  { on = "p", run = "mux next", desc = "Show next previewer" },
  # ...
]

Example setup (optional)

Option	Default	Description
notify_on_switch	false	Whether to show a notification when the previewer is switched.
remember_per_file_extension	false	If false, the current previewer is remembered per file (per session). If true, the current previewer is remembered per suffix, so e.g. each JSON file will be previewed with the last selected previewer for JSON files. NOTE: this is without mime types yet, so folders and files without an extension will be treated the same, which will lead to unexpected behavior.
aliases	{}	See "Use cases" for examples on how to use it.

NOTE: Setup is only required if you want to change from the defaults.

require("mux"):setup({
  notify_on_switch = true, -- Default: false
  remember_per_file_extension = true, -- Default: false
  aliases = {}, -- Default: {}
})

Use cases

eza list and tree preview

(Like with the eza-preview.yazi plugin)

NOTE: Requires the piper plugin.

Explanations:

• cd before eza makes sure that the root does not contain the full path
• Make sure to use an eza theme that aligns with your yazi flavor.

-- init.lua
require("mux"):setup({
	aliases = {
		eza_tree_1 = {
			previewer = "piper",
			args = {
				'cd "$1" && eza --oneline --tree --level 1 --color=always --icons=always --group-directories-first --no-quotes .',
			},
		},
		eza_tree_2 = {
			previewer = "piper",
			args = {
				'cd "$1" && eza --oneline --tree --level 2 --color=always --icons=always --group-directories-first --no-quotes .',
			},
		},
		eza_tree_3 = {
			previewer = "piper",
			args = {
				'cd "$1" && eza --oneline --tree --level 3 --color=always --icons=always --group-directories-first --no-quotes .',
			},
		},
		eza_tree_4 = {
			previewer = "piper",
			args = {
				'cd "$1" && eza --oneline --tree --level 4 --color=always --icons=always --group-directories-first --no-quotes .',
			},
		},
	},
})

# yazi.toml
[plugin]
prepend_previewers = [
  { url = "*/", run = "mux eza_tree_1 eza_tree_2 eza_tree_3 eza_tree_4" },
  # ...
]

# keymap.toml
[mgr]
prepend_keymap = [
  # Plugin: mux
  { on = "P", run = "plugin mux next", desc = "Cycle through mux previewers" },
  # ...
]

duckdb and code previewer

NOTE: Requires the duckdb plugin.

prepend_previewers = [
  { url = "*.csv", run = "mux duckdb code" },
  { url = "*.tsv", run = "mux duckdb code" },
  { url = "*.json", run = "mux duckdb code" },
  # ...
]

# keymap.toml
[mgr]
prepend_keymap = [
  # Plugin: mux
  { on = "P", run = "plugin mux next", desc = "Cycle through mux previewers" },
  # ...
]

Roadmap

• Support spotters
• Support fetchers?

Development

See previewer plugin docs.

Useful just commands are defined in the Justfile.

just ci

Container development

This repository includes a podman-oriented development image that installs a pinned Yazi release and mounts the local checkout as the live mux.yazi plugin source inside the container.

Build the image with the default Yazi version:

just container_build

Build the image with a specific Yazi version:

just container_build v26.1.4

Open an interactive shell in the container:

just container_shell v26.1.4

Or start Yazi directly:

just container_yazi v26.1.4

Inside the container, this repository is mounted at /workspace/mux.yazi and linked into Yazi as:

/root/.config/yazi/plugins/mux.yazi

The local docker/ directory is mounted into /opt/mux-dev, and the container entrypoint copies docker/init.lua, docker/yazi.toml, and docker/keymap.toml into Yazi's config directory on startup. Changes there are picked up on the next container start without rebuilding the image.

The container also installs a minimal Yazi config that:

• loads mux from init.lua
• binds P to plugin mux next
• configures mux code file for text and JSON previews

If you're using Podman on Linux with SELinux enabled, add :Z to the bind mount in the container_shell and container_yazi recipes in the Justfile.

License

This project is licensed under the MIT license (LICENSE or opensource.org/licenses/MIT)