diff --git a/content/docs/architecture/command.smd b/content/docs/architecture/command.smd index 0ec4e4d..aaebabd 100644 --- a/content/docs/architecture/command.smd +++ b/content/docs/architecture/command.smd @@ -15,8 +15,7 @@ present in `editor`, `tui`, `mode` and `minimodes`, it's possible to find commands in other places, which will become evident when the need arises. -[]($section.id('notes')) -## Previous notes +## Prev[ious notes]($section.id('notes')) Note: Flow is programmed with [zig](https://ziglang.org/), if you are familiar with C, C++, Rust, there are differences and reasonings that @@ -36,8 +35,7 @@ Maybe there is a [shell command invoked](/docs/architecture/keybind#shell) with a keybinding that can help in the task you are aiming at before developing flow itself. -[]($section.id('creating')) -## Understanding and creating commands +## [Understanding and creating commands]($section.id('creating')) A command is a function with a type like @@ -61,8 +59,7 @@ constitutes a repetition parameter, targeting vim, emacs and helix modes. As you dig in, there might be particularities on the parameters accepted for a given command. -[]($section.id('calling')) -## Invoking another command +## [Invoking another command]($section.id('calling')) Commands can be bound to mnemonics in modes by convention. For example, in Vim Mode `vim.zig`, `q` corresponds to (quit), the most famous one. @@ -79,8 +76,7 @@ type, given that this command is defined in `vim.zig` which is calling the `quit` command defined in `editor.zig`. `cmd` takes care of routing and finding the command wherever it is defined. -[]($section.id('tldr')) -## Chaining commands +## [Chaining commands]($section.id('tldr')) Chaining commands is also common, and, by the way, swift. This is a sample of applying first `save_file` command and then, the command @@ -99,8 +95,7 @@ sent to commands vary for each command. Sometimes [keybinding](/docs/architecture/keybind) is enough to accomplish a compound of already present commands. -[]($section.id('command_arguments')) -### Sending parameters to commands +### [Sending parameters to commands]($section.id('command_arguments')) `goto_line` (in the case of vim and helix mode, you first type the number and then the action, `gg`) is a command that exemplifies @@ -146,8 +141,7 @@ A deeper explanation of the rules about parameter passing is exposed in that parameters can be sent not only to commands, but other broader use cases. -[]($section.id('deepen')) -## Code organization +## [Code organization]($section.id('deepen')) Is common to define private functions in a given module meant to be invoked from commands. As usual, reusing code with functions @@ -164,8 +158,7 @@ pub fn select_to_char_left_helix(_: *void, ctx: Ctx) Result { } ``` -[]($section.id('next')) -## Next steps +## [Next steps]($section.id('next')) [Minimodes](/docs/architecture/minimode) pass arguments to the editor, if you wonder how to go beyond the current buffer window, when there diff --git a/content/docs/architecture/index.smd b/content/docs/architecture/index.smd index c76e1a7..fc55c36 100644 --- a/content/docs/architecture/index.smd +++ b/content/docs/architecture/index.smd @@ -22,8 +22,7 @@ in deepwiki. Do not hesitate to ask in the channels and [open a PR](https://github.com/neurocyte/flow-website/pulls) to improve anything. -[]($section.id("internals")) -## Internals +## [Internals]($section.id("internals")) The foundational unit is the `Buffer` that holds the document in memory; there might be various opened files, each one loaded in a buffer. @@ -41,8 +40,7 @@ hierarchy, interact with lsp and git. When flow is opened, only one active project is loaded in the current session. The `Project Manager` offers services around the set of projects. -[]($section.id("commands")) -## Editor commands and modes +## [Editor commands and modes]($section.id("commands")) When a buffer is active, it has an Editor attached to it; an editor might have associated tree-sitter support, @@ -58,8 +56,7 @@ possible to create a nano mode with just keybindings. In the other hand, `Vim` and [Helix](/docs/mode/helix) modes have particular definitions for commands that interact with the buffers, being modal editors. -[]($section.id("tui")) -## Text user interface +## [Text user interface]($section.id("tui")) `Tui` governs it all offering support for [palettes](/docs/architecture/palette) that are known in other @@ -71,15 +68,14 @@ that receive more keypresses to offer additional functionality, such as finding in files, finding in the current buffer, open files and replacing a character. -[]($section.id("oses")) -## Operating systems and UI + +## [Operating systems and UI]($section.id("oses")) [libvaxis](https://github.com/rockorager/libvaxis) is in charge of rendering the text and all the interface in Linux, MacOS, FreeBSD, and Android via Termux, while in Windows there is an special GUI. -[]($section.id("thespian")) -## Communication between components +## [Communication between components]($section.id("thespian")) [Thespian](https://github.com/neurocyte/thespian) is in charge of processes synchronization and allows sending @@ -93,22 +89,19 @@ operations they perform, integration with git and running a `shell` command via a `task` all are coordinated thanks to the infrastructure that Thespian provides. -[]($section.id("languages")) -## Programming languages support +## [Programming languages support]($section.id("languages")) There are plenty of programming languages that use tree-sitter via [flow-syntax](https://github.com/neurocyte/flow-syntax) and whose language servers and formatters are configured via `file_type_lsp`. Currently one Language Server is supported for each language. -[]($section.id("facilities")) -## Facilities +## [Facilities]($section.id("facilities")) The clipboard is used for copy, paste operations and there is also support to use the system clipboard, copying and pasting to/from it. -[]($section.id("logging")) -### Logging support +### [Logging support]($section.id("logging")) Logging support offers various levels to give feedback for several actions that ease developing Flow itself and also are used to offer @@ -136,8 +129,7 @@ Log something logger.print("{} unsaved buffer(s) remaining", .{remaining}); ``` -[]($section.id("show_input")) -### View key presses +### [View key presses]($section.id("show_input")) There are situations when you press some keys without the expected behavior happening, to review if flow is getting the keys, the @@ -146,8 +138,7 @@ executing the [desired command](/docs/architecture/command), or maybe your desktop environment or something else is capturing them, you will want to invoke flow with the option `--show-input`. -[]($section.id("next")) -## Next steps +## [Next steps]($section.id("next")) * [Configure some keybinds](/docs/architecture/keybind) * [Guidelines for contributions](/docs/contributing) diff --git a/content/docs/architecture/inner_data_exchange.smd b/content/docs/architecture/inner_data_exchange.smd index 45a94f8..78b505d 100644 --- a/content/docs/architecture/inner_data_exchange.smd +++ b/content/docs/architecture/inner_data_exchange.smd @@ -25,8 +25,7 @@ management is provided by This chapter describes the mechanisms that flow has to pass arguments between components. -[]($section.id('libraries')) -## Library usage +## [Library usage]($section.id('libraries')) * The Thespian library sends and receives `thespian.message` values, which are strongly typed, but schema free CBOR encoded structures. @@ -61,9 +60,7 @@ data, more samples on using cbor can be seen in For example, when interacting with the clipboard, the messages sent are multiple chunks of information, - -[]($section.id('scoping')) -## Buffer scoping +## [Buffer scoping]($section.id('scoping')) CBOR structures are mostly stored in a way that avoids allocation entirely. This is really fast, but requires that you always know where @@ -105,16 +102,14 @@ came from. original CBOR data and will be invalidated implicitly when the CBOR buffer they came from is invalidated/overwritten. -[]($section.id('next')) -## Next steps +## [Next steps]($section.id('next')) * [Commands](/docs/architecture/command) * [Minimodes](/docs/architecture/minimode) * [Architecture](/docs/architecture) -[]($section.id('more')) -## More information +## [More information]($section.id('more')) * [Deepwiki on cbor](https://deepwiki.com/neurocyte/cbor) * [Samples of cbor usage](https://github.com/neurocyte/cbor/blob/master/test/tests.zig) -* [Deepwiki on thespian](https://deepwiki.com/neurocyte/thespian) \ No newline at end of file +* [Deepwiki on thespian](https://deepwiki.com/neurocyte/thespian) diff --git a/content/docs/architecture/keybind.smd b/content/docs/architecture/keybind.smd index f460aee..9ee948b 100644 --- a/content/docs/architecture/keybind.smd +++ b/content/docs/architecture/keybind.smd @@ -30,8 +30,7 @@ and the different [imodes](#hierarchy) present. Command palette can also be reached left clicking on the current mode in the status bar. -[]($section.id('tldr')) -## ;TLDR; +## [;TLDR;]($section.id('tldr')) Once you open the corresponding json file, locate inside the [imode](#hierarchy)(internal mode) that will accept the key or @@ -46,16 +45,14 @@ like in To avoid screwing up the combinations, and putting flow in an unusable state derived from a wrong mapping of key combinations, read on. -[]($section.id('defaults')) -## Resetting keys to factory defaults +## [Resetting keys to factory defaults]($section.id('defaults')) User configured keybindings are stored in Flow's configuration directory under `keys/mode.json` where mode can be `flow`, `emacs`, `vim`, `helix` or customized ones. Removing the keys directory or the particular mode file can take you out from a broken state. -[]($section.id('modes')) -## Keybinds for each mode +## [Keybinds for each mode]($section.id('modes')) Keybinds are edited per mode, and other modes inherit what is defined in your `flow.json` keybindings. Each mode override keybindings of its @@ -66,8 +63,7 @@ flow, and the default ones defined for emacs mode. [introducing keybindings](/devlog/2024#2024-12-05T20:55:00) showcases how to get to edit keybindings. -[]($section.id('hierarchy')) -## Keybindings hierarchy +## [Keybindings hierarchy]($section.id('hierarchy')) Some terminology @@ -134,8 +130,7 @@ and other modes inherit from it. Each mode inherits, extends and overrides actions and define their internal imodes extending as required each minimode. -[]($section.id('adding')) -## Adding a Keybinding +## [Adding a Keybinding]($section.id('adding')) The most basic case to map a keybind to a command was covered in [TLDR](#tldr) which used the combination of three keys pressed @@ -146,8 +141,7 @@ A common use case is to add a keybinding to invoke an already existing command and chain it to another, making Flow more suited to your own needs. -[]($section.id('shell')) -## Running shell commands +## [Running shell commands]($section.id('shell')) For example, `f5` by default is used to run `zig build test` outputting its results to a *scratch buffer* called `test`. @@ -190,8 +184,7 @@ want to remap `f5` to a different shell command. Observe [tasks running](/devlog/2025#2025-01-26T22:11:00) and maybe consider using more keybindings or running tasks for your projects. -[]($section.id('next')) -## Next steps +## [Next steps]($section.id('next')) If you realized that there is a handy combination that others can benefit from or that a mode lacks the combination and it might be diff --git a/content/docs/architecture/minimode.smd b/content/docs/architecture/minimode.smd index c4e0b92..5da2305 100644 --- a/content/docs/architecture/minimode.smd +++ b/content/docs/architecture/minimode.smd @@ -16,8 +16,7 @@ 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 +## [Anatomy of minimodes]($section.id("anatomy")) To create a minimode it's needed: @@ -25,8 +24,7 @@ To create a minimode it's needed: * An Action mapping * A Minimode definition -[]($section.id("keybind")) -### Keybinding +### [Keybinding]($section.id("keybind")) When a key or a keystroke(set of keys) are pressed, the associated minimode gets activated and will start to capture the key/strokes @@ -35,8 +33,7 @@ the minimode. Head to `src/keybind/builtin/flow.json`(flow keybinds) and look for `mini_find`, where you will know which specific actions are triggered by the keybindings of the `find` minimode. -[]($section.id("mapping")) -### Action mapping +### [Action mapping]($section.id("mapping")) Actions executed by each minimode are stored one per file under `src/tui/mode/mini/`. The command that opens the door to the minimode @@ -46,8 +43,7 @@ when needed. Look for `mini` inside `tui.zig` to find out which minimodes are present and where to look, to learn how each minimode does its own task. -[]($section.id("definition")) -### Minimode definition +### [Minimode definition]($section.id("definition")) Possibly the simplest minimode that does not require defining a particular widget is the `replace` minimode, used in @@ -99,16 +95,14 @@ All the keys were handled and managed by the default "invisible" widget that processes the keys for the minimode. And there is room for custom widgets. -[]($section.id("custom_widgets")) -## A custom widget +## [A custom widget]($section.id("custom_widgets")) When there is a need for an specialized widget, it's possible to define one, for example, the `file_browser` is used to load and save files, and `numeric_input` is used to set the tab width for example(look for it in the command palette `:`). -[]($section.id("next")) -## Next steps +## [Next steps]($section.id("next")) * Create [palettes](/docs/architecture/palette) * Review [commands](/docs/architecture/command) diff --git a/content/docs/architecture/palette.smd b/content/docs/architecture/palette.smd index 310f69d..193f75b 100644 --- a/content/docs/architecture/palette.smd +++ b/content/docs/architecture/palette.smd @@ -30,8 +30,7 @@ To get the most of this section, it's recommended to have read about [commands](/docs/architecture/command), and optionally, [minimodes](/docs/architecture/minimode). -[]($section.id("anatomy")) -## Defining the palette +## [Defining the palette]($section.id("anatomy")) Palettes are under `tui/overlay` and use the facilities offered by `palette.zig` to perform all the operations. @@ -45,8 +44,7 @@ options to execute an action on the given selection. To maintain as readable as possible the code and thus extensible, the data to be used should be prepared previously. -[]($section.id("basic")) -### Fields +### [Fields]($section.id("basic")) Basic fields that give hints to the user and need to be set are: @@ -57,8 +55,7 @@ pub const description = "clipboard"; pub const icon = " "; ``` -[]($section.id("entries")) -### Defining the list of elements in the palette +### [Defining the list of elements in the palette]($section.id("entries")) `load_entries` is in charge of populating the visible entries, each one with an index. @@ -87,8 +84,7 @@ try palette.menu.add_item_with_handler(value, select); Which will apply the `select` function when the value is selected. -[]($section.id("select")) -### Acting on selection +### [Acting on selection]($section.id("select")) When the selection happens, it is time to invoke the command with the selection making sure to close the palette. Those actions will be @@ -102,8 +98,7 @@ Other common operations in the palettes can be inspected looking at the source code of the palettes, all of them import `palette.zig`. Once the palette is ready, it's time to make the palette available as a command. -[]($section.id("register")) -## Registering the palette +## [Registering the palette]($section.id("register")) Commands that open the palette are defined in `tui.zig` in a similar way it is done with [minimodes](/docs/architecture/minimode). We have got @@ -113,9 +108,9 @@ you covered if in doubt about To view a complete implementation of a palette, take a look at [clipboard history palette commit](https://github.com/neurocyte/flow/commit/634a18cb5685a3c3fcfc08301306e628d33c3256) -[]($section.id("next")) -## Next steps +## [Next steps]($section.id("next")) * [Minimodes](/docs/architecture/minimode) * [On commands](/docs/architecture/command) -* [Architecture](/docs/architecture) \ No newline at end of file +* [Exchanging messages](/docs/architecture/inner_data_exchange) +* [Architecture](/docs/architecture) diff --git a/content/docs/contributing.smd b/content/docs/contributing.smd index 994a448..ae35a82 100644 --- a/content/docs/contributing.smd +++ b/content/docs/contributing.smd @@ -1,6 +1,6 @@ --- .title = "Contributing", -.date = @date("2025-07-06T00:00:00"), +.date = @date("2025-11-06T00:00:00"), .author = "Igor Támara", .layout = "tutorial.shtml", .draft = false, @@ -9,8 +9,7 @@ } --- -[]($section.id("request")) -## Asking for a feature +## [Asking for a feature]($section.id("request")) Please [open an issue](https://github.com/neurocyte/flow/issues) that explains what is the requirement, being as descriptive as @@ -21,8 +20,7 @@ more information. At the end, the issues in github have more chance to get developed, given that there are plenty of things to do for this kind of software. -[]($section.id("issues")) -## Reporting a problem +## [Reporting a problem]($section.id("issues")) If you discover a problem, or unexpected behaviour, feel free to join [Discord](https://discord.com/invite/4wvteUPphx) to check if there is @@ -41,8 +39,7 @@ Issues later on are tagged with proposed version to solve them, in case of low hanging fruit, it's possible that it can be solved pretty quick. -[]($section.id("showcase")) -## Help others and share your workflows +## [Help others and share your workflows]($section.id("showcase")) We are happy when you [share your workflows](https://discord.gg/XeYatDhh) or when someone asks something and gets a helpful answer, for example, a @@ -55,8 +52,8 @@ making blog entries and sharing with others what you can build or achieve with flow; battle testing flow on daily basis helps its improvement and bring ideas from other places too. -[]($section.id("developing")) -## Developing + +## [Developing]($section.id("developing")) [Flow Control](https://flow-control.dev/) is programmed with [zig](https://ziglang.org/). @@ -76,8 +73,7 @@ agreements or find guidance. This [summary](/docs/architecture) can help on getting started to follow the codebase. -[]($section.id("coding_style")) -### Coding style +### [Coding style]($section.id("coding_style")) Please follow what you see in the source code for functions, Structs, variables, const names, etc... Functions have descriptive names to @@ -90,8 +86,8 @@ inaccurate in this doc or others, do open an issue or jump to [Discord](https://discord.com/invite/4wvteUPphx) and comment, it's valid to [improve too](https://github.com/neurocyte/flow-website/tree/master/content/docs/contributing.smd"). -[]($section.id("commits")) -### Commit comments + +### [Commit comments]($section.id("commits")) It's better to use commits for different purposes, even if they look small and there is a temptation to include on the same new code, fixes @@ -110,8 +106,8 @@ clearer for future readers and committers. * `fix:` When something changed to a more expected behaviour. * `build`: the commit doesn't change code at all. -[]($section.id("testing")) -### Testing + +### [Testing]($section.id("testing")) It's possible that the test set grows as the project evolves, given that the amount of relationships among components increase the @@ -119,8 +115,7 @@ opportunity to generate regressions. If you are new to zig a good place to start to learn about the codebase is [adding some tests](/docs/testing) -[]($section.id("resources")) -## Resources +## [Resources]($section.id("resources")) * [nerd fonts cheatsheet](https://www.nerdfonts.com/cheat-sheet): When icons are needed, you can look for them. @@ -129,8 +124,7 @@ to trace some messages. * [showing key-presses](/docs/architecture#show_input): When the keyboard don't seem to work. -[]($section.id("next")) -## Next steps +## [Next steps]($section.id("next")) * [Join Discord](https://discord.com/invite/4wvteUPphx) * [Fill an issue](https://github.com/neurocyte/flow/issues) diff --git a/content/docs/testing.smd b/content/docs/testing.smd index 8684dd2..f33df39 100644 --- a/content/docs/testing.smd +++ b/content/docs/testing.smd @@ -24,8 +24,7 @@ To work with tests you will need to: Flow tests are placed in the directory `test`. -[]($section.id("running_tests")) -## Running the tests +## [Running the tests]($section.id("running_tests")) To run the full set of tests, inside flow, use `f5`, which runs a task that invokes: @@ -37,8 +36,7 @@ zig build test it will work if flow was invoked from the project root, which is the same place that you would normally run the tests when on the terminal. -[]($section.id("running_a_test")) -### Run a particular test +### [Run a particular test]($section.id("running_a_test")) To run an specific test use `Dtest-filter` option with the name of your test, i.e., for the test called **test_block_name** use: @@ -47,8 +45,7 @@ test, i.e., for the test called **test_block_name** use: zig build test -Dtest-filter="test_block_name" ``` -[]($section.id("first_test")) -## Adding tests +## [Adding tests]($section.id("first_test")) Tests are needed when: @@ -68,8 +65,7 @@ additional functions to make the tests readable and extendable though. public functions are straightforward tested, while there are some conventions for testing private functions. -[]($section.id("private_functions_testing")) -### Testing private functions +### [Testing private functions]($section.id("private_functions_testing")) Some internal logic of a module can be tested without the need to be exposed to other modules. @@ -111,8 +107,7 @@ try helix.test_internal.move_cursor_long_word_right_end(root, cursor, the_metric In case there is need of a new test file for concern separation, continue to the next section. -[]($section.id("new_test_file")) -## Adding a new test file +## [Adding a new test file]($section.id("new_test_file")) Three steps are required for adding a new test file: @@ -121,8 +116,7 @@ Three steps are required for adding a new test file: 1. Optionally, make available a module to the build system for your particular test -[]($section.id("create_test_file")) -### Create the test file +### [Create the test file]($section.id("create_test_file")) Place your test file under `test` directory, the name should be prefixed with `tests_`. @@ -130,8 +124,7 @@ with `tests_`. For the rest of this section we will use as a sample `tests_project_manager.zig`. -[]($section.id("linking_tests")) -### Include the test file +### [Include the test file]($section.id("linking_tests")) Tests files are linked via `test/tests.zig`, import your new test_file alphabetically as in our sample: @@ -140,8 +133,7 @@ alphabetically as in our sample: pub const project_manager = @import("tests_project_manager.zig"); ``` -[]($section.id("import_in_build_zig")) -### Import required modules when building tests +### [Import required modules when building tests]($section.id("import_in_build_zig")) In `build.zig` import the required module under `tests.root_module`, for the current example: @@ -153,21 +145,16 @@ tests.root_module.addImport("project_manager", project_manager_mod); [Sample](https://github.com/neurocyte/flow/commit/e053a0dcf4b4c93f1ce1fe6d14a3c04e886d393c) of adding a new test file for project manager. -[]($section.id("faq")) -## FAQ on tests +## [FAQ on tests]($section.id("faq")) -[]($section.id("import_editor")) -### I need to test something that requires importing the editor ¿What -do I do? +### [I need to test something that requires importing the editor ¿What do I do?]($section.id("import_editor")) There are two paths from here: 1. Refactor your code to test the lower level functions 1. Extend the tests to automate via external tools - -[]($section.id("lower_level")) -### Refactor to test lower level functions +### [Refactor to test lower level functions]($section.id("lower_level")) Refactor the functions involved in the functionality to make them not rely directly with editor and other higher level components, and @@ -194,8 +181,7 @@ The group of functions `beyond_eol` can be seen in and whose tests are [here](https://github.com/neurocyte/flow/pull/330/commits/38a08aed49f4fbba18aab9ccbd3c8b9758414221). -[]($section.id("end_to_end")) -### Use additional tools to test a running flow session +### [Use additional tools to test a running flow session]($section.id("end_to_end")) Use additional tools to invoke the built editor and send keys to it, modify a file and then compare the initial contents of the file @@ -204,8 +190,7 @@ and the resulting contents of your file and the expected ones. If in doubt about how to do something, [please ask](https://discord.com/invite/4wvteUPphx). -[]($section.id("next")) -## Next steps +## [Next steps]($section.id("next")) * [How to contribute](/docs/contributing) * [Personalizing keybindings](/docs/architecture/keybind)