Skip to content

Commit

Permalink
Rewrite and refactor all documentation (helix-editor#5534)
Browse files Browse the repository at this point in the history 
* Rewrite and refactor all documentation

* Rewrite and refactor the guides

* update runtime directory instructions for windows

* Update the Ubuntu 3rd party repo section with 22.10

* Merge from upstream

* Rewrite and refactor all documentation

* Apply suggestions from code review

Apply the suggestions that can be committed from the GitHub web interface.

Co-authored-by: Michael Davis <mcarsondavis@gmail.com>

* Add Windows themes folder

Co-authored-by: digidoor <37601466+digidoor@users.noreply.github.com>

* Apply the rest of the suggestions from the code review

* Revert "Apply the rest of the suggestions from the code review"

This reverts commit 498be1b.

* Revert "Merge branch 'rewrite-and-refactor-all-documentation' of github.com:David-Else/helix into rewrite-and-refactor-all-documentation"

This reverts commit 7c84042, reversing
changes made to d932969.

* Apply code review suggestions

* Changes after re-reading all documents

* Missed a full stop

* Code review suggestions and remove macOS and Windows specific sections

* Add OpenBSD to heading

* Add back macOS and Windows sections and further simplify and improve

* Change wording to nightly

* Remove README installation section and turn into a link

* Simplify building from source and follow code review suggestions

* Code review revisions

* Fix copy paste mistake

* Apply the latest code review suggestions

* More small code review items

* Change minor modes for code review

* Fix link and typos

* Add note that you need a c++ compiler to install the tree-sitter grammars

* Add pacman example

* Make sure all headings are lower case

* Revert to the original passage adding a reference to Windows that was missing

* Update book/src/guides/adding_languages.md

Fix grammar typo

Co-authored-by: Michael Davis <mcarsondavis@gmail.com>

* Update book/src/install.md

Fix tree sitter typo

Co-authored-by: Michael Davis <mcarsondavis@gmail.com>

* Remove TOC links to main heading

---------

Co-authored-by: CptPotato <3957610+CptPotato@users.noreply.github.com>
Co-authored-by: Michael Davis <mcarsondavis@gmail.com>
Co-authored-by: digidoor <37601466+digidoor@users.noreply.github.com>
  • Loading branch information
@David-Else @CptPotato
@the-mikedavis @digidoor
4 people authored and Sagnik Bhattacharya committed Mar 21, 2023
1 parent 84542df commit bbe995c
Show file tree
Hide file tree
Showing 15 changed files with 465 additions and 471 deletions.
84 changes: 1 addition & 83 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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).
Expand Down
10 changes: 5 additions & 5 deletions book/src/SUMMARY.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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)
2 changes: 1 addition & 1 deletion book/src/commands.md
View file
Original file line number Diff line number Diff line change
@@ -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}}
89 changes: 43 additions & 46 deletions book/src/configuration.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand All @@ -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` |

Expand Down Expand Up @@ -125,10 +123,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` |
Expand All @@ -141,25 +141,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

Expand Down Expand Up @@ -211,7 +208,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
Expand All @@ -220,7 +217,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
Expand Down Expand Up @@ -248,7 +245,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` |

Expand All @@ -273,7 +270,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 |
| --- | --- | --- |
Expand Down Expand Up @@ -315,13 +312,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:
Expand Down
2 changes: 1 addition & 1 deletion book/src/guides/README.md
View file
Original file line number Diff line number Diff line change
@@ -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.
Loading

0 comments on commit bbe995c

Please sign in to comment.