refactor: Better anchor linking for toc
This commit is contained in:
Igor Támara
parent
a239b2b5f2
commit
3b93f62ccd
8 changed files with 70 additions and 130 deletions
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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)
|
||||
|
|
|
|||
|
|
@ -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)
|
||||
* [Deepwiki on thespian](https://deepwiki.com/neurocyte/thespian)
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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)
|
||||
|
|
|
|||
|
|
@ -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)
|
||||
* [Exchanging messages](/docs/architecture/inner_data_exchange)
|
||||
* [Architecture](/docs/architecture)
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue