From 97ce6b4b56ef4593bce3f256a0dcd8028b311a7b Mon Sep 17 00:00:00 2001 From: pascalkuthe Date: Mon, 6 May 2024 15:39:19 +0000 Subject: [PATCH] deploy: a959c0ef9be59e63617c8e95d1ac59889d45a8b5 --- master/404.html | 2 +- master/building-from-source.html | 364 ++++++++++++++++++ master/commands.html | 2 +- master/configuration.html | 300 +-------------- master/editor.html | 548 ++++++++++++++++++++++++++++ master/from-vim.html | 2 +- master/guides/adding_languages.html | 2 +- master/guides/indent.html | 2 +- master/guides/index.html | 2 +- master/guides/injection.html | 2 +- master/guides/textobject.html | 2 +- master/index.html | 2 +- master/install.html | 249 +------------ master/keymap.html | 8 +- master/lang-support.html | 2 +- master/languages.html | 2 +- master/package-managers.html | 338 +++++++++++++++++ master/print.html | 153 ++++---- master/registers.html | 280 ++++++++++++++ master/remapping.html | 2 +- master/searchindex.js | 2 +- master/searchindex.json | 2 +- master/surround.html | 252 +++++++++++++ master/syntax-aware-motions.html | 281 ++++++++++++++ master/textobjects.html | 276 ++++++++++++++ master/themes.html | 6 +- master/title-page.html | 2 +- master/usage.html | 176 +-------- 28 files changed, 2453 insertions(+), 808 deletions(-) create mode 100644 master/building-from-source.html create mode 100644 master/editor.html create mode 100644 master/package-managers.html create mode 100644 master/registers.html create mode 100644 master/surround.html create mode 100644 master/syntax-aware-motions.html create mode 100644 master/textobjects.html diff --git a/master/404.html b/master/404.html index 4693a5148..c80fa4b58 100644 --- a/master/404.html +++ b/master/404.html @@ -90,7 +90,7 @@ diff --git a/master/building-from-source.html b/master/building-from-source.html new file mode 100644 index 000000000..eee7e9142 --- /dev/null +++ b/master/building-from-source.html @@ -0,0 +1,364 @@ + + + + + + Building from source + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + + + +
+
+

Building from source

+ +

Requirements:

+

Clone the Helix GitHub repository into a directory of your choice. The +examples in this documentation assume installation into either ~/src/ on +Linux and macOS, or %userprofile%\src\ on Windows.

+ +

If you are using the musl-libc standard library instead of glibc the following environment variable must be set during the build to ensure tree-sitter grammars can be loaded correctly:

+
RUSTFLAGS="-C target-feature=-crt-static"
+
+
    +
  1. +

    Clone the repository:

    +
    git clone https://github.com/helix-editor/helix
+cd helix
+
    +
    2. +
  2. +

    Compile from source:

    +
    cargo install --path helix-term --locked
+
    +

    This command will create the hx executable and construct the tree-sitter +grammars in the local runtime folder.

    +
    3. +
+
+

💡 If you do not want to fetch or build grammars, set an environment variable HELIX_DISABLE_AUTO_GRAMMAR_BUILD

+
+
+

💡 Tree-sitter grammars can be fetched and compiled if not pre-packaged. Fetch +grammars with hx --grammar fetch and compile them with +hx --grammar build. This will install them in +the runtime directory within the user's helix config directory (more +details below).

+
+

Configuring Helix's runtime files

+

Linux and macOS

+

The runtime directory is one below the Helix source, so either export a +HELIX_RUNTIME environment variable to point to that directory and add it to +your ~/.bashrc or equivalent:

+
export HELIX_RUNTIME=~/src/helix/runtime
+
+

Or, create a symbolic link:

+
ln -Ts $PWD/runtime ~/.config/helix/runtime
+
+

If the above command fails to create a symbolic link because the file exists either move ~/.config/helix/runtime to a new location or delete it, then run the symlink command above again.

+

Windows

+

Either set the HELIX_RUNTIME environment variable to point to the runtime files using the Windows setting (search for +Edit environment variables for your account) or use the setx command in +Cmd:

+
setx HELIX_RUNTIME "%userprofile%\source\repos\helix\runtime"
+
+
+

💡 %userprofile% resolves to your user directory like +C:\Users\Your-Name\ for example.

+
+

Or, create a symlink in %appdata%\helix\ that links to the source code directory:

+
+ + +
MethodCommand
PowerShellNew-Item -ItemType Junction -Target "runtime" -Path "$Env:AppData\helix\runtime"
Cmdcd %appdata%\helix
mklink /D runtime "%userprofile%\src\helix\runtime"
+
+
+

💡 On Windows, creating a symbolic link may require running PowerShell or +Cmd as an administrator.

+
+

Multiple runtime directories

+

When Helix finds multiple runtime directories it will search through them for files in the +following order:

+
    +
  1. runtime/ sibling directory to $CARGO_MANIFEST_DIR directory (this is intended for +developing and testing helix only).
    2. +
  2. runtime/ subdirectory of OS-dependent helix user config directory.
    3. +
  3. $HELIX_RUNTIME
    4. +
  4. Distribution-specific fallback directory (set at compile time—not run time— +with the HELIX_DEFAULT_RUNTIME environment variable)
    5. +
  5. runtime/ subdirectory of path to Helix executable.
    6. +
+

This order also sets the priority for selecting which file will be used if multiple runtime +directories have files with the same name.

+

Note to packagers

+

If you are making a package of Helix for end users, to provide a good out of +the box experience, you should set the HELIX_DEFAULT_RUNTIME environment +variable at build time (before invoking cargo build) to a directory which +will store the final runtime files after installation. For example, say you want +to package the runtime into /usr/lib/helix/runtime. The rough steps a build +script could follow are:

+
    +
  1. export HELIX_DEFAULT_RUNTIME=/usr/lib/helix/runtime
    2. +
  2. cargo build --profile opt --locked --path helix-term
    3. +
  3. cp -r runtime $BUILD_DIR/usr/lib/helix/
    4. +
  4. cp target/opt/hx $BUILD_DIR/usr/bin/hx
    5. +
+

