Rewrite and refactor all documentation

README.md

@@ -45,92 +45,10 @@ Note: Only certain languages have indentation definitions at the moment. Check
 
 # Installation
 
-Packages are available for various distributions (see [Installation docs](https://docs.helix-editor.com/install.html)).
-
-If you would like to build from source:
-
-```shell
-git clone https://github.com/helix-editor/helix
-cd helix
-cargo install --locked --path helix-term
-```
-
-This will install the `hx` binary to `$HOME/.cargo/bin` and build tree-sitter grammars in `./runtime/grammars`.
-
-Helix needs its runtime files so make sure to copy/symlink the `runtime/` directory into the
-config directory (for example `~/.config/helix/runtime` on Linux/macOS, or `%AppData%/helix/runtime` on Windows).
-
-| OS                   | Command                                          |
-| -------------------- | ------------------------------------------------ |
-| Windows (Cmd)        | `xcopy /e /i runtime %AppData%\helix\runtime`    |
-| Windows (PowerShell) | `xcopy /e /i runtime $Env:AppData\helix\runtime` |
-| Linux / macOS        | `ln -s $PWD/runtime ~/.config/helix/runtime`     |
-
-Starting with Windows Vista you can also create symbolic links on Windows. Note that this requires
-elevated privileges - i.e. PowerShell or Cmd must be run as administrator.
-
-**PowerShell:**
-
-```powershell
-New-Item -ItemType Junction -Target "runtime" -Path "$Env:AppData\helix\runtime"
-```
-Note: "runtime" must be absolute path to the runtime directory.
-
-**Cmd:**
-
-```cmd
-cd %appdata%\helix
-mklink /D runtime "<helix-repo>\runtime"
-```
-
-The runtime location can be overridden via the `HELIX_RUNTIME` environment variable.
-
-> NOTE: if `HELIX_RUNTIME` is set prior to calling `cargo install --locked --path helix-term`,
-> tree-sitter grammars will be built in `$HELIX_RUNTIME/grammars`.
-
-If you plan on keeping the repo locally, an alternative to copying/symlinking
-runtime files is to set `HELIX_RUNTIME=/path/to/helix/runtime`
-(`HELIX_RUNTIME=$PWD/runtime` if you're in the helix repo directory).
-
-Packages already solve this for you by wrapping the `hx` binary with a wrapper
-that sets the variable to the install dir.
-
-> NOTE: running via cargo also doesn't require setting explicit `HELIX_RUNTIME` path, it will automatically
-> detect the `runtime` directory in the project root.
-
-If you want to customize your `languages.toml` config,
-tree-sitter grammars may be manually fetched and built with `hx --grammar fetch` and `hx --grammar build`.
-
-In order to use LSP features like auto-complete, you will need to
-[install the appropriate Language Server](https://github.com/helix-editor/helix/wiki/How-to-install-the-default-language-servers)
-for a language.
+[Installation documentation](https://docs.helix-editor.com/install.html).
 
 [![Packaging status](https://repology.org/badge/vertical-allrepos/helix.svg)](https://repology.org/project/helix/versions)
 
-## Adding Helix to your desktop environment
-
-If installing from source, to use Helix in desktop environments that supports [XDG desktop menu](https://specifications.freedesktop.org/menu-spec/menu-spec-latest.html), including Gnome and KDE, copy the provided `.desktop` file to the correct folder:
-
-```bash
-cp contrib/Helix.desktop ~/.local/share/applications
-cp contrib/helix.png ~/.local/share/icons
-```
-
-To use another terminal than the default, you will need to modify the `.desktop` file. For example, to use `kitty`:
-
-```bash
-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
-```
-
-## macOS
-
-Helix can be installed on macOS through homebrew:
-
-```
-brew install helix
-```
-
 # Contributing
 
 Contributing guidelines can be found [here](./docs/CONTRIBUTING.md).

book/src/SUMMARY.md

@@ -6,13 +6,13 @@
 - [Usage](./usage.md)
   - [Keymap](./keymap.md)
   - [Commands](./commands.md)
-  - [Language Support](./lang-support.md)
+  - [Language support](./lang-support.md)
 - [Migrating from Vim](./from-vim.md)
 - [Configuration](./configuration.md)
   - [Themes](./themes.md)
-  - [Key Remapping](./remapping.md)
+  - [Key remapping](./remapping.md)
   - [Languages](./languages.md)
 - [Guides](./guides/README.md)
-  - [Adding Languages](./guides/adding_languages.md)
-  - [Adding Textobject Queries](./guides/textobject.md)
-  - [Adding Indent Queries](./guides/indent.md)
+  - [Adding languages](./guides/adding_languages.md)
+  - [Adding textobject queries](./guides/textobject.md)
+  - [Adding indent queries](./guides/indent.md)

book/src/commands.md

@@ -1,5 +1,5 @@
 # Commands
 
-Command mode can be activated by pressing `:`, similar to Vim. Built-in commands:
+Command mode can be activated by pressing `:`. The built-in commands are:
 
 {{#include ./generated/typable-cmd.md}}

book/src/configuration.md

@@ -2,10 +2,10 @@
 
 To override global configuration parameters, create a `config.toml` file located in your config directory:
 
-* Linux and Mac: `~/.config/helix/config.toml`
-* Windows: `%AppData%\helix\config.toml`
+- Linux and Mac: `~/.config/helix/config.toml`
+- Windows: `%AppData%\helix\config.toml`
 
-> Hint: You can easily open the config file by typing `:config-open` within Helix normal mode.
+> 💡 You can easily open the config file by typing `:config-open` within Helix normal mode.
 
 Example config:
 
@@ -25,36 +25,34 @@ select = "underline"
 hidden = false
 ```
 
-You may also specify a file to use for configuration with the `-c` or
-`--config` CLI argument: `hx -c path/to/custom-config.toml`.
-
-It is also possible to trigger configuration file reloading by sending the `USR1`
-signal to the helix process, e.g. via `pkill -USR1 hx`. This is only supported 
-on unix operating systems.
+You can use a custom configuration file by specifying it with the `-c` or
+`--config` command line argument, for example `hx -c path/to/custom-config.toml`.
+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`.
 
 ## Editor
 
 ### `[editor]` Section
 
 | Key | Description | Default |
 |--|--|---------|
-| `scrolloff` | Number of lines of padding around the edge of the screen when scrolling. | `5` |
-| `mouse` | Enable mouse mode. | `true` |
-| `middle-click-paste` | Middle click paste support. | `true` |
-| `scroll-lines` | Number of lines to scroll per scroll wheel step. | `3` |
-| `shell` | Shell to use when running external commands. | Unix: `["sh", "-c"]`<br/>Windows: `["cmd", "/C"]` |
-| `line-number` | Line 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 numbers. | `absolute` |
-| `cursorline` | Highlight all lines with a cursor. | `false` |
-| `cursorcolumn` | Highlight all columns with a cursor. | `false` |
+| `scrolloff` | Number of lines of padding around the edge of the screen when scrolling | `5` |
+| `mouse` | Enable mouse mode | `true` |
+| `middle-click-paste` | Middle click paste support | `true` |
+| `scroll-lines` | Number of lines to scroll per scroll wheel step | `3` |
+| `shell` | Shell to use when running external commands | Unix: `["sh", "-c"]`<br/>Windows: `["cmd", "/C"]` |
+| `line-number` | Line 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 numbers | `absolute` |
+| `cursorline` | Highlight all lines with a cursor | `false` |
+| `cursorcolumn` | Highlight all columns with a cursor | `false` |
 | `gutters` | Gutters 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-completion` | Enable automatic pop up of auto-completion. | `true` |
-| `auto-format` | Enable automatic formatting on save. | `true` |
-| `auto-save` | Enable automatic saving on focus moving away from Helix. Requires [focus event support](https://github.com/helix-editor/helix/wiki/Terminal-Support) from your terminal. | `false` |
-| `idle-timeout` | Time in milliseconds since last keypress before idle timers trigger. Used for autocompletion, set to 0 for instant. | `400` |
+| `auto-completion` | Enable automatic pop up of auto-completion | `true` |
+| `auto-format` | Enable automatic formatting on save | `true` |
+| `auto-save` | Enable automatic saving on the focus moving away from Helix. Requires [focus event support](https://github.com/helix-editor/helix/wiki/Terminal-Support) from your terminal | `false` |
+| `idle-timeout` | Time in milliseconds since last keypress before idle timers trigger. Used for autocompletion, set to 0 for instant | `400` |
 | `completion-trigger-len` | The min-length of word under cursor to trigger autocompletion | `2` |
-| `auto-info` | Whether to display infoboxes | `true` |
-| `true-color` | Set to `true` to override automatic detection of terminal truecolor support in the event of a false negative. | `false` |
-| `rulers` | List of column positions at which to display the rulers. Can be overridden by language specific `rulers` in `languages.toml` file. | `[]` |
+| `auto-info` | Whether to display info boxes | `true` |
+| `true-color` | Set to `true` to override automatic detection of terminal truecolor support in the event of a false negative | `false` |
+| `rulers` | List of column positions at which to display the rulers. Can be overridden by language specific `rulers` in `languages.toml` file | `[]` |
 | `bufferline` | Renders 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-modes` | Whether to color the mode indicator with different colors depending on the mode itself | `false` |
 
@@ -124,10 +122,12 @@ The following statusline elements can be configured:
 
 ### `[editor.cursor-shape]` Section
 
-Defines the shape of cursor in each mode. Note that due to limitations
-of the terminal environment, only the primary cursor can change shape.
+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.
+
 | Key      | Description                                | Default |
 | ---      | -----------                                | ------- |
 | `normal` | Cursor shape in [normal mode][normal mode] | `block` |
@@ -140,25 +140,22 @@ Valid values for these options are `block`, `bar`, `underline`, or `hidden`.
 
 ### `[editor.file-picker]` Section
 
-Sets options for file picker and global search. All but the last key listed in
-the default file-picker configuration below are IgnoreOptions: whether hidden
-files and files listed within ignore files are ignored by (not visible in) the
-helix file picker and global search. There is also one other key, `max-depth`
-available, which is not defined by default.
+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.
 
 | Key | Description | Default |
 |--|--|---------|
-|`hidden` | Enables ignoring hidden files. | true
+|`hidden` | Enables ignoring hidden files | true
 |`follow-links` | Follow symlinks instead of ignoring them | true
 |`deduplicate-links` | Ignore symlinks that point at files already shown in the picker | true
-|`parents` | Enables reading ignore files from parent directories. | true
-|`ignore` | Enables reading `.ignore` files. | true
-|`git-ignore` | Enables reading `.gitignore` files. | true
-|`git-global` | Enables reading global .gitignore, whose path is specified in git's config: `core.excludefile` option. | true
-|`git-exclude` | Enables reading `.git/info/exclude` files. | true
-|`max-depth` | Set with an integer value for maximum depth to recurse. | Defaults to `None`.
+|`parents` | Enables reading ignore files from parent directories | true
+|`ignore` | Enables reading `.ignore` files | true
+|`git-ignore` | Enables reading `.gitignore` files | true
+|`git-global` | Enables reading global `.gitignore`, whose path is specified in git's config: `core.excludefile` option | true
+|`git-exclude` | Enables reading `.git/info/exclude` files | true
+|`max-depth` | Set with an integer value for maximum depth to recurse | Defaults to `None`.
 
 ### `[editor.auto-pairs]` Section
 
@@ -210,7 +207,7 @@ Search specific options.
 
 | Key | Description | Default |
 |--|--|---------|
-| `smart-case` | Enable smart case regex searching (case insensitive unless pattern contains upper case characters) | `true` |
+| `smart-case` | Enable smart case regex searching (case-insensitive unless pattern contains upper case characters) | `true` |
 | `wrap-around`| Whether the search should wrap after depleting the matches | `true` |
 
 ### `[editor.whitespace]` Section
@@ -219,7 +216,7 @@ Options for rendering whitespace with visible characters. Use `:set whitespace.r
 
 | Key | Description | Default |
 |-----|-------------|---------|
-| `render` | Whether to render whitespace. May either be `"all"` or `"none"`, or a table with sub-keys `space`, `nbsp`, `tab`, and `newline`. | `"none"` |
+| `render` | Whether to render whitespace. May either be `"all"` or `"none"`, or a table with sub-keys `space`, `nbsp`, `tab`, and `newline` | `"none"` |
 | `characters` | Literal characters to use when rendering whitespace. Sub-keys may be any of `tab`, `space`, `nbsp`, `newline` or `tabpad` | See example below |
 
 Example
@@ -247,7 +244,7 @@ Options for rendering vertical indent guides.
 
 | Key           | Description                                             | Default |
 | ---           | ---                                                     | ---     |
-| `render`      | Whether to render indent guides.                        | `false` |
+| `render`      | Whether to render indent guides                         | `false` |
 | `character`   | Literal character to use for rendering the indent guide | `│`     |
 | `skip-levels` | Number of indent levels to skip                         | `0`     |
 
@@ -272,7 +269,7 @@ 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 sub-sections.
+specific gutter components as subsections.
 
 | Key      | Description                    | Default                                                       |
 | ---      | ---                            | ---                                                           |
@@ -314,13 +311,13 @@ Currently unused
 
 ### `[editor.soft-wrap]` Section
 
-Options for soft wrapping lines that exceed the view width
+Options for soft wrapping lines that exceed the view width:
 
 | Key                 | Description                                                  | Default |
 | ---                 | ---                                                          | ---     |
-| `enable`            | Whether soft wrapping is enabled.                            | `false` |
-| `max-wrap`          | Maximum free space left at the end of the line.              | `20`    |
-| `max-indent-retain` | Maximum indentation to carry over when soft wrapping a line. | `40`    |
+| `enable`            | Whether soft wrapping is enabled                             | `false` |
+| `max-wrap`          | Maximum free space left at the end of the line               | `20`    |
+| `max-indent-retain` | Maximum indentation to carry over when soft wrapping a line  | `40`    |
 | `wrap-indicator`    | Text inserted before soft wrapped lines, highlighted with `ui.virtual.wrap` | `↪ `    |
 
 Example:

book/src/guides/README.md

@@ -1,4 +1,4 @@
 # Guides
 
 This section contains guides for adding new language server configurations,
-tree-sitter grammars, textobject queries, etc.
+tree-sitter grammars, textobject queries, and other similar items.