# Micro help text
-Micro is a terminal-based text editor that aims to be easy to use and intuitive,
-while also taking advantage of the full capabilities of modern terminals.
+Micro is a terminal-based text editor that aims to be easy to use and
+intuitive, while also taking advantage of the full capabilities of modern
+terminals.
-### Usage
+To open the command bar, press Ctrl-e. This enables a `>` prompt for typing
+commands. From now on when the documentation says to run a command such as `>
+help`, this means press Ctrl-e and type `help` (and press enter to execute the
+command).
-Once you have built the editor, simply start it by running
-`micro path/to/file.txt` or simply `micro` to open an empty buffer.
+For a list of the default keybindings run `> help defaultkeys`.
+For more information on keybindings see `> help keybindings`.
-Micro also supports creating buffers from stdin:
+## Quick-start
-```
-$ ifconfig | micro
-```
+Press Ctrl-q to quit, and Ctrl-s to save. Press Ctrl-e to start typing commands
+and you can see which commands are available by pressing tab, or by viewing the
+help topic `> help commands`.
-You can move the cursor around with the arrow keys and mouse.
+Move the cursor around with the mouse or the arrow keys. Run
+`> help defaultkeys` to get a quick, easy overview of the default hotkeys and
+what they do. For more info on rebinding keys, see type `> help keybindings`.
-### Keybindings
+If the colorscheme doesn't look good, you can change it with
+`> set colorscheme ...`. You can press tab to see the available colorschemes,
+or see more information about colorschemes and syntax highlighting with `> help
+colors`.
-Here are the default keybindings in json form which is also how
-you can rebind them to your liking.
+Press Ctrl-w to move between splits, and type `> vsplit filename` or
+`> hsplit filename` to open a new split.
-```json
-{
- "Up": "CursorUp",
- "Down": "CursorDown",
- "Right": "CursorRight",
- "Left": "CursorLeft",
- "ShiftUp": "SelectUp",
- "ShiftDown": "SelectDown",
- "ShiftLeft": "SelectLeft",
- "ShiftRight": "SelectRight",
- "AltLeft": "WordLeft",
- "AltRight": "WordRight",
- "AltShiftRight": "SelectWordRight",
- "AltShiftLeft": "SelectWordLeft",
- "CtrlLeft": "StartOfLine",
- "CtrlRight": "EndOfLine",
- "CtrlShiftLeft": "SelectToStartOfLine",
- "CtrlShiftRight": "SelectToEndOfLine",
- "CtrlUp": "CursorStart",
- "CtrlDown": "CursorEnd",
- "CtrlShiftUp": "SelectToStart",
- "CtrlShiftDown": "SelectToEnd",
- "Enter": "InsertEnter",
- "Space": "InsertSpace",
- "Backspace": "Backspace",
- "Backspace2": "Backspace",
- "Alt-Backspace": "DeleteWordLeft",
- "Alt-Backspace2": "DeleteWordLeft",
- "Tab": "InsertTab",
- "CtrlO": "OpenFile",
- "CtrlS": "Save",
- "CtrlF": "Find",
- "CtrlN": "FindNext",
- "CtrlP": "FindPrevious",
- "CtrlZ": "Undo",
- "CtrlY": "Redo",
- "CtrlC": "Copy",
- "CtrlX": "Cut",
- "CtrlK": "CutLine",
- "CtrlD": "DuplicateLine",
- "CtrlV": "Paste",
- "CtrlA": "SelectAll",
- "CtrlT": "AddTab"
- "CtrlRightSq": "PreviousTab",
- "CtrlBackslash": "NextTab",
- "Home": "Start",
- "End": "End",
- "PageUp": "CursorPageUp",
- "PageDown": "CursorPageDown",
- "CtrlG": "ToggleHelp",
- "CtrlR": "ToggleRuler",
- "CtrlL": "JumpLine",
- "Delete": "Delete",
- "Esc": "ClearStatus",
- "CtrlB": "ShellMode",
- "CtrlQ": "Quit",
- "CtrlE": "CommandMode",
- "CtrlW": "NextSplit",
-
- // Emacs-style keybindings
- "Alt-f": "WordRight",
- "Alt-b": "WordLeft",
- "Alt-a": "StartOfLine",
- "Alt-e": "EndOfLine",
- "Alt-p": "CursorUp",
- "Alt-n": "CursorDown"
-}
-```
+## Accessing more help
-You can use the alt keys + arrows to move word by word.
-Ctrl left and right move the cursor to the start and end of the line, and
-ctrl up and down move the cursor the start and end of the buffer.
+Micro has a built-in help system which can be accessed with the `help` command.
-You can hold shift with all of these movement actions to select while moving.
+To use it, press Ctrl-e to access command mode and type in `help` followed by a
+topic. Typing `help` followed by nothing will open this page.
-The bindings may be rebound using the `~/.config/micro/bindings.json`
-file. Each key is bound to an action.
+Here are the possible help topics that you can read:
-For example, to bind `Ctrl-y` to undo and `Ctrl-z` to redo, you could put the
-following in the `bindings.json` file.
+* tutorial: A brief tutorial which gives an overview of all the other help
+ topics
+* keybindings: Gives a full list of the default keybindings as well as how to
+ rebind them
+* defaultkeys: Gives a more straight-forward list of the hotkey commands and
+ what they do.
+* commands: Gives a list of all the commands and what they do
+* options: Gives a list of all the options you can customize
+* plugins: Explains how micro's plugin system works and how to create your own
+ plugins
+* colors: Explains micro's colorscheme and syntax highlighting engine and how
+ to create your own colorschemes or add new languages to the engine
-```json
-{
- "CtrlY": "Undo",
- "CtrlZ": "Redo"
-}
-```
+For example, to open the help page on plugins you would run `> help plugins`.
-### Possible commands
-
-You can execute an editor command by pressing `Ctrl-e` followed by the command.
-Here are the possible commands that you can use.
-
-* `quit`: Quits micro.
-
-* `save`: Saves the current buffer.
-
-* `replace "search" "value" flags`: This will replace `search` with `value`.
- The `flags` are optional.
- At this point, there is only one flag: `c`, which enables `check` mode
- which asks if you'd like to perform the replacement each time
-
- Note that `search` must be a valid regex. If one of the arguments
- does not have any spaces in it, you may omit the quotes.
-
-* `set option value`: sets the option to value. Please see the next section for
- a list of options you can set.
-
-* `run sh-command`: runs the given shell command in the background. The
- command's output will be displayed in one line when it finishes running.
-
-* `bind key action`: creates a keybinding from key to action. See the sections on
- keybindings above for more info about what keys and actions are available.
-
-* `vsplit filename`: opens a vertical split with `filename`. If no filename is
- provided, a vertical split is opened with an empty buffer
-
-* `hsplit filename`: same as `vsplit` but opens a horizontal split instead of
- a vertical split
-
-### Options
-
-Micro stores all of the user configuration in its configuration directory.
-
-Micro uses the `$XDG_CONFIG_HOME/micro` as the configuration directory. As per
-the XDG spec, if `$XDG_CONFIG_HOME` is not set, `~/.config/micro` is used as
-the config directory.
-
-Here are the options that you can set:
-
-* `colorscheme`: loads the colorscheme stored in
- $(configDir)/colorschemes/`option`.micro
-
- default value: `default`
- Note that the default colorschemes (default, solarized, and solarized-tc)
- are not located in configDir, because they are embedded in the micro binary
-
- The colorscheme can be selected from all the files in the
- ~/.config/micro/colorschemes/ directory. Micro comes by default with three
- colorschemes:
-
- * default: this is the default colorscheme.
-
- * solarized: this is the solarized colorscheme (used in the screenshot).
- You should have the solarized color palette in your terminal to use it.
-
- * solarized-tc: this is the solarized colorscheme for true color, just
- make sure your terminal supports true color before using it and that the
- MICRO_TRUECOLOR environment variable is set to 1 before starting micro.
-
- * monokai-tc: this is the monokai colorscheme. It requires true color to
- look perfect, but the 256 color approximation looks good as well.
-
- * atom-dark-tc: this colorscheme is based off of Atom's "dark" colorscheme.
- It requires true color to look good.
-
-
-* `tabsize`: sets the tab size to `option`
-
- default value: `4`
-
-* `indentchar`: sets the indentation character
-
- default value: ` `
-
-* `ignorecase`: perform case-insensitive searches
-
- default value: `off`
-
-* `syntax`: turns syntax on or off
-
- default value: `on`
-
-* `tabstospaces`: use spaces instead of tabs
-
- default value: `off`
-
-* `autoindent`: when creating a new line use the same indentation as the
- previous line
-
- default value: `on`
-
-* `cursorline`: highlight the line that the cursor is on in a different color
- (the color is defined by the colorscheme you are using)
-
- default value: `off`
-
-* `ruler`: display line numbers
-
- default value: `on`
-
-* `statusline`: display the status line at the bottom of the screen
-
- default value: `on`
-
-* `savecursor`: remember where the cursor was last time the file was opened and
- put it there when you open the file again
-
- default value: `off`
-
-* `saveundo`: when this option is on, undo is saved even after you close a file
- so if you close and reopen a file, you can keep undoing
-
- default value: `off`
-
-* `scrollmargin`: amount of lines you would like to see above and below the cursor
-
- default value: `3`
-
-* `scrollspeed`: amount of lines to scroll for one scroll event
-
- default value: `2`
-
----
-
-Default plugin options:
-
-* `linter`: lint languages on save (supported languages are C, D, Go, Java,
- Javascript, Lua). Provided by the `linter` plugin.
-
- default value: `on`
-
-* `autoclose`: Automatically close `{}` `()` `[]` `""` `''`. Provided by the autoclose plugin
-
- default value: `on`
-
-* `goimports`: Run goimports on save. Provided by the `go` plugin.
-
- default value: `off`
-
-* `gofmt`: Run gofmt on save. Provided by the `go` plugin.
-
- default value: `on`
-
-Any option you set in the editor will be saved to the file
-~/.config/micro/settings.json so, in effect, your configuration file will be
-created for you. If you'd like to take your configuration with you to another
-machine, simply copy the settings.json to the other machine.
+I recommend looking at the `tutorial` help file because it is short for each
+section and gives concrete examples of how to use the various configuration
+options in micro. However, it does not give the in-depth documentation that the
+other topics provide.
projects / micro.git / blobdiff