This way the resulting hx binary will always look for its runtime directory in +/usr/lib/helix/runtime if the user has no custom runtime in ~/.config/helix +or HELIX_RUNTIME.

+

Validating the installation

+

To make sure everything is set up as expected you should run the Helix health +check:

+
hx --health
+
+

For more information on the health check results refer to +Health check.

+

Configure the desktop shortcut

+

If your desktop environment supports the +XDG desktop menu +you can configure Helix to show up in the application menu by copying the +provided .desktop and icon files to their correct folders:

+
cp contrib/Helix.desktop ~/.local/share/applications
+cp contrib/helix.png ~/.icons # or ~/.local/share/icons
+
+

To use another terminal than the system default, you can modify the .desktop +file. For example, to use kitty:

+
sed -i "s|Exec=hx %F|Exec=kitty hx %F|g" ~/.local/share/applications/Helix.desktop
+sed -i "s|Terminal=true|Terminal=false|g" ~/.local/share/applications/Helix.desktop
+
+ +
+ + +
+
+ + + +
+ + + + + + + + + + + + + + + + + + +
+ + diff --git a/master/commands.html b/master/commands.html index 9b7f0de9f..2c242a50b 100644 --- a/master/commands.html +++ b/master/commands.html @@ -89,7 +89,7 @@ diff --git a/master/configuration.html b/master/configuration.html index 09e874e52..e68dbe77f 100644 --- a/master/configuration.html +++ b/master/configuration.html @@ -89,7 +89,7 @@ @@ -209,300 +209,6 @@ Additionally, you can reload the configuration file by sending the USR1 signal to the Helix process on Unix operating systems, such as by using the command pkill -USR1 hx.

Finally, you can have a config.toml local to a project by putting it under a .helix directory in your repository. Its settings will be merged with the configuration directory config.toml and the built-in configuration.

-

Editor

-

[editor] Section

-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
KeyDescriptionDefault
scrolloffNumber of lines of padding around the edge of the screen when scrolling5
mouseEnable mouse modetrue
middle-click-pasteMiddle click paste supporttrue
scroll-linesNumber of lines to scroll per scroll wheel step3
shellShell to use when running external commandsUnix: ["sh", "-c"]
Windows: ["cmd", "/C"]
line-numberLine number display: absolute simply shows each line's number, while relative shows the distance from the current line. When unfocused or in insert mode, relative will still show absolute line numbersabsolute
cursorlineHighlight all lines with a cursorfalse
cursorcolumnHighlight all columns with a cursorfalse
guttersGutters to display: Available are diagnostics and diff and line-numbers and spacer, note that diagnostics also includes other features like breakpoints, 1-width padding will be inserted if gutters is non-empty["diagnostics", "spacer", "line-numbers", "spacer", "diff"]
auto-completionEnable automatic pop up of auto-completiontrue
auto-formatEnable automatic formatting on savetrue
auto-saveEnable automatic saving on the focus moving away from Helix. Requires focus event support from your terminalfalse
idle-timeoutTime in milliseconds since last keypress before idle timers trigger.250
completion-timeoutTime in milliseconds after typing a word character before completions are shown, set to 5 for instant.250
preview-completion-insertWhether to apply completion item instantly when selectedtrue
completion-trigger-lenThe min-length of word under cursor to trigger autocompletion2
completion-replaceSet to true to make completions always replace the entire word and not just the part before the cursorfalse
auto-infoWhether to display info boxestrue
true-colorSet to true to override automatic detection of terminal truecolor support in the event of a false negativefalse
undercurlSet to true to override automatic detection of terminal undercurl support in the event of a false negativefalse
rulersList of column positions at which to display the rulers. Can be overridden by language specific rulers in languages.toml file[]
bufferlineRenders a line at the top of the editor displaying open buffers. Can be always, never or multiple (only shown if more than one buffer is in use)never
color-modesWhether to color the mode indicator with different colors depending on the mode itselffalse
text-widthMaximum line length. Used for the :reflow command and soft-wrapping if soft-wrap.wrap-at-text-width is set80
workspace-lsp-rootsDirectories relative to the workspace root that are treated as LSP roots. Should only be set in .helix/config.toml[]
default-line-endingThe line ending to use for new documents. Can be native, lf, crlf, ff, cr or nel. native uses the platform's native line ending (crlf on Windows, otherwise lf).native
insert-final-newlineWhether to automatically insert a trailing line-ending on write if missingtrue
popup-borderDraw border around popup, menu, all, or nonenone
indent-heuristicHow the indentation for a newly inserted line is computed: simple just copies the indentation level from the previous line, tree-sitter computes the indentation based on the syntax tree and hybrid combines both approaches. If the chosen heuristic is not available, a different one will be used as a fallback (the fallback order being hybrid -> tree-sitter -> simple).hybrid
jump-label-alphabetThe characters that are used to generate two character jump labels. Characters at the start of the alphabet are used first."abcdefghijklmnopqrstuvwxyz"
-
-

[editor.statusline] Section

-

Allows configuring the statusline at the bottom of the editor.

-

The configuration distinguishes between three areas of the status line:

-

[ ... ... LEFT ... ... | ... ... ... CENTER ... ... ... | ... ... RIGHT ... ... ]

-

Statusline elements can be defined as follows:

-
[editor.statusline]
-left = ["mode", "spinner"]
-center = ["file-name"]
-right = ["diagnostics", "selections", "position", "file-encoding", "file-line-ending", "file-type"]
-separator = "│"
-mode.normal = "NORMAL"
-mode.insert = "INSERT"
-mode.select = "SELECT"
-
-

The [editor.statusline] key takes the following sub-keys:

-
- - - - - - - -
KeyDescriptionDefault
leftA list of elements aligned to the left of the statusline["mode", "spinner", "file-name", "read-only-indicator", "file-modification-indicator"]
centerA list of elements aligned to the middle of the statusline[]
rightA list of elements aligned to the right of the statusline["diagnostics", "selections", "register", "position", "file-encoding"]
separatorThe character used to separate elements in the statusline"│"
mode.normalThe text shown in the mode element for normal mode"NOR"
mode.insertThe text shown in the mode element for insert mode"INS"
mode.selectThe text shown in the mode element for select mode"SEL"
-
-

