From 1fed4d2c1755e06a47d2ada37818352d2e2d7a25 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Igor=20T=C3=A1mara?= Date: Sun, 2 Nov 2025 00:32:43 -0500 Subject: [PATCH] Improved internal links and adopt zig highlight --- content/docs/architecture/command.smd | 53 ++++++++++--------- .../index.smd} | 2 +- content/docs/architecture/keybind.smd | 13 ++--- content/docs/architecture/minimode.smd | 16 +++--- content/docs/architecture/palette.smd | 6 +-- content/docs/mode/helix.smd | 46 +++++++++------- 6 files changed, 74 insertions(+), 62 deletions(-) rename content/docs/{architecture.smd => architecture/index.smd} (99%) diff --git a/content/docs/architecture/command.smd b/content/docs/architecture/command.smd index 8d251cf..b30135a 100644 --- a/content/docs/architecture/command.smd +++ b/content/docs/architecture/command.smd @@ -99,24 +99,6 @@ sent to commands vary for each command. Sometimes [keybinding](/docs/architecture/keybind) is enough to accomplish a compound of already present commands. -[]($section.id('deepen')) -## Code organization - -Is common to define private functions in a given module that are -invoked from commands, as usual, functions are meant to be reused and -help organize code. - -For example, in hx mode `helix.zig` the `select_to_char_left_helix` -command uses the functions `helix_with_selections_const_arg` which -iterates over all cursels and applies the -`select_cursel_to_char_left_helix` function. - -```zig -pub fn select_to_char_left_helix(_: *void, ctx: Ctx) Result { - try helix_with_selections_const_arg(ctx, &select_cursel_to_char_left_helix); -} -``` - []($section.id('command_arguments')) ### Sending parameters to commands @@ -133,7 +115,6 @@ extract from the context like this: ```zig pub fn goto_line(self: *Self, ctx: Context) Result { - var line: usize = 0; if (!try ctx.args.match(.{tp.extract(&line)})) return error.InvalidGotoLineArgument; @@ -162,15 +143,39 @@ and json, packing all of them in Command.Context. A deeper explanation of the rules about parameter passing is exposed in [inner data exchange](/docs/architecture/inner_data_exchange), given -that parameters can be sent not only to commands, but other broather +that parameters can be sent not only to commands, but other broader use cases. +[]($section.id('deepen')) +## Code organization + +Is common to define private functions in a given module meant to be +invoked from commands. As usual, reusing code with functions +help organize code. + +For example, in hx mode `src/tui/mode/helix.zig` the +`select_to_char_left_helix` command uses the functions +`helix_with_selections_const_arg` which iterates over all cursels and +applies the `select_cursel_to_char_left_helix` function. + +```zig +pub fn select_to_char_left_helix(_: *void, ctx: Ctx) Result { + try helix_with_selections_const_arg(ctx, &select_cursel_to_char_left_helix); +} +``` + []($section.id('next')) ## Next steps -* [minimode](/docs/architecture/minimode) shows argument passing to -commands in reaction to keypresses. -* [Palettes](/docs/architecture/palette) invoke commands and pass -parameters to them. +[Minimodes](/docs/architecture/minimode) pass arguments to the editor, +if you wonder how to go beyond the current buffer window, when there +are actions like going to a specific line or when searching or +replacing a character,this is the place. + +[Palettes](/docs/architecture/palette) are built to open files, change +buffers and also pass parameters to commands. Diving out from the +buffer and editor. + * [Add tests](/docs/testing) to harden your code +* [Sending parameters across](/docs/architecture/inner_data_exchange) * [Back to architecture](/docs/architecture) \ No newline at end of file diff --git a/content/docs/architecture.smd b/content/docs/architecture/index.smd similarity index 99% rename from content/docs/architecture.smd rename to content/docs/architecture/index.smd index 5e8dbd4..c76e1a7 100644 --- a/content/docs/architecture.smd +++ b/content/docs/architecture/index.smd @@ -116,7 +116,7 @@ feedback via `logview`. To view logs use `f11` to toggle the previous messages, or alternatively, open flow with the option `--show-logs`. -To log something, first import +To log something, first, `import log` ```zig const log = @import("log"); diff --git a/content/docs/architecture/keybind.smd b/content/docs/architecture/keybind.smd index 2ef1b31..b5a79cc 100644 --- a/content/docs/architecture/keybind.smd +++ b/content/docs/architecture/keybind.smd @@ -39,7 +39,7 @@ key/combos and add an array, where the first element is the combination to map to the commands that will be invoked, the array accepts strings like in -```js +```zig ["ctrl+alt+shift+p", "open_command_palette"] ``` @@ -122,7 +122,7 @@ its results to a *scratch buffer* called `test`. The original definition is: -```js +```zig ["f5", ["create_scratch_buffer", "*test*"], ["shell_execute_insert", "zig", "build", "test"]], ``` @@ -139,7 +139,7 @@ a shell command called `zig` with the parameters `build` and `test`; if you don't have zig installed, it will not work, and you might want to remap `f5` to a different shell command. -``` +```zig [ "f5", [ @@ -174,6 +174,7 @@ flow. * Making flow even better with [tests](/docs/testing) -* [How to contribute](/docs/contributing) -* [Get in touch](https://discord.com/invite/4wvteUPphx) to share your -combos +* Adding [new commands](/docs/architecture/command) +* [Contributing](/docs/contributing) +* [Getting in touch](https://discord.com/invite/4wvteUPphx) to share +your combos diff --git a/content/docs/architecture/minimode.smd b/content/docs/architecture/minimode.smd index 3a173e2..c4e0b92 100644 --- a/content/docs/architecture/minimode.smd +++ b/content/docs/architecture/minimode.smd @@ -10,12 +10,11 @@ }, --- -Minimodes commitment is to add functionality to the editor, are opened -for short periods of time and have their own set of keybindings to -execute an specific action, i.e. find something in the current buffer -or in project files, open/save a file, and, in modal modes(like vim -and helix), as receiving a number as a prefix to repeat an action many -times. +Minimodes add functionality to the editor, are opened for short periods +of time and have their own set of keybindings to execute an specific +action, i.e. find something in the current buffer or in project files, +open/save a file, and, in modal modes(like vim and helix), as receiving +a number as a prefix to repeat an action many times. []($section.id("anatomy")) ## Anatomy of minimodes @@ -111,6 +110,7 @@ example(look for it in the command palette `:`). []($section.id("next")) ## Next steps -* Head to [architecture](/docs/architecture) +* Create [palettes](/docs/architecture/palette) * Review [commands](/docs/architecture/command) -* Review [keybindings](/docs/architecture/keybind) +* Adjust [keybindings](/docs/architecture/keybind) +* To [architecture](/docs/architecture) diff --git a/content/docs/architecture/palette.smd b/content/docs/architecture/palette.smd index 41dfecf..310f69d 100644 --- a/content/docs/architecture/palette.smd +++ b/content/docs/architecture/palette.smd @@ -18,9 +18,9 @@ the elements, and having special elements that trigger different actions, for example, the task palette. Examples of palettes are `command_palette`, `clipboard_palette`, they -all are based on `src/tui/mode/overlay/palette.zig that does all the -heavy lifting and sets the framework to create new palettes as simple -as possible. +all are based on `src/tui/mode/overlay/palette.zig` doing all the heavy +lifting and sets the framework to create new palettes as simple as +possible. Palettes are an special case of [minimode] and for instance a mode, they receive inputs from the keyboard and execute the beforehand mentioned diff --git a/content/docs/mode/helix.smd b/content/docs/mode/helix.smd index 3b983f4..57e137f 100644 --- a/content/docs/mode/helix.smd +++ b/content/docs/mode/helix.smd @@ -10,7 +10,7 @@ }, --- -This document describes implementation of Helix Mode. +This document describes Helix Mode implementation. []($section.id('what')) ## What and what not @@ -19,16 +19,21 @@ The first and biggest difference is that Flow has a mode that emulates Helix, or at least has equivalent of the worthiest actions that can be done with Helix. The conversely is not true. +When entering to Helix Mode through `F4`, you land on `NOR` +[imode](/docs/architecture/keybind#hierarchy), there are `SEL` and +`INS` imodes implemented. + `:` opens up Flow's rich command palette that might have functionalities Helix users are used to have, if you find something missing, it's possible to -[open a Feature Request](https://github.com/neurocyte/flow/issues), +[open a feature request](https://github.com/neurocyte/flow/issues), make sure to review [other issues](https://github.com/neurocyte/flow/issues?q=is%3Aissue%20state%3Aopen%20label%3Ahelix-mode) -to avoid repeating or see if there is anyone interested in porting on -[Discord](https://discord.gg/kzJC9fA7) to ask if or there is a -workaround, remember that it's possible to bounce back to Flow mode -if needed. +to avoid repeating or see in [Discord](https://discord.gg/kzJC9fA7) +to ask if there is a workaround, or anyone else is interested in +porting your requirement, adding a reaction to an issue offers +awareness on what to implement or to get higher priority, remember that +it's possible to bounce back to Flow(f4) mode if needed. []($section.id('enhancing')) ## Enhancing hx mode @@ -36,29 +41,31 @@ if needed. This is a programmer's editor, you are more than welcome to enhance to suit your needs that maybe coincide with others. -Please take a look at [architecture](/docs/architecture) and +Take a look at [architecture](/docs/architecture) and [contributing](/docs/contributing) for an overview and the mechanics -of getting your changes into Flow. +of getting your changes into flow. hx mode is modal kind, the same as vim mode, and the file that has the -particular work to make it real is in `src/tui/mode/helix.zig`, adding +particular work to make it real is `src/tui/mode/helix.zig`, adding a `command` and the corresponding `meta` is what is required. [More on commands](/docs/architecture/command). []($section.id('pickers')) ### Pickers -Flow hx mode offers most of the picker types equivalents with `panels` -and [palettes](/docs/architecture/palette). Example of panels are -the `g` `r` (go to reference from lsp) and `space` `/` (a.k.a find in -files). Examples of `palettes` are `space` `b` to pick a buffer or +Flow hx mode offers most of the Helix pickers functionalities with +`panels` and [palettes](/docs/architecture/palette). Example of panels +are the `g` `r` (go to reference from lsp) and `space` `/` (a.k.a find +in files). Examples of `palettes` are `space` `b` to pick a buffer or `space` `f` to open a file in your project. Panels open below the editor while palettes open overlapping the working area. -One medium sized project is to create a widget that has one input -widget with two panels, on the left, the list of options and, on the -right, the preview of the selected option and offer various keybindings -to manipulate the objects inside both panels with filtering. +One medium sized project is to create a **Helix picker** widget that +has one input widget with two panels, on the left, the list of options +and, on the right, the preview of the selected option. The input +widget reacts to various keybindings to manipulate the objects inside +both panels with filtering. `src/tui/mode/overlay/palette.zig` +implements much of the required functionality. []($section.id('next')) ## Next steps @@ -66,11 +73,10 @@ to manipulate the objects inside both panels with filtering. Said all of this, it's possible to start contributing via pull requesting [keybinds](/docs/architecture/keybind), [commands](/docs/architecture/command), -[palettes](/docs/architecture/palette), or the special widget -mentioned previously. +[palettes](/docs/architecture/palette), or the **hx picker**. More about the [architecture](/docs/architecture) or jump to [contribution guidelines](/docs/contributing). Join the [#helix-mode channel](https://discord.gg/sxdejrAA) and get in -touch with other hx users. \ No newline at end of file +touch with other hx mode and helix interested users.