This guide describes how to customize aretext for your workflows.
Aretext uses a rule-based system for configuration. This allows you to easily customize the editor for different programming languages and projects.
In addition, you can define custom menu commands that invoke arbitrary programs. This provides a simple yet powerful way to extend the editor. For example, you can create custom menu commands to:
... and much more!
Aretext stores its configuration in a single YAML file. By default, the config file is located at
~/.config/aretext/config.yaml, but you can change the location by setting the
XDG_CONFIG_HOME env var (following the XDG Base Directory Specification). If you open the config file, you should see something like:
- name: default pattern: "**" config: autoIndent: false hideDirectories: [".git"] syntaxLanguage: plaintext tabExpand: false tabSize: 4 showLineNumbers: false - name: json pattern: "**/*.json" config: autoIndent: true syntaxLanguage: json tabExpand: true tabSize: 2 showLineNumbers: true
Each item in the configuration file describes a rule. For example, in the snippet above, the first rule is named "default" and the second rule is named "json".
Each rule has a pattern. The "**" is a wildcard that matches any subdirectory, and "*" is a wildcard that matches zero or more characters in a file or directory name.
When aretext loads a file, it checks each rule in order. If the rule's pattern matches the file's absolute path, it applies the rule to update the configuration.
For example, if aretext loaded the file "foo/bar.json" using the above configuration, both rules would match the filename. The resulting configuration would be:
config: autoIndent: true # from the "json" rule hideDirectories: [".git"] # from the "default" rule syntaxLanguage: json # from the "json" rule tabExpand: true # from the "json" rule tabSize: 2 # from the "json" rule showLineNumbers: true # from the "json" rule
When merging configurations from different rules:
This is a powerful mechanism for customizing configuration based on filename extension and/or project location. For example, suppose that one project you work on uses four spaces to indent JSON files. You could add a new rule to your config that overwrites the tabSize for JSON files in that specific project:
# ... other rules above ... - name: myproject-json pattern: "**/myproject/**/*.json" config: tabSize: 4
For a complete list of available configuration options, see Configuration Reference.
If your YAML config file has errors, aretext will exit with an error message. You can force aretext to ignore the config file by passing the "-noconfig" flag:
aretext -noconfig ~/.config/aretext/config.yaml
This allows you to start the editor so you can fix the configuration.
Aretext allows you to define custom menu items to run shell commands. This provides a simple, yet powerful, way to extend aretext.
You can add new menu commands by editing the YAML config file at
- name: custom-menu-rule pattern: "**/myproject/**" config: menuCommands: - name: my custom menu command shellCmd: echo 'hello world!' | less mode: terminal # or "silent" or "insert" or "fileLocations"
After restarting the editor, the new command will be available in the command menu. Selecting the new command will launch a shell (configured by the
$SHELL environment variable) and execute the shell command (in this case, echoing "hello world").
The "mode" parameter controls how aretext handles the command's input and output. There are four modes:
|insert||none||insert into document||paste from system clipboard, insert snippet, comment/uncomment selection, ...|
|fileLocations||none||file location menu||grep for word under cursor, ...|
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.
$SELECTIONis the currently selected text (if any).
Add a menu command to build a project using
make. Piping to
less allows us to page through the output.
- name: custom-make-cmd pattern: "**/myproject/**" config: menuCommands: - name: build shellCmd: make | less # default mode is "terminal"
Most systems provide command-line utilities for interacting with the system clipboard.
|Linux using XWindows||
|Linux using Wayland||
|WSL on Windows||
We can add custom menu commands to copy the current selection to the system clipboard and paste from the system clipboard into the document. For example, on Wayland:
- name: custom-clipboard-commands pattern: "**" config: menuCommands: - name: copy to clipboard shellCmd: wl-copy "$SELECTION" mode: silent - name: paste from clipboard shellCmd: wl-paste mode: insert
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:
- name: custom-fmt-command pattern: "**/*.go" config: menuCommands: - name: go fmt current file shellCmd: go fmt -w $FILEPATH | less
If there are no unsaved changes, aretext will automatically reload the file after it has been formatted.
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:
- name: custom-snippet-command pattern: "**/*.go" config: - name: insert test snippet shellCmd: cat ~/snippets/go-test.go mode: insert
You can add a custom menu command to grep for the word under the cursor. The following example uses ripgrep to perform the search:
- name: custom-grep-command pattern: "**" config: - name: rg word shellCmd: rg $WORD --vimgrep # or `grep $WORD -n -R .` mode: fileLocations
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!
If you use tmux, you can add a custom menu command to open the current document in a new window.
- name: split window horizontal shellCmd: tmux split-window -h "aretext $FILEPATH" mode: silent - name: split window vertical shellCmd: tmux split-window -v "aretext $FILEPATH" mode: silent