Skip to content

editor_configuration.md

Latest commit

 

History

History
326 lines (246 loc) · 9.53 KB

editor_configuration.md

File metadata and controls

326 lines (246 loc) · 9.53 KB

Editor Configuration

Yazelix provides smart editor configuration to avoid conflicts with existing installations while maintaining full integration features.

Quick Start

Most users should use the default:

[editor]
command = ""  # Uses Yazelix's Helix - no conflicts, full features

If you have specific needs:

How It Works

Yazelix sets your configured editor as the EDITOR environment variable throughout the system. The editor choice affects:

  • File opening behavior from Yazi file manager
  • Integration features (reveal in sidebar, open in same instance, etc.)
  • Zellij pane management and tab naming
  • Shell commands that respect $EDITOR

Configuration Options

Default (Recommended): Yazelix's Helix

# In yazelix.toml:
[editor]
command = ""             # Use Yazelix's Helix (recommended)
sidebar_width_percent = 20

[helix]
# runtime_path = "/path/to/runtime"  # Optional override when using custom builds

Benefits:

  • ✅ No conflicts with existing Helix installations
  • ✅ Always works - binary and runtime are perfectly matched
  • ✅ Full integration - All yazelix features work (reveal in sidebar, open in same instance, etc.)
  • ✅ Zero configuration - Works out of the box

How it works:

  • Yazelix uses its own Nix-provided Helix binary (/nix/store/.../bin/hx)
  • Runtime is automatically set to the matching version (/nix/store/.../share/helix/runtime)
  • No interference with your system's Helix installation

Using Your Existing Helix

# In yazelix.toml:
[editor]
command = "hx"  # Use system Helix from PATH

[helix]
# runtime_path = "/home/user/helix/runtime"  # Only for custom/nonstandard Helix runtimes

Benefits:

  • ✅ Full integration - All yazelix features work if runtime matches
  • ✅ Use your custom build - Great for Helix developers

Notes:

  • Standard packaged Helix installs usually do not need [helix].runtime_path
  • Set [helix].runtime_path only when your Helix runtime lives outside Helix's normal discovery paths
  • If you set it, it MUST match your Helix binary version
  • ⚠️ Requires matching runtime - Version mismatch causes startup errors
  • ⚠️ Manual configuration - You must specify the correct runtime path

Finding your runtime path:

# Automatic detection:
ls $(dirname $(which hx))/../share/helix/runtime

# Manual check for system-installed Helix:
which hx  # e.g., /usr/bin/hx → runtime at /usr/share/helix/runtime

# For custom builds:
ls ~/helix/runtime  # Should contain themes/, grammars/, queries/ directories

# Verify Helix can resolve a valid runtime:
hx --health | head -n 5

Using Neovim

# In yazelix.toml:
[editor]
command = "nvim"         # Use Neovim

Benefits:

  • ✅ Full integration - All yazelix features work (reveal in sidebar, open in same instance, etc.)
  • ✅ Smart instance management - Files open in existing Neovim instance when possible
  • ✅ Managed pane targeting - Yazelix finds and reuses your managed Neovim pane deterministically

Setup Required:

Popular Neovim commands:

  • "nvim" - Neovim from PATH
  • "/usr/bin/nvim" - System Neovim with full path
  • "/nix/store/.../bin/nvim" - Nix-provided Neovim

Using Other Editors

# In yazelix.toml:
[editor]
command = "vim"          # "nano", "emacs", etc.

Benefits:

  • ✅ Works reliably - Basic Zellij integration (new panes, tab naming)
  • ✅ Use any editor - Full flexibility

Limitations:

  • ❌ Limited features - No advanced integration (reveal in sidebar, same-instance opening)
  • ❌ No editor-specific shortcuts - reveal in Yazi won't work without custom integration

Popular editor commands:

  • "vim" - Vi/Vim
  • "nano" - GNU Nano
  • "emacs" - GNU Emacs
  • "kak" - Kakoune
  • "/path/to/custom/editor" - Custom editor with full path

Integration Features

Helix-Specific Features (when using Helix)

Reveal in Yazi (managed binding):

  • Jump from Helix buffer to the same file in Yazi sidebar
  • Works against the managed sidebar in the current Yazelix tab
  • Default binding: Alt+r
  • Managed through Yazelix's Helix config surface instead of ~/.config/helix/config.toml
  • If you want to adopt an existing personal Helix config, run yzx import helix
  • Details: Helix Keybindings

File Picker:

  • Native Helix file picker integration
  • Choose a Helix-local binding that does not conflict with your Yazelix workspace shortcuts