The following statusline elements can be configured:

-
- - - - - - - - - - - - - - - - - - - - - -
KeyDescription
modeThe current editor mode (mode.normal/mode.insert/mode.select)
spinnerA progress spinner indicating LSP activity
file-nameThe path/name of the opened file
file-absolute-pathThe absolute path/name of the opened file
file-base-nameThe basename of the opened file
file-modification-indicatorThe indicator to show whether the file is modified (a [+] appears when there are unsaved changes)
file-encodingThe encoding of the opened file if it differs from UTF-8
file-line-endingThe file line endings (CRLF or LF)
read-only-indicatorAn indicator that shows [readonly] when a file cannot be written
total-line-numbersThe total line numbers of the opened file
file-typeThe type of the opened file
diagnosticsThe number of warnings and/or errors
workspace-diagnosticsThe number of warnings and/or errors on workspace
selectionsThe number of active selections
primary-selection-lengthThe number of characters currently in primary selection
positionThe cursor position
position-percentageThe cursor position as a percentage of the total number of lines
separatorThe string defined in editor.statusline.separator (defaults to "│")
spacerInserts a space between elements (multiple/contiguous spacers may be specified)
version-controlThe current branch name or detached commit hash of the opened workspace
registerThe current selected register
-
-

[editor.lsp] Section

-
- - - - - - - -
KeyDescriptionDefault
enableEnables LSP integration. Setting to false will completely disable language servers regardless of language settings.true
display-messagesDisplay LSP progress messages below statusline1false
auto-signature-helpEnable automatic popup of signature help (parameter hints)true
display-inlay-hintsDisplay inlay hints2false
display-signature-help-docsDisplay docs under signature help popuptrue
snippetsEnables snippet completions. Requires a server restart (:lsp-restart) to take effect after :config-reload/:set.true
goto-reference-include-declarationInclude declaration in the goto references popup.true
-
-
1 -

By default, a progress spinner is shown in the statusline beside the file path.

-
-
2 -

You may also have to activate them in the LSP config for them to appear, not just in Helix. Inlay hints in Helix are still being improved on and may be a little bit laggy/janky under some circumstances. Please report any bugs you see so we can fix them!

-
-

[editor.cursor-shape] Section

-

Defines the shape of cursor in each mode. -Valid values for these options are block, bar, underline, or hidden.

-
-

💡 Due to limitations of the terminal environment, only the primary cursor can -change shape.

-
-
- - - -
KeyDescriptionDefault
normalCursor shape in normal modeblock
insertCursor shape in insert modeblock
selectCursor shape in select modeblock
-
-

[editor.file-picker] Section

-

Set options for file picker and global search. Ignoring a file means it is -not visible in the Helix file picker and global search.

-

All git related options are only enabled in a git repository.

-
- - - - - - - - - -
KeyDescriptionDefault
hiddenEnables ignoring hidden filestrue
follow-symlinksFollow symlinks instead of ignoring themtrue
deduplicate-linksIgnore symlinks that point at files already shown in the pickertrue
parentsEnables reading ignore files from parent directoriestrue
ignoreEnables reading .ignore filestrue
git-ignoreEnables reading .gitignore filestrue
git-globalEnables reading global .gitignore, whose path is specified in git's config: core.excludesfile optiontrue
git-excludeEnables reading .git/info/exclude filestrue
max-depthSet with an integer value for maximum depth to recurseUnset by default
-
-

Ignore files can be placed locally as .ignore or put in your home directory as ~/.ignore. They support the usual ignore and negative ignore (unignore) rules used in .gitignore files.

-

Additionally, you can use Helix-specific ignore files by creating a local .helix/ignore file in the current workspace or a global ignore file located in your Helix config directory:

- -

Example:

-
# unignore in file picker and global search
-!.github/
-!.gitignore
-!.gitattributes
-
-

[editor.auto-pairs] Section

-

Enables automatic insertion of pairs to parentheses, brackets, etc. Can be a -simple boolean value, or a specific mapping of pairs of single characters.

-

To disable auto-pairs altogether, set auto-pairs to false:

-
[editor]
-auto-pairs = false # defaults to `true`
-
-

The default pairs are (){}[]''""``, but these can be customized by -setting auto-pairs to a TOML table:

-
[editor.auto-pairs]
-'(' = ')'
-'{' = '}'
-'[' = ']'
-'"' = '"'
-'`' = '`'
-'<' = '>'
-
-

Additionally, this setting can be used in a language config. Unless -the editor setting is false, this will override the editor config in -documents with this language.

-

Example languages.toml that adds <> and removes ''

-
[[language]]
-name = "rust"
-
-[language.auto-pairs]
-'(' = ')'
-'{' = '}'
-'[' = ']'
-'"' = '"'
-'`' = '`'
-'<' = '>'
-
-

[editor.search] Section

-

Search specific options.

-
- - -
KeyDescriptionDefault
smart-caseEnable smart case regex searching (case-insensitive unless pattern contains upper case characters)true
wrap-aroundWhether the search should wrap after depleting the matchestrue
-
-

[editor.whitespace] Section

-

Options for rendering whitespace with visible characters. Use :set whitespace.render all to temporarily enable visible whitespace.

-
- - -
KeyDescriptionDefault
renderWhether to render whitespace. May either be all or none, or a table with sub-keys space, nbsp, nnbsp, tab, and newlinenone
charactersLiteral characters to use when rendering whitespace. Sub-keys may be any of tab, space, nbsp, nnbsp, newline or tabpadSee example below
-
-

Example

-
[editor.whitespace]
-render = "all"
-# or control each character
-[editor.whitespace.render]
-space = "all"
-tab = "all"
-nbsp = "none"
-nnbsp = "none"
-newline = "none"
-
-[editor.whitespace.characters]
-space = "·"
-nbsp = "⍽"
-nnbsp = "␣"
-tab = "→"
-newline = "⏎"
-tabpad = "·" # Tabs will look like "→···" (depending on tab width)
-
-

[editor.indent-guides] Section

-

Options for rendering vertical indent guides.

