• Contents

  • 1 Starting yed for the first time
    • Configuration
    • init.so
    • yedrc
    • Different Config Paths
  • 2 Running commands
  • 3 Keybindings
  • 4 Buffers
  • 5 Frames
  • 6 Variables
  • 7 Styles
  • 8 Plugins
    • YPM
  • 9 F.A.Q.


• This guide is meant to explain the normal operation and concepts of yed. It assumes that you've already built and installed yed. If you haven't yet, instructions are here. For information regarding plugin development, see the developer manual.
  For more help, users on our discord will be more than happy to answer questions.
  
  Other links: Command Reference, Variable Reference, Attribute String Reference, Status Line Reference

Starting yed for the first time

yed can be started by simply entering "yed" on the command line.

                    $ yed # run your editor
                

Configuration

All configuration of yed by default starts with items located in ~/.config/yed. If this is your first time running yed, you should see a popup that looks like this: Hitting 'y' will create this directory and fill it with a default configuration made up of a few items that are explained in the next sections. You may see an additional popup asking you to update YPM (see this section).

init.so

The root of any yed configuration is the file ~/.config/yed/init.so. This file is simply another yed plugin that sets options, adds commands, etc. It is different from other plugins only in that it is loaded automatically by yed at startup.

If you allowed yed to create your ~/.config/yed for you, you should see this file along with init.c, the source code for init.so.

Examining init.c, you should notice a few things:

• It uses YEXE() to run yed commands.
• It creates a command called recompile-init, which you can use to integrate changes you make to this file.
• It loads a couple of plugins (ypm and yedrc).
• It instructs yedrc to load the file ~/config/.yed/yedrc.

yedrc

yedrc is a plugin that allows you to source files that contain a sequence of yed commands and execute them. Most simple configuration tasks such as loading plugins, setting variables, activating a style, etc. can be accomplished with yed commands and putting these in a yedrc file makes that easier since you don't have to recompile anything.

However, configuration that requires any dynamic behavior such as setting variables to different values depending on the presence of a program on the system, or custom frame rules, are not possible just by calling commands. You always have the option to program complex configuration in your init.c (or any plugin, for that matter).

Different Config Paths

When the environment variable YED_CONFIG_DIR is set, yed will use that directory instead of ~/.config/yed. Otherwise, if XDG_CONFIG_HOME is set, yed will search there. ~/.config/yed is used in any other case.

Running commands

Most behavior in yed is command driven. This is true even at a basic level. For example, when you hit the right arrow key to move the cursor to the right, what is actually happening is that there is a key binding that maps the arrow key to the command cursor-right. That command uses the lower-level yed core code to get the cursor to the correct spot.

Commands can be invoked in the following ways:

• Programmatically using YEXE().
• Through a key binding.
• Simply typed in the command line.

By default, ctrl-y will bring you to the command line. (Notice, command-prompt is also just another command invoked by a key binding!)

Once there, you can run any available command, including those provided by plugins.

See the Command Reference.

Keybindings

As mentioned in the previous section, commands can be bound to keystrokes and some already have corresponding bindings. However, you may want to add useful bindings or change the key map completely!

To do this you can use the bind and unbind commands. For example, let's say you wanted to change the binding for command-prompt from the default ctrl-y to ctrl-x. To do that, you could issue the following commands:

                    YED> bind ctrl-x command-prompt
                

                    YED> unbind ctrl-y
                

If you want those bindings to persist, you must add those commands to your configuration.

NOTE: It's important to do the commands in that order so that you can still access the command prompt to create the new binding!

NOTE: Some plugins (vimish, for example) add complex behavior on top of key bindings and may require that you use alternative commands for binding keys. Read the plugin documentation.

Buffers

Buffers are units of text content that typically represent a file. To open a file in yed, you can either start yed and pass the path to the file as a command line argument:

                    $ yed my_file.txt
                

or, from within yed, use the buffer command:

                    YED> buffer my_file.txt
                

