Configurando o Yazi com Helix no Linux (Artix/Arch)
Este artigo documenta como configurar o gerenciador de arquivos Yazi para abrir arquivos e diretórios no editor Helix, incluindo os problemas encontrados durante o processo e como resolvê-los.
Ambiente:
- Distro: Artix Linux (baseado em Arch)
- Session: X11
- Terminal: Kitty
- Shell: Zsh
- Yazi: 26.1.22
- Helix: instalado como helix no PATH
Hardware
┌───────────────────┬────────────────────────────────────────┐ │ Componente │ Detalhes │ ├───────────────────┼────────────────────────────────────────┤ │ CPU │ Intel Xeon E5-2690 v3 @ 2.60GHz │ ├───────────────────┼────────────────────────────────────────┤ │ Cores/Threads │ 24 threads (12 cores × 2 threads) │ ├───────────────────┼────────────────────────────────────────┤ │ RAM │ 32 GB (11 GB em uso, 19 GB disponível) │ ├───────────────────┼────────────────────────────────────────┤ │ Swap │ 12 GB (zram) │ ├───────────────────┼────────────────────────────────────────┤ │ Armazenamento │ PNY 1TB SATA SSD │ ├───────────────────┼────────────────────────────────────────┤ │ GPU │ NVIDIA GeForce GT 730 │ └───────────────────┴────────────────────────────────────────┘
Parte 1 - Tutorial: Configuração do Yazi com Helix
1. Variável de ambiente
A forma mais simples de definir o editor padrão do Yazi é via variável de ambiente. Adicione ao seu ~/.zshrc (ou ~/.bashrc):
export EDITOR=helix export VISUAL=helix
O Yazi usa $EDITOR automaticamente para abrir arquivos de texto no Linux/macOS sem precisar de configuração adicional.
2. Arquivo de configuração principal
Crie ou edite ~/.config/yazi/yazi.toml:
[manager]
sort_by = "modified"
sort_reverse = true
sort_dir_first = true
[opener]
pdf = [
{ run = 'zathura "$@"', orphan = true, desc = "Zathura" }
]
video = [
{ run = 'mpv "$@"', orphan = true, desc = "MPV" }
]
edit = [
{ run = 'helix "$@"', block = true, desc = "Helix" }
]
[open]
rules = [
{ name = "*/", use = "edit" },
{ name = "*.pdf", use = "pdf" },
{ name = "*.mp4", use = "video" },
{ name = "*.mkv", use = "video" },
{ name = "*.php", use = "edit" },
{ name = "*.json", use = "edit" },
{ name = "*.js", use = "edit" },
{ name = "*.sh", use = "edit" },
{ mime = "text/*", use = "edit" },
{ mime = "application/javascript", use = "edit" },
{ mime = "application/json", use = "edit" }
]
[flavour]
use = "tokyonight"
[preview]
image_filter = "lanczos3"
image_quality = 90
max_width = 1500
max_height = 1500
Pontos importantes:
- block = true faz o Yazi pausar e aguardar o Helix fechar antes de voltar ao painel — essencial para editores TUI
- orphan = true é para apps que devem continuar rodando após o Yazi fechar (como mpv e zathura)
- name = "*/" com a barra identifica diretórios pelo nome
- mime = "inode/directory" identifica diretórios pelo tipo MIME — mas pode falhar (ver Parte 2)
3. Abrindo diretórios no Helix
O Helix aceita diretórios como argumento diretamente:
helix /caminho/para/projeto
Isso abre o explorador de arquivos interno do Helix já na pasta do projeto.
4. Flavor tokyonight
Para instalar o flavor tokyonight no Yazi:
ya pack -a dangooddd/yazi-flavors:tokyonight
Parte 2 - Troubleshooting: Problemas Conhecidos
Problema 1: Enter na pasta não abre o editor, não faz nada
Sintoma: Ao pressionar Enter em cima de uma pasta no Yazi, nada acontece.
Causa: O Yazi separa intencionalmente as ações enter (navegar dentro da pasta) e open (abrir com opener). O Enter por padrão navega, não abre.
Solução 1 - smart-enter plugin (recomendada):
ya pack -a yazi-rs/plugins:smart-enter
Adicione ao ~/.config/yazi/keymap.toml:
[[manager.prepend_keymap]] on = "<Enter>" run = "plugin smart-enter" desc = "Enter directory or open file"
O smart-enter verifica: se for arquivo, abre com o opener; se for pasta, entra nela.
Solução 2 - usar name = "*/" em vez de mime = "inode/directory":
Em algumas versões o mime type de diretório não é detectado corretamente. Use o padrão de nome:
[open]
rules = [
{ name = "*/", use = "edit" }, # identifica diretórios
...
]Solução 3 - cd + helix no opener:
Se o Helix não aceitar o diretório como argumento em alguma situação:
[opener]
open_project = [
{ run = 'cd "$0" && helix .', block = true, desc = "Helix" }
]
[open]
rules = [
{ name = "*/", use = "open_project" },
...
]Problema 2: mime = "inode/directory" não funciona
Sintoma: A regra com mime = "inode/directory" não casa com pastas.
Diagnóstico:
yazi --debug
Procure a linha:
Routine
`file -bL --mime-type`: text/plainSe retornar text/plain em vez de inode/directory, o comando file do sistema não está identificando diretórios corretamente para o Yazi.
Verificação manual:
file -bL --mime-type /seu/diretorio # Deve retornar: inode/directory
Solução: Use name = "*/" em vez de mime = "inode/directory" nas rules.
Problema 3: Tecla o (Open with) não abre menu
Sintoma: Pressionar o em cima de um item não exibe o menu "Open with".
Causa provável: Nenhum opener está casando com o item selecionado, então o Yazi não tem o que mostrar no menu.
Diagnóstico: Adicione um fallback nas rules:
{ mime = "*", use = "edit" }Se o menu aparecer após isso, significa que as rules anteriores não estavam casando com o item.
Problema 4: Arquivo abre mas diretório não
Sintoma: helix arquivo.php funciona, mas helix /caminho/pasta/ não faz nada via Yazi.
Verificação:
# Teste direto no terminal helix /caminho/para/projeto
Se funcionar no terminal mas não pelo Yazi, o problema é na integração — verifique as rules e o nome do binário:
which helix # Se retornar /usr/bin/hx em vez de helix, use hx no opener
Problema 5: Yazi debug útil
Sempre que algo não funcionar, rode:
yazi --debug
As seções mais úteis para troubleshooting de openers:
Text Opener
default: Some(OpenerRule { run: "helix \"$@\"", block: true, ... })
Variables
EDITOR: Some("helix")
VISUAL: Some("helix")
Routine
`file -bL --mime-type`: text/plain ← aqui fica o bug de mimeReferência Rápida
Situação Solução
| Enter não abre editor | Instalar smart-enter plugin
| mime = "inode/directory" não funciona | Usar name = "*/"
| Nenhum opener disponível | Adicionar { mime = "*", use = "edit" } como fallback
| Editor não abre diretório | Usar cd "$0" && helix . no opener
| Binário não encontrado | Verificar com which helix e ajustar o runConfiguração Final Funcional
[manager]
sort_by = "modified"
sort_reverse = true
sort_dir_first = true
[opener]
pdf = [
{ run = 'zathura "$@"', orphan = true, desc = "Zathura" }
]
video = [
{ run = 'mpv "$@"', orphan = true, desc = "MPV" }
]
edit = [
{ run = 'helix "$@"', block = true, desc = "Helix" }
]
[open]
rules = [
{ name = "*/", use = "edit" },
{ name = "*.pdf", use = "pdf" },
{ name = "*.mp4", use = "video" },
{ name = "*.mkv", use = "video" },
{ name = "*.php", use = "edit" },
{ name = "*.json", use = "edit" },
{ name = "*.js", use = "edit" },
{ name = "*.sh", use = "edit" },
{ mime = "text/*", use = "edit" },
{ mime = "application/javascript", use = "edit" },
{ mime = "application/json", use = "edit" }
]
[flavour]
use = "tokyonight"
[preview]
image_filter = "lanczos3"
image_quality = 90
max_width = 1500
max_height = 1500