-
- - - -
KeyDescriptionDefault
renderWhether to render indent guidesfalse
characterLiteral character to use for rendering the indent guide│
skip-levelsNumber of indent levels to skip0
-
-

Example:

-
[editor.indent-guides]
-render = true
-character = "╎" # Some characters that work well: "▏", "┆", "┊", "⸽"
-skip-levels = 1
-
-

[editor.gutters] Section

-

For simplicity, editor.gutters accepts an array of gutter types, which will -use default settings for all gutter components.

-
[editor]
-gutters = ["diff", "diagnostics", "line-numbers", "spacer"]
-
-

To customize the behavior of gutters, the [editor.gutters] section must -be used. This section contains top level settings, as well as settings for -specific gutter components as subsections.

-
- -
KeyDescriptionDefault
layoutA vector of gutters to display["diagnostics", "spacer", "line-numbers", "spacer", "diff"]
-
-

Example:

-
[editor.gutters]
-layout = ["diff", "diagnostics", "line-numbers", "spacer"]
-
-

[editor.gutters.line-numbers] Section

-

Options for the line number gutter

-
- -
KeyDescriptionDefault
min-widthThe minimum number of characters to use3
-
-

Example:

-
[editor.gutters.line-numbers]
-min-width = 1
-
-

[editor.gutters.diagnostics] Section

-

Currently unused

-

[editor.gutters.diff] Section

-

The diff gutter option displays colored bars indicating whether a git diff represents that a line was added, removed or changed. -These colors are controlled by the theme attributes diff.plus, diff.minus and diff.delta.

-

Other diff providers will eventually be supported by a future plugin system.

-

There are currently no options for this section.

-

[editor.gutters.spacer] Section

-

Currently unused

-

[editor.soft-wrap] Section

-

Options for soft wrapping lines that exceed the view width:

-
- - - - - -
KeyDescriptionDefault
enableWhether soft wrapping is enabled.false
max-wrapMaximum free space left at the end of the line.20
max-indent-retainMaximum indentation to carry over when soft wrapping a line.40
wrap-indicatorText inserted before soft wrapped lines, highlighted with ui.virtual.wrap↪
wrap-at-text-widthSoft wrap at text-width instead of using the full viewport size.false
-
-

Example:

-
[editor.soft-wrap]
-enable = true
-max-wrap = 25 # increase value to reduce forced mid-word wrapping
-max-indent-retain = 0
-wrap-indicator = ""  # set wrap-indicator to "" to hide it
-
-

[editor.smart-tab] Section

-

Options for navigating and editing using tab key.

-
- - -
KeyDescriptionDefault
enableIf set to true, then when the cursor is in a position with non-whitespace to its left, instead of inserting a tab, it will run move_parent_node_end. If there is only whitespace to the left, then it inserts a tab as normal. With the default bindings, to explicitly insert a tab character, press Shift-tab.true
supersede-menuNormally, when a menu is on screen, such as when auto complete is triggered, the tab key is bound to cycling through the items. This means when menus are on screen, one cannot use the tab key to trigger the smart-tab command. If this option is set to true, the smart-tab command always takes precedence, which means one cannot use the tab key to cycle through menu items. One of the other bindings must be used instead, such as arrow keys or C-n/C-p.false
-
-

Due to lack of support for S-tab in some terminals, the default keybindings don't fully embrace smart-tab editing experience. If you enjoy smart-tab navigation and a terminal that supports the Enhanced Keyboard protocol, consider setting extra keybindings:

-
[keys.normal]
-tab = "move_parent_node_end"
-S-tab = "move_parent_node_start"
-
-[keys.insert]
-S-tab = "move_parent_node_start"
-
-[keys.select]
-tab = "extend_parent_node_end"
-S-tab = "extend_parent_node_start"
-
@@ -512,7 +218,7 @@ S-tab = "extend_parent_node_start" - @@ -526,7 +232,7 @@ S-tab = "extend_parent_node_start" - diff --git a/master/editor.html b/master/editor.html new file mode 100644 index 000000000..d4c8425fe --- /dev/null +++ b/master/editor.html @@ -0,0 +1,548 @@ + + + + + + Editor + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + + + + + + + + + + + + + + + + +
+ +
+ + + + + + + + +
+
+

Editor

+ +

[editor] Section

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
KeyDescriptionDefault
scrolloffNumber of lines of padding around the edge of the screen when scrolling5
mouseEnable mouse modetrue
middle-click-pasteMiddle click paste supporttrue
scroll-linesNumber of lines to scroll per scroll wheel step3
shellShell to use when running external commandsUnix: ["sh", "-c"]
Windows: ["cmd", "/C"]
line-numberLine number display: absolute simply shows each line's number, while relative shows the distance from the current line. When unfocused or in insert mode, relative will still show absolute line numbersabsolute
cursorlineHighlight all lines with a cursorfalse
cursorcolumnHighlight all columns with a cursorfalse
guttersGutters to display: Available are diagnostics and diff and line-numbers and spacer, note that diagnostics also includes other features like breakpoints, 1-width padding will be inserted if gutters is non-empty["diagnostics", "spacer", "line-numbers", "spacer", "diff"]
auto-completionEnable automatic pop up of auto-completiontrue
auto-formatEnable automatic formatting on savetrue
auto-saveEnable automatic saving on the focus moving away from Helix. Requires focus event support from your terminalfalse
idle-timeoutTime in milliseconds since last keypress before idle timers trigger.250
completion-timeoutTime in milliseconds after typing a word character before completions are shown, set to 5 for instant.250
preview-completion-insertWhether to apply completion item instantly when selectedtrue
completion-trigger-lenThe min-length of word under cursor to trigger autocompletion2
completion-replaceSet to true to make completions always replace the entire word and not just the part before the cursorfalse
auto-infoWhether to display info boxestrue
true-colorSet to true to override automatic detection of terminal truecolor support in the event of a false negativefalse
undercurlSet to true to override automatic detection of terminal undercurl support in the event of a false negativefalse
rulersList of column positions at which to display the rulers. Can be overridden by language specific rulers in languages.toml file[]
bufferlineRenders a line at the top of the editor displaying open buffers. Can be always, never or multiple (only shown if more than one buffer is in use)never
color-modesWhether to color the mode indicator with different colors depending on the mode itselffalse
text-widthMaximum line length. Used for the :reflow command and soft-wrapping if soft-wrap.wrap-at-text-width is set80
workspace-lsp-rootsDirectories relative to the workspace root that are treated as LSP roots. Should only be set in .helix/config.toml[]
default-line-endingThe line ending to use for new documents. Can be native, lf, crlf, ff, cr or nel. native uses the platform's native line ending (crlf on Windows, otherwise lf).native
insert-final-newlineWhether to automatically insert a trailing line-ending on write if missingtrue
popup-borderDraw border around popup, menu, all, or nonenone
indent-heuristicHow the indentation for a newly inserted line is computed: simple just copies the indentation level from the previous line, tree-sitter computes the indentation based on the syntax tree and hybrid combines both approaches. If the chosen heuristic is not available, a different one will be used as a fallback (the fallback order being hybrid -> tree-sitter -> simple).hybrid
jump-label-alphabetThe characters that are used to generate two character jump labels. Characters at the start of the alphabet are used first."abcdefghijklmnopqrstuvwxyz"
+
+

