Improved internal links and adopt zig highlight

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)

content/docs/architecture/index.smd

@@ -0,0 +1,156 @@
+---
+.title = "Architecture",
+.date = @date("2025-07-06T00:00:00"),
+.author = "Igor Támara",
+.layout = "tutorial.shtml",
+.draft = false,
+.custom = {
+  .githubedit = "/docs/architecture.smd",
+}
+---
+
+This document describes in a general way, concepts that help to
+understand how the code is organized and where to look at when starting
+to contribute developing Flow Control.  Make sure you have read
+first [help.md](https://github.com/neurocyte/flow/blob/master/help.md)
+and use the editor at least in flow mode. We recommend reading the
+[deepwiki description](https://deepwiki.com/neurocyte/flow) for a more
+in depth documentation and joining
+[Discord](https://discord.com/invite/4wvteUPphx) to ask from the
+simplest.  If something does not look accurate on this documentation or
+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
+
+The foundational unit is the `Buffer` that holds the document in memory;
+there might be various opened files, each one loaded in a buffer.
+A buffer can be ephemeral, meaning, it is not related to a file, that
+might be the product of a `Task` run.  Buffers are implementations of
+ropes that offer multiple services such as insert characters, load from
+file, write to file, load from string, return as string, tell if it has
+unsaved changes(dirty), among many others. A buffer can have multiple
+`Selections` and `Cursors` interacting with it. The `Buffer Manager`
+offers services around the set of buffers.
+
+A `Project` initially is the directory where flow is opened at, once
+opened, it starts processes to discover the files under the directory
+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
+
+When a buffer is active, it has an Editor
+attached to it; an editor might have associated tree-sitter support,
+given the file type detected, and offers common services that are aimed
+to be used by `Commands` to manipulate the contents of a buffer at a
+higher level, the selections, cursors, cursor selections `CurSel` and
+the `View`. [Commands](/docs/architecture/command) are used by `Modes`
+with [Keybindings](/docs/architecture/keybind). The main mode is Flow
+and the keybindings can be used to map to a mode built up entirely on
+solely calling already created commands. An example of a mode
+created by command composition is `Emacs` mode, for instance, it's
+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
+
+`Tui` governs it all offering support for
+[palettes](/docs/architecture/palette) that are known in other
+environments as pickers, as well as offering information through a
+set of `_views` (i.e. `logview`, `inputview`, `inspector_view`) and
+`status` (i.e. `tabs`, `clock`, `branch`, `linenum`), in the statusbar
+[minimodes](/docs/architecture/minimode) will be present too, those
+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
+
+[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
+
+[Thespian](https://github.com/neurocyte/thespian) is in charge of
+processes synchronization and allows sending
+[messages between different flow components](/docs/architecture/inner_data_exchange),
+for example, when a widget needs updating information from changing
+states of internal data and when components or external processes take
+time and need to return an answer, all this without blocking the user
+interface. Tree-sitter queries to highlight the current file of a
+particular language and LSPs usually take time by the nature of
+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
+
+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
+
+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 offers various levels to give feedback for several
+actions that ease developing Flow itself and also are used to offer
+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 log`
+
+```zig
+const log = @import("log");
+```
+
+Instantiate the logger, replacing prefix with something meaningful to
+differentiate from other logging messages.
+
+```zig
+const logger = log.logger("prefix");
+defer logger.deinit();
+```
+
+Log something
+
+```zig
+logger.print("{} unsaved buffer(s) remaining", .{remaining});
+```
+
+[]($section.id("show_input"))
+### View key presses
+
+There are situations when you press some keys without the expected
+behavior happening, to review if flow is getting the keys, the
+[keybindings are associated](/docs/architecture/keybind), and are
+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
+
+* [Configure some keybinds](/docs/architecture/keybind)
+* [Guidelines for contributions](/docs/contributing)
+* [Create your own commands](/docs/architecture/command)
+* [Take a peek on testing](/docs/testing)
+* [Back to docs](/docs)

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

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)

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