Smart Instance Management:

  • Opening files from Yazi reuses existing Helix instance when possible
  • New panes created intelligently based on layout

Buffer Navigation:

  • Yazelix tracks Helix buffers for navigation features

Neovim-Specific Features (when using Neovim)

Reveal in Yazi (custom binding):

  • Jump from Neovim buffer to the same file in Yazi sidebar
  • Works against the managed sidebar in the current Yazelix tab
  • Recommended binding: Alt+r
  • Recommended command: yzx reveal
  • Setup: Neovim Keybindings

Smart Instance Management:

  • Opening files from Yazi reuses the managed Neovim pane when possible
  • New panes created intelligently based on layout

Managed Pane Targeting:

  • Yazelix targets the managed editor pane through the pane orchestrator plugin
  • New editor panes are titled editor so later opens can reuse them deterministically
  • Editors started manually from an ordinary shell pane are not automatically adopted as the managed editor pane

Command Integration:

  • Files opened via :edit command in existing instances
  • Working directory changed via :cd command automatically

Generic Editor Features (all editors)

Basic File Opening:

  • Files open in new Zellij panes
  • Tab naming based on file directory
  • Working directory set correctly

Zellij Integration:

  • Proper pane management and focus
  • Terminal multiplexer benefits
  • Generic editors opened manually from shell panes remain ordinary panes; Yazelix-managed routing only applies to the managed editor pane

Troubleshooting

📋 Complete Troubleshooting Guide → - Quick fixes for common issues

Quick reset: Delete yazelix.toml and run yzx launch to regenerate defaults.

Advanced Scenarios

Multiple Helix Versions

If you have multiple Helix installations:

# Use specific version
[editor]
command = "/opt/helix-custom/bin/hx"

[helix]
runtime_path = "/opt/helix-custom/share/helix/runtime"

Development Setup

For Helix development:

# Use your development build
[editor]
command = "/home/user/helix/target/release/hx"

[helix]
runtime_path = "/home/user/helix/runtime"

Fallback Configuration

For maximum reliability:

# Always use yazelix's Helix
[editor]
command = ""

Home Manager Integration

When using Home Manager, the same options apply:

programs.yazelix = {
  enable = true;
  
  # Editor configuration
  editor_command = null;        # Default: yazelix's Helix
  helix_runtime_path = null;    # Default: matching runtime
  
  # Or custom:
  # editor_command = "hx";
  # helix_runtime_path = "/home/user/helix/runtime";
};

See home_manager/examples/example.nix for complete configuration examples.

Common Configuration Examples

Most Users (Recommended)

# yazelix.toml
[editor]
command = ""             # Use Yazelix's Helix

[helix]
# runtime_path = null  # Use matching runtime
# ... other settings

Helix Developer

# yazelix.toml
[editor]
command = "/home/user/helix/target/release/hx"

[helix]
runtime_path = "/home/user/helix/runtime"
# ... other settings

Neovim User

# yazelix.toml
[editor]
command = "nvim"         # Use Neovim
# ... other settings

Remember: Add a custom reveal binding to your Neovim config - see Neovim Keybindings

Vim/Other Editor User

# yazelix.toml
[editor]
command = "vim"          # Or "nano", "emacs", etc.
# ... other settings

System Helix User (Advanced)

# yazelix.toml
[editor]
command = "hx"  # Use system Helix

[helix]
runtime_path = "/usr/share/helix/runtime"  # Match system runtime
# ... other settings

Integration Feature Matrix

Editor Type File Opening Reveal in Sidebar Same Instance File Picker Tab Naming
Yazelix Helix (null) ✅ ✅ ✅ ✅ ✅
System Helix ("hx") ✅ ✅ ✅ ✅ ✅
Custom Helix (path) ✅ ✅ ✅ ✅ ✅
Neovim ("nvim") ✅ ✅ (with setup) ✅ ✅ (Telescope) ✅
Vim ✅ ❌ ❌ ❌ ✅
Other Editors ✅ ❌ ❌ ❌ ✅

Legend:

  • File Opening: Click files in Yazi to open in editor
  • Reveal in Sidebar: your editor-local reveal binding jumps to the file in Yazi
  • Same Instance: Files open in existing editor instance when possible
  • File Picker: Native file picking integration (Helix: custom binding, Neovim: Telescope/fzf-lua)
  • Tab Naming: Zellij tabs named after project/directory

Notes:

  • Neovim requires keybinding setup for reveal in sidebar
  • File picker in Neovim works with your existing plugins (Telescope, fzf-lua, etc.)