[editor.statusline] Section

+

Allows configuring the statusline at the bottom of the editor.

+

The configuration distinguishes between three areas of the status line:

+

[ ... ... LEFT ... ... | ... ... ... CENTER ... ... ... | ... ... RIGHT ... ... ]

+

Statusline elements can be defined as follows:

+
[editor.statusline]
+left = ["mode", "spinner"]
+center = ["file-name"]
+right = ["diagnostics", "selections", "position", "file-encoding", "file-line-ending", "file-type"]
+separator = "│"
+mode.normal = "NORMAL"
+mode.insert = "INSERT"
+mode.select = "SELECT"
+
+

The [editor.statusline] key takes the following sub-keys:

+
+ + + + + + + +
KeyDescriptionDefault
leftA list of elements aligned to the left of the statusline["mode", "spinner", "file-name", "read-only-indicator", "file-modification-indicator"]
centerA list of elements aligned to the middle of the statusline[]
rightA list of elements aligned to the right of the statusline["diagnostics", "selections", "register", "position", "file-encoding"]
separatorThe character used to separate elements in the statusline"│"
mode.normalThe text shown in the mode element for normal mode"NOR"
mode.insertThe text shown in the mode element for insert mode"INS"
mode.selectThe text shown in the mode element for select mode"SEL"
+
+

The following statusline elements can be configured:

+
+ + + + + + + + + + + + + + + + + + + + + +
KeyDescription
modeThe current editor mode (mode.normal/mode.insert/mode.select)
spinnerA progress spinner indicating LSP activity
file-nameThe path/name of the opened file
file-absolute-pathThe absolute path/name of the opened file
file-base-nameThe basename of the opened file
file-modification-indicatorThe indicator to show whether the file is modified (a [+] appears when there are unsaved changes)
file-encodingThe encoding of the opened file if it differs from UTF-8
file-line-endingThe file line endings (CRLF or LF)
read-only-indicatorAn indicator that shows [readonly] when a file cannot be written
total-line-numbersThe total line numbers of the opened file
file-typeThe type of the opened file
diagnosticsThe number of warnings and/or errors
workspace-diagnosticsThe number of warnings and/or errors on workspace
selectionsThe number of active selections
primary-selection-lengthThe number of characters currently in primary selection
positionThe cursor position
position-percentageThe cursor position as a percentage of the total number of lines
separatorThe string defined in editor.statusline.separator (defaults to "│")
spacerInserts a space between elements (multiple/contiguous spacers may be specified)
version-controlThe current branch name or detached commit hash of the opened workspace
registerThe current selected register
+
+

[editor.lsp] Section

+
+ + + + + + + +
KeyDescriptionDefault
enableEnables LSP integration. Setting to false will completely disable language servers regardless of language settings.true
display-messagesDisplay LSP progress messages below statusline1false
auto-signature-helpEnable automatic popup of signature help (parameter hints)true
display-inlay-hintsDisplay inlay hints2false
display-signature-help-docsDisplay docs under signature help popuptrue
snippetsEnables snippet completions. Requires a server restart (:lsp-restart) to take effect after :config-reload/:set.true
goto-reference-include-declarationInclude declaration in the goto references popup.true
+
+
1 +

By default, a progress spinner is shown in the statusline beside the file path.

+
+
2 +

You may also have to activate them in the LSP config for them to appear, not just in Helix. Inlay hints in Helix are still being improved on and may be a little bit laggy/janky under some circumstances. Please report any bugs you see so we can fix them!

+
+

[editor.cursor-shape] Section

+

Defines the shape of cursor in each mode. +Valid values for these options are block, bar, underline, or hidden.

+
+

💡 Due to limitations of the terminal environment, only the primary cursor can +change shape.

+
+
+ + + +
KeyDescriptionDefault
normalCursor shape in normal modeblock
insertCursor shape in insert modeblock
selectCursor shape in select modeblock
+
+

[editor.file-picker] Section

+

Set options for file picker and global search. Ignoring a file means it is +not visible in the Helix file picker and global search.

+

All git related options are only enabled in a git repository.

+
+ + + + + + + + + +
KeyDescriptionDefault
hiddenEnables ignoring hidden filestrue
follow-symlinksFollow symlinks instead of ignoring themtrue
deduplicate-linksIgnore symlinks that point at files already shown in the pickertrue
parentsEnables reading ignore files from parent directoriestrue
ignoreEnables reading .ignore filestrue
git-ignoreEnables reading .gitignore filestrue
git-globalEnables reading global .gitignore, whose path is specified in git's config: core.excludesfile optiontrue
git-excludeEnables reading .git/info/exclude filestrue
max-depthSet with an integer value for maximum depth to recurseUnset by default
+
+

Ignore files can be placed locally as .ignore or put in your home directory as ~/.ignore. They support the usual ignore and negative ignore (unignore) rules used in .gitignore files.

+

Additionally, you can use Helix-specific ignore files by creating a local .helix/ignore file in the current workspace or a global ignore file located in your Helix config directory:

+
    +
  • Linux and Mac: ~/.config/helix/ignore
    • +
  • Windows: %AppData%\helix\ignore
    • +
+

Example:

+
# unignore in file picker and global search
+!.github/
+!.gitignore
+!.gitattributes
+
+

[editor.auto-pairs] Section

+

Enables automatic insertion of pairs to parentheses, brackets, etc. Can be a +simple boolean value, or a specific mapping of pairs of single characters.

+

To disable auto-pairs altogether, set auto-pairs to false:

+
[editor]
+auto-pairs = false # defaults to `true`
+
+

The default pairs are (){}[]''""``, but these can be customized by +setting auto-pairs to a TOML table:

+
[editor.auto-pairs]
+'(' = ')'
+'{' = '}'
+'[' = ']'
+'"' = '"'
+'`' = '`'
+'<' = '>'
+
+

Additionally, this setting can be used in a language config. Unless +the editor setting is false, this will override the editor config in +documents with this language.

+

Example languages.toml that adds <> and removes ''

+
[[language]]
+name = "rust"
+
+[language.auto-pairs]
+'(' = ')'
+'{' = '}'
+'[' = ']'
+'"' = '"'
+'`' = '`'
+'<' = '>'
+
+

[editor.search] Section

+

Search specific options.

+
+ + +
KeyDescriptionDefault
smart-caseEnable smart case regex searching (case-insensitive unless pattern contains upper case characters)true
wrap-aroundWhether the search should wrap after depleting the matchestrue
+
+

[editor.whitespace] Section

+

Options for rendering whitespace with visible characters. Use :set whitespace.render all to temporarily enable visible whitespace.

+
+ + +
KeyDescriptionDefault
renderWhether to render whitespace. May either be all or none, or a table with sub-keys space, nbsp, nnbsp, tab, and newlinenone
charactersLiteral characters to use when rendering whitespace. Sub-keys may be any of tab, space, nbsp, nnbsp, newline or tabpadSee example below
+
+

Example

+
[editor.whitespace]
+render = "all"
+# or control each character
+[editor.whitespace.render]
+space = "all"
+tab = "all"
+nbsp = "none"
+nnbsp = "none"
+newline = "none"
+
+[editor.whitespace.characters]
+space = "·"
+nbsp = "⍽"
+nnbsp = "␣"
+tab = "→"
+newline = "⏎"
+tabpad = "·" # Tabs will look like "→···" (depending on tab width)
+
+

[editor.indent-guides] Section

+

Options for rendering vertical indent guides.

+
+ + + +
KeyDescriptionDefault
renderWhether to render indent guidesfalse
characterLiteral character to use for rendering the indent guide│
skip-levelsNumber of indent levels to skip0
+
+

Example:

+
[editor.indent-guides]
+render = true
+character = "╎" # Some characters that work well: "▏", "┆", "┊", "⸽"
+skip-levels = 1
+
+

[editor.gutters] Section

+

For simplicity, editor.gutters accepts an array of gutter types, which will +use default settings for all gutter components.

+
[editor]
+gutters = ["diff", "diagnostics", "line-numbers", "spacer"]
+
+

To customize the behavior of gutters, the [editor.gutters] section must +be used. This section contains top level settings, as well as settings for +specific gutter components as subsections.

+
+ +
KeyDescriptionDefault
layoutA vector of gutters to display["diagnostics", "spacer", "line-numbers", "spacer", "diff"]
+
+

Example:

+
[editor.gutters]
+layout = ["diff", "diagnostics", "line-numbers", "spacer"]
+
+

[editor.gutters.line-numbers] Section

+

Options for the line number gutter

+
+ +
KeyDescriptionDefault
min-widthThe minimum number of characters to use3
+
+

Example:

+
[editor.gutters.line-numbers]
+min-width = 1
+
+

[editor.gutters.diagnostics] Section

+

Currently unused

+

[editor.gutters.diff] Section

+

The diff gutter option displays colored bars indicating whether a git diff represents that a line was added, removed or changed. +These colors are controlled by the theme attributes diff.plus, diff.minus and diff.delta.

+

Other diff providers will eventually be supported by a future plugin system.

+

There are currently no options for this section.

+

[editor.gutters.spacer] Section

+

Currently unused

+

[editor.soft-wrap] Section

+

Options for soft wrapping lines that exceed the view width:

+
+ + + + + +
KeyDescriptionDefault
enableWhether soft wrapping is enabled.false
max-wrapMaximum free space left at the end of the line.20
max-indent-retainMaximum indentation to carry over when soft wrapping a line.40
wrap-indicatorText inserted before soft wrapped lines, highlighted with ui.virtual.wrap↪
wrap-at-text-widthSoft wrap at text-width instead of using the full viewport size.false
+
+

Example:

+
[editor.soft-wrap]
+enable = true
+max-wrap = 25 # increase value to reduce forced mid-word wrapping
+max-indent-retain = 0
+wrap-indicator = ""  # set wrap-indicator to "" to hide it
+
+

[editor.smart-tab] Section

+

Options for navigating and editing using tab key.

+
+ + +
KeyDescriptionDefault
enableIf set to true, then when the cursor is in a position with non-whitespace to its left, instead of inserting a tab, it will run move_parent_node_end. If there is only whitespace to the left, then it inserts a tab as normal. With the default bindings, to explicitly insert a tab character, press Shift-tab.true
supersede-menuNormally, when a menu is on screen, such as when auto complete is triggered, the tab key is bound to cycling through the items. This means when menus are on screen, one cannot use the tab key to trigger the smart-tab command. If this option is set to true, the smart-tab command always takes precedence, which means one cannot use the tab key to cycle through menu items. One of the other bindings must be used instead, such as arrow keys or C-n/C-p.false
+
+

Due to lack of support for S-tab in some terminals, the default keybindings don't fully embrace smart-tab editing experience. If you enjoy smart-tab navigation and a terminal that supports the Enhanced Keyboard protocol, consider setting extra keybindings:

