Custom Menu Commands
Aretext allows you to define custom menu items to run shell commands. This provides a simple, yet powerful, way to extend the editor.
Adding Custom Menu Comands
You can add new menu commands by editing the config file to add this rule:
After restarting the editor, the new command will be available in the command menu. Selecting the new command will launch a shell to execute the given command (in this case, echoing "hello world").
The shell program can be configured by environment variables:
$ARETEXT_SHELL has highest priority, then
$SHELL. If neither environment variable is set, aretext uses
The "mode" parameter controls how aretext handles the command's input and output. The table below shows the available modes:
|insert||none||insert into document||paste from system clipboard, insert snippet, comment/uncomment selection, ...|
|insertChoice||none||insert choice menu||choose a word to insert from a dictionary like
|fileLocations||none||file location menu||grep for word under cursor, ...|
|workingDir||none||working directory menu||select the current working directory from a preset list|
In addition, the following environment variables are provided to the shell command:
$FILEPATHis the absolute path to the current file.
$WORDis the current word under the cursor.
$LINEis the line number of the cursor, starting from one.
$COLUMNis the column position of the cursor in bytes, starting from one.
$SELECTIONis the currently selected text (if any).
If there are multiple commands with the same name, only the last of these commands will appear in the menu.
Build a project with make
Add a menu command to build a project using
make. Piping to
less allows us to page through the output.
Copy and paste using the system clipboard
Most systems provide command-line utilities for interacting with the system clipboard. Custom menu commands can invoke these tools to copy the current selection and paste into the document.
On Linux (Wayland):
Format the current file
Many programming languages provide command line tools to automatically format code. You can add a custom menu command to run these tools on the current file.
For example, this command uses
go fmt to format a Go file:
Git blame the current file
When working in a git repository, you might want to know who last edited a line of code. You can find this using
git blame on the current file.
Insert a snippet
You can add a custom menu command to insert a snippet of code.
For example, suppose you have written a template for a Go test. You can then create a menu command to
cat the contents of the file into the document:
Grep for the word under the cursor
You can add a custom menu command to grep for the word under the cursor. The following example uses ripgrep to perform the search:
Once the search has completed, aretext loads the locations into a searchable menu. This allows you to easily navigate to a particular result.
The "fileLocations" mode works with any command that outputs file locations as lines with the format:
<file>:<line>:<col>:<snippet>. You can use grep, ripgrep, or a script you write yourself!
Open a document in a new tmux window
If you use tmux, you can add a custom menu command to open the current document in a new window.