In either case the contents of my_file.txt should be displayed.

As you use yed to modify this text, you're manipulating the buffer, not the file. However, you can save the changes in the buffer back to the file on disk with the write-buffer command (default binding ctrl-w):

                    YED> write-buffer
                

Additionally there is the concept of a special buffer, which typically does NOT represent a file. By convention, special buffers start with the * character. Some examples of these are *bindings, *vars, *yank, and *log. Even though they are special, they are still just buffers, so to view one, you can use the buffer command.

                    YED> buffer *log
                

Running that will pull up the log that collects the activity of many systems, commands, and plugins running in yed. You may also notice that it is write-protected.

Many plugins add and implement functionality in special buffers.

Frames

Frames are areas of the screen that show some part of a buffer. They are analogous to a "window", "pane", or "view". They can be created and manipulated programmatically or with the commands frame-new, frame-resize, and frame-move.

If you start yed and open a new buffer, you should see its contents in a frame that takes up the whole screen. Opening more buffers does not create new frames, however. Instead it simply displays the new buffer in the same frame. The commands buffer-next and buffer-prev can be used to cycle through open buffers with the currently active frame. Additionally, running buffer with the name of an already open buffer will display that buffer in the active frame.

You can create as many frames as you would like and arrange them as you wish. Each frame can show different buffers or even the same buffer! Additionally frames can be split using the commands frame-vsplit and frame-hsplit.

Your cursor may only be in one frame at a time (the "active" frame). When you have more than one frame, you can cycle between them with the frame-next and frame-prev commands.

Finally, a frame can be deleted with frame-delete.
NOTE: Deleting a frame does not have any effect on the buffer it was displaying.

Variables

yed variables are simple key/value string pairs that are used to configure various aspects of the editor and plugins.

To set/unset variables, use the commands set and unset. The command get will print the value of the given variable.

See the Variable Reference.

Styles

To change yed's colors and attributes, you can activate a style.
Styles are generally created by plugins and activated by name using the style command.

                    YED> style monokai
                

NOTE: The only style available without plugins is called "default".

Most available styles are written to use the full 16 million colors available in "truecolor" terminals when the variable truecolor is true (false by default). However, most of the styles will try to approximate their colors into the 256 color palette if truecolor is disabled (to varying degrees of success).
Check this list to see if your terminal supports truecolor: https://gist.github.com/XVilka/8346728.

To enable truecolor styles, set truecolor to a truthy value before loading the style plugins:

                    set truecolor 'yes'
                    plugin-load 'ypm' # if style plugins loaded by YPM
                    plugin-load 'styles/gruvbox' # or manually
                    style 'gruvbox'
                

Plugins

Almost all advanced functionality is implemented by plugins. Plugins can be loaded and unloaded with the commands plugin-load and plugin-unload. When you try to load a plugin, yed will search the plugin in the paths listed by the command plugins-list-dirs (descending priority).

To find out where a plugin is being loaded from, use the command plugin-path.

YPM

yed ships with a plugin manager called YPM that can optionally be used to find, download, and use plugins from a large collection of user-written plugins. If the ypm plugin has been loaded, you may use the command ypm-menu to see a list of all available. From there you can discover the plugins that you'd like and install them. Plugins installed with ypm will automatically be loaded the next time you run yed, so there is no need to add plugin-load commands to your configuration.

F.A.Q.

How do I quit yed?

Open the command line (the default key binding for this is ctrl-y), type "quit", and hit ENTER.

How do I get syntax highlighting?

A plugin such as lang/c and lang/syntax/c.

Can I change yed's colors?

Yes. Use the command style to activate a style made available by plugins. See Styles.

How do I get line numbers?

A plugin such as line_numbers.

How do move my configuration to a new machine?

Copy your yedrc files and your ypm_list as appropriate to your new ~/config/.yed and recompile your init.so and any other plugins you may have written. If you are using ypm, running ypm-update will install all of the plugins from your ypm_list.