+
[keys.normal]
+tab = "move_parent_node_end"
+S-tab = "move_parent_node_start"
+
+[keys.insert]
+S-tab = "move_parent_node_start"
+
+[keys.select]
+tab = "extend_parent_node_end"
+S-tab = "extend_parent_node_start"
+
+ +
+ + +
+
+ + + +
+ + + + + + + + + + + + + + + + + + +
+ + diff --git a/master/from-vim.html b/master/from-vim.html index a2c2cf063..a837fd6f3 100644 --- a/master/from-vim.html +++ b/master/from-vim.html @@ -89,7 +89,7 @@ diff --git a/master/guides/adding_languages.html b/master/guides/adding_languages.html index 0a2f54e2f..c09145ac4 100644 --- a/master/guides/adding_languages.html +++ b/master/guides/adding_languages.html @@ -89,7 +89,7 @@ diff --git a/master/guides/indent.html b/master/guides/indent.html index 0d6b14275..ba532e902 100644 --- a/master/guides/indent.html +++ b/master/guides/indent.html @@ -89,7 +89,7 @@ diff --git a/master/guides/index.html b/master/guides/index.html index aff2e9763..22492138b 100644 --- a/master/guides/index.html +++ b/master/guides/index.html @@ -89,7 +89,7 @@ diff --git a/master/guides/injection.html b/master/guides/injection.html index 301f576e1..e277c0eb5 100644 --- a/master/guides/injection.html +++ b/master/guides/injection.html @@ -89,7 +89,7 @@ diff --git a/master/guides/textobject.html b/master/guides/textobject.html index 3cd121bf6..38888c4ad 100644 --- a/master/guides/textobject.html +++ b/master/guides/textobject.html @@ -89,7 +89,7 @@ diff --git a/master/index.html b/master/index.html index 4ed7854d4..6a6c65641 100644 --- a/master/index.html +++ b/master/index.html @@ -89,7 +89,7 @@ diff --git a/master/install.html b/master/install.html index e6e2a1cba..207c838d2 100644 --- a/master/install.html +++ b/master/install.html @@ -89,7 +89,7 @@ @@ -180,56 +180,12 @@

Installing Helix

- - -

To install Helix, follow the instructions specific to your operating system. Note that:

  • To get the latest nightly version of Helix, you need to -build from source.

    +build from source.

  • To take full advantage of Helix, install the language servers for your @@ -242,203 +198,6 @@ for instructions.

    Download pre-built binaries from the GitHub Releases page. Add the hx binary to your system's $PATH to use it from the command line, and copy the runtime directory into the config directory (for example ~/.config/helix/runtime on Linux/macOS). The runtime location can be overriden via the HELIX_RUNTIME environment variable.

    -

    Linux, macOS, Windows and OpenBSD packaging status

    -

    Packaging status

    -

    Linux

    -

    The following third party repositories are available:

    -

    Ubuntu

    -

    Add the PPA for Helix:

    -
    sudo add-apt-repository ppa:maveonair/helix-editor
-sudo apt update
-sudo apt install helix
-
    -

    Fedora/RHEL

    -
    sudo dnf install helix
-
    -

    Arch Linux extra

    -

    Releases are available in the extra repository:

    -
    sudo pacman -S helix
-
    -
    -

    💡 When installed from the extra repository, run Helix with helix instead of hx.

    -

    For example:

    -
    helix --health
-
    -

    to check health

    -
    -

    Additionally, a helix-git package is available -in the AUR, which builds the master branch.

    -

    NixOS

    -

    Helix is available in nixpkgs through the helix attribute, -the unstable channel usually carries the latest release.

    -

    Helix is also available as a flake in the project -root. Use nix develop to spin up a reproducible development shell. Outputs are -cached for each push to master using Cachix. The -flake is configured to automatically make use of this cache assuming the user -accepts the new settings on first use.

    -

    If you are using a version of Nix without flakes enabled, -install Cachix CLI and use -cachix use helix to configure Nix to use cached outputs when possible.

    -

    Flatpak

    -

    Helix is available on Flathub:

    -
    flatpak install flathub com.helix_editor.Helix
-flatpak run com.helix_editor.Helix
-
    -

    Snap

    -

    Helix is available on Snapcraft and can be installed with:

    -
    snap install --classic helix
-
    -

    This will install Helix as both /snap/bin/helix and /snap/bin/hx, so make sure /snap/bin is in your PATH.

    -

    AppImage

    -

    Install Helix using the Linux AppImage format. -Download the official Helix AppImage from the latest releases page.

    -
    chmod +x helix-*.AppImage # change permission for executable mode
-./helix-*.AppImage # run helix
-
    -

    macOS

    -

    Homebrew Core

    -
    brew install helix
-
    -

    MacPorts

    -
    port install helix
-
    -

    Windows

    -

    Install on Windows using Winget, Scoop, Chocolatey -or MSYS2.

    -

    Winget

    -

    Windows Package Manager winget command-line tool is by default available on Windows 11 and modern versions of Windows 10 as a part of the App Installer. -You can get App Installer from the Microsoft Store. If it's already installed, make sure it is updated with the latest version.

    -
    winget install Helix.Helix
-
    -

    Scoop

    -
    scoop install helix
-
    -

    Chocolatey

    -
    choco install helix
-
    -

    MSYS2

    -

    For 64-bit Windows 8.1 or above:

    -
    pacman -S mingw-w64-ucrt-x86_64-helix
-
    -

    Building from source

    -

    Requirements:

    -

    Clone the Helix GitHub repository into a directory of your choice. The -examples in this documentation assume installation into either ~/src/ on -Linux and macOS, or %userprofile%\src\ on Windows.

    - -

    If you are using the musl-libc standard library instead of glibc the following environment variable must be set during the build to ensure tree-sitter grammars can be loaded correctly:

    -
    RUSTFLAGS="-C target-feature=-crt-static"
-
    -
      -
    1. -

      Clone the repository:

      -
      git clone https://github.com/helix-editor/helix
-cd helix
-
      -
      2. -
    2. -

      Compile from source:

      -
      cargo install --path helix-term --locked
-
      -

      This command will create the hx executable and construct the tree-sitter -grammars in the local runtime folder.

      -
      3. -
    -
    -

    💡 If you do not want to fetch or build grammars, set an environment variable HELIX_DISABLE_AUTO_GRAMMAR_BUILD

    -
    -
    -

    💡 Tree-sitter grammars can be fetched and compiled if not pre-packaged. Fetch -grammars with hx --grammar fetch and compile them with -hx --grammar build. This will install them in -the runtime directory within the user's helix config directory (more -details below).

    -
    -

    Configuring Helix's runtime files

    -

    Linux and macOS

    -

    The runtime directory is one below the Helix source, so either export a -HELIX_RUNTIME environment variable to point to that directory and add it to -your ~/.bashrc or equivalent:

    -
    export HELIX_RUNTIME=~/src/helix/runtime
-
    -

    Or, create a symbolic link:

    -
    ln -Ts $PWD/runtime ~/.config/helix/runtime
-
    -

    If the above command fails to create a symbolic link because the file exists either move ~/.config/helix/runtime to a new location or delete it, then run the symlink command above again.

    -

    Windows

    -

    Either set the HELIX_RUNTIME environment variable to point to the runtime files using the Windows setting (search for -Edit environment variables for your account) or use the setx command in -Cmd:

    -
    setx HELIX_RUNTIME "%userprofile%\source\repos\helix\runtime"
-
    -
    -

    💡 %userprofile% resolves to your user directory like -C:\Users\Your-Name\ for example.

    -
    -

    Or, create a symlink in %appdata%\helix\ that links to the source code directory:

    -
    - - -
    MethodCommand
    PowerShellNew-Item -ItemType Junction -Target "runtime" -Path "$Env:AppData\helix\runtime"
    Cmdcd %appdata%\helix
    mklink /D runtime "%userprofile%\src\helix\runtime"
    -
    -
    -

    💡 On Windows, creating a symbolic link may require running PowerShell or -Cmd as an administrator.

    -
    -

    Multiple runtime directories

    -

    When Helix finds multiple runtime directories it will search through them for files in the -following order:

    -
      -
    1. runtime/ sibling directory to $CARGO_MANIFEST_DIR directory (this is intended for -developing and testing helix only).
      2. -
    2. runtime/ subdirectory of OS-dependent helix user config directory.
      3. -
    3. $HELIX_RUNTIME
      4. -
    4. Distribution-specific fallback directory (set at compile time—not run time— -with the HELIX_DEFAULT_RUNTIME environment variable)
      5. -
    5. runtime/ subdirectory of path to Helix executable.
      6. -
    -

    This order also sets the priority for selecting which file will be used if multiple runtime -directories have files with the same name.

    -

    Note to packagers

    -

    If you are making a package of Helix for end users, to provide a good out of -the box experience, you should set the HELIX_DEFAULT_RUNTIME environment -variable at build time (before invoking cargo build) to a directory which -will store the final runtime files after installation. For example, say you want -to package the runtime into /usr/lib/helix/runtime. The rough steps a build -script could follow are:

    -
      -
    1. export HELIX_DEFAULT_RUNTIME=/usr/lib/helix/runtime
      2. -
    2. cargo build --profile opt --locked --path helix-term
      3. -
    3. cp -r runtime $BUILD_DIR/usr/lib/helix/
      4. -
    4. cp target/opt/hx $BUILD_DIR/usr/bin/hx
      5. -
    -

    This way the resulting hx binary will always look for its runtime directory in -/usr/lib/helix/runtime if the user has no custom runtime in ~/.config/helix -or HELIX_RUNTIME.

    -

    Validating the installation

    -

    To make sure everything is set up as expected you should run the Helix health -check:

    -
    hx --health
-
    -

    For more information on the health check results refer to -Health check.

    -

    Configure the desktop shortcut

    -

    If your desktop environment supports the -XDG desktop menu -you can configure Helix to show up in the application menu by copying the -provided .desktop and icon files to their correct folders:

    -
    cp contrib/Helix.desktop ~/.local/share/applications
-cp contrib/helix.png ~/.icons # or ~/.local/share/icons
-
    -

    To use another terminal than the system default, you can modify the .desktop -file. For example, to use kitty:

    -
    sed -i "s|Exec=hx %F|Exec=kitty hx %F|g" ~/.local/share/applications/Helix.desktop
-sed -i "s|Terminal=true|Terminal=false|g" ~/.local/share/applications/Helix.desktop
-
@@ -448,7 +207,7 @@ sed -i "s|Terminal=true|Terminal=false|g" ~/.local/share/applications/Helix.desk - @@ -462,7 +221,7 @@ sed -i "s|Terminal=true|Terminal=false|g" ~/.local/share/applications/Helix.desk - diff --git a/master/keymap.html b/master/keymap.html index 241dbd3d4..801ecb088 100644 --- a/master/keymap.html +++ b/master/keymap.html @@ -89,7 +89,7 @@ @@ -179,7 +179,7 @@
-

Keymap

+

Keymap

  • Normal mode
      @@ -631,7 +631,7 @@ you to selectively add search terms to your selections.

💡 f, t, etc. need a tree-sitter grammar active for the current -document and a special tree-sitter query file to work properly. Only -some grammars currently have the query file implemented. +document and a special tree-sitter query file to work properly. [Only +some grammars][lang-support] currently have the query file implemented. Contributions are welcome!

@@ -564,14 +550,14 @@ Contributions are welcome!

possible using tree-sitter and textobject queries. For example to move to the next function use ]f, to move to previous type use [t, and so on.

-

Tree-sitter-nav-demo

-

For the full reference see the unimpaired section of the key bind +

![Tree-sitter-nav-demo][tree-sitter-nav-demo]

+

For the full reference see the [unimpaired][unimpaired-keybinds] section of the key bind documentation.

💡 This feature relies on tree-sitter textobjects and requires the corresponding query file to work properly.

-

Moving the selection with syntax-aware motions

+

Moving the selection with syntax-aware motions

Alt-p, Alt-o, Alt-i, and Alt-n (or Alt and arrow keys) allow you to move the selection according to its location in the syntax tree. For example, many languages have the following syntax for function calls:

@@ -619,7 +605,7 @@ child node will be selected. In the event that arg1 does not have a sibling, the selection will move up the syntax tree and select the previous element. As a result, using Alt-p with a selection on arg1 will move the selection to the "func" identifier.

-

Keymap

+

Keymap