Add sections anchors

README.md

@@ -27,7 +27,7 @@ added.
 1. Update the file `contrib/symbolnerdfontmonolist.txt` adding the unicode
 2. Add the reference to assets/css/webfont.css
 3. Use it the same as layouts/templates/base.html navbar
-4. Update the fonts installing (uv pip install fonttools) with:
+4. Update the fonts(to install the tool `uv pip install fonttools`) with:
 
 ```python
 pyftsubset contrib/fonts/nerdfonts/SymbolsNerdFontMono-Regular.ttf --unicodes-file=contrib/symbolnerdfontmonolist.txt  --output-file=assets/fonts/SymbolsNerdFontMono-Regular.ttf
@@ -37,9 +37,27 @@ If the icon you want to use from nerdonfts is not present in contrib/fonts/nerdf
 get it from https://github.com/ryanoasis/nerd-fonts/releases/download/v3.4.0/NerdFontsSymbolsOnly.zip
 and update contrib to ease later needings.
 
+## Custom frontmatter
+
+Some [custom frontmatter](https://zine-ssg.io/docs/supermd/#frontmatter) fields are being used on the docs
+
+### githubedit (Optional)
+Directs to contribute editing this documentation. Used by `layout/tutorial.shtml`.
+
+```ziggy
+  .githubedit** = "/docs/testing.md",
+```
+
+### codepath (Optional)
+Links to relevant source code on the current doc. Used by `layout/tutorial.shtml`.
+
+```ziggy
+  .codepath ="test",
+```
+
 ## Resources
 
-* [Monospace Web Theme](https://owickstrom.github.io/the-monospace-web/)
 * [Zine](https://zine-ssg.io/docs/)
 * [Flow Control Editor](https://github.com/neurocyte/flow)
 * [NerdFonts](https://www.nerdfonts.com/cheat-sheet)
+* [Monospace Web Theme](https://owickstrom.github.io/the-monospace-web/)

assets/css/index.css

@@ -485,3 +485,10 @@ label input {
 .debug-toggle-label {
   text-align: right;
 }
+
+div nav {
+    text-align: right;
+}
+div.tutnav p {
+    text-align: center;
+}

assets/css/webfont.css

@@ -40,3 +40,9 @@
 .nf-fa-people_carry_box:before {
   content: "\eda2";
 }
+.nf-dev-zig:before {
+  content: "\e8ef";
+}
+.nf-fa-edit:before {
+  content: "\f044";
+}

content/docs/architecture.smd

@@ -4,7 +4,9 @@
 .author = "Igor Támara",
 .layout = "tutorial.shtml",
 .draft = false,
-.custom = { .githubedit = "https://github.com/neurocyte/flow-website/tree/master/content/docs/architecture.smd"},
+.custom = {
+  .githubedit = "/docs/architecture.smd",
+}
 ---
 
 This document describes in a general way, concepts that help to
@@ -16,9 +18,11 @@ and use the editor at least in flow mode. We recommend reading the
 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 to
+in deepwiki. Do not hesitate to ask in the channels and
-improve anything.
+[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;
@@ -37,6 +41,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
 
 When a buffer is active, it has an `Editor` attached to it; an editor
@@ -52,6 +57,7 @@ create a nano mode with just keybindings. In the other hand, `Vim` and
 `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` that are known
@@ -60,22 +66,29 @@ through a set of `_views` (i.e. `logview`, `inputview`,
 `inspector_view`) and `status` (i.e. `tabs`, `clock`, `branch`,
 `linenum`).
 
+[]($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,
-while in Windows there is an special GUI.
+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, for example, when a widget needs
 updating information from changing states of internal data and
-when components or external processes take time. For example,
+when components or external processes take time and need to return
-tree-sitter queries to highlight the current file of a particular
+an answer, all this without blocking the user interface. Tree-sitter
-language, LSPs, git, running a `shell` command via a `task`.
+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
@@ -83,14 +96,52 @@ There are plenty of programming languages that use tree-sitter via
 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.
 
-Logging support offers various levels to give feedback for various
+[]($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`.
+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 import
 
-We have some [contribution guidelines](/docs/contributing).
+```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, or your desktop
+environment or something else are capturing them, you will want to
+invoke flow with the option `--show-input`.
+
+[]($section.id("next"))
+## Next steps
+
+* [Guidelines for contributions](/docs/contributing)
+* [Take a peek on testing](/docs/testing)
+* [Back to docs](/docs)

content/docs/contributing.smd

@@ -4,9 +4,12 @@
 .author = "Igor Támara",
 .layout = "tutorial.shtml",
 .draft = false,
-.custom = { .githubedit = "https://github.com/neurocyte/flow-website/tree/master/content/docs/contributing.smd"},
+.custom = {
+  .githubedit = "/docs/contributing.smd",
+}
 ---
 
+[]($section.id("request"))
 ## Asking for a feature
 
 Please [open an issue](https://github.com/neurocyte/flow/issues) that
@@ -18,13 +21,14 @@ 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
 
-If you discover a problem, or unexpected behaviour, feel free to
+If you discover a problem, or unexpected behaviour, feel free to join
-join [Discord](https://discord.com/invite/4wvteUPphx) to check
+[Discord](https://discord.com/invite/4wvteUPphx) to check if there is
-if there is a simple way to overcome the inconvenience or to get
+a simple way to overcome the inconvenience or to get some guidance.
-some guidance.  [Reporting a bug](https://github.com/neurocyte/flow/issues)
+[Reporting a bug](https://github.com/neurocyte/flow/issues) is a good
-is a good way to contribute. When reporting one, it should contain:
+way to contribute. When reporting one, it should contain:
 
 * Flow version. You get it with `flow --version`
 * What you were doing, if possible, step by step to reproduce it
@@ -39,6 +43,7 @@ quick.
 
 Spreading the word is another way to contribute to Flow Code growth.
 
+[]($section.id("developing"))
 ## Developing
 
 [Flow Control](https://flow-control.dev/) is programmed with
@@ -58,6 +63,7 @@ agreements or find guidance.
 This [summary](/docs/architecture) can help on getting started to
 follow the codebase.
 
+[]($section.id("coding_style"))
 ### Coding style
 
 Please follow what you see in the source code for functions, Structs,
@@ -65,39 +71,55 @@ variables, const names, etc...  Functions have descriptive names to
 use less time adding and maintaining comments to communicate the
 purpose and intent. Don't worry about commenting each function, module
 or parameter, there are automated tools that are currently helping
-with this, take a peek on [deepwiki](https://deepwiki.com/neurocyte/flow);
+with this, take a peek on
-if you find something inaccurate in this doc or others, do open an
+[deepwiki](https://deepwiki.com/neurocyte/flow); if you find something
-issue or jump in [Discord](https://discord.com/invite/4wvteUPphx)
+inaccurate in this doc or others, do open an issue or jump to
-and comment, it's valid to
+[Discord](https://discord.com/invite/4wvteUPphx) and comment, it's
-[improve too](https://github.com/neurocyte/flow-website/tree/master/content/docs/contributing.smd").
+valid to [improve too](https://github.com/neurocyte/flow-website/tree/master/content/docs/contributing.smd").
 
+[]($section.id("commits"))
 ### Commit comments
 
-It's better to use commits for different purposes, even if they look small and
+It's better to use commits for different purposes, even if they look
-there is a temptation to include on the same new code, fixes and refactors. Making
+small and there is a temptation to include on the same new code, fixes
-concise and self contained commits make review easier and future fixes possible,
+and refactors. Making concise and self contained commits make review
+easier and future fixes possible,
 in case of need.
 
-Use these prefixes as much as you can, doing so helps when identifying the features
+Use these prefixes as much as you can, doing so helps when identifying
-and eases the process of letting others know about what's new, fixed and help
+the features and eases the process of letting others know about what's
-communicate better when releasing.
+new, fixed and help communicate better when releasing.
 
-* `feat:` when there is a new feature, if specific to a mode, please use
+* `feat:` when there is a new feature, if specific to a mode, please
-`feat: [mode]`.
+use `feat: [mode]`.
-* `refactor`: when reorganizing code, usually when you make something clearer
+* `refactor`: when reorganizing code, usually when you make something
-for future readers and commiters.
+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
 
 It's possible that the test set grows as the project evolves, given
 that the amount of relationships among components increase the
-opportunity to generate regressions.
+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)
 
-## Getting in touch.
+[]($section.id("resources"))
+## Resources
 
-[Discord](https://discord.com/invite/4wvteUPphx) and
+* [nerd fonts cheatsheet](https://www.nerdfonts.com/cheat-sheet): When
-[Github issues](https://github.com/neurocyte/flow/issues) are the
+icons are needed, you can look for them.
-main channels to do so.
+* [logging](/docs/architecture#logging): When developing flow and need
+to trace some messages.
+* [showing key-presses](/docs/architecture#show_input): When the keyboard
+don't seem to work.
 
+[]($section.id("next"))
+## Next steps
+
+* [Join Discord](https://discord.com/invite/4wvteUPphx)
+* [Fill an issue](https://github.com/neurocyte/flow/issues)
+* [Add some tests](/docs/testing)
+* [Back to architecture](/docs/architecture)

content/docs/testing.smd

@@ -0,0 +1,191 @@
+---
+.title = "Testing",
+.date = @date("2025-10-20T00:00:00"),
+.author = "Igor Támara",
+.layout = "tutorial.shtml",
+.draft = false,
+.custom = {
+  .githubedit = "/docs/testing.md",
+  .codepath ="test",
+},
+---
+Currently flow tests are aimed to work as unit tests, it always is a good
+idea to review the
+[zig tests documentation](https://ziglang.org/documentation/master/#Zig-Test)
+and also an
+[introduction to testing](https://pedropark99.github.io/zig-book/Chapters/03-unittests.html).
+
+To work with tests you will need to:
+
+* [Clone](https://github.com/neurocyte/flow) the repository
+* Have [zig installed](https://ziglang.org/download/). Highly recommended to use
+[anyzig](https://github.com/marler8997/anyzig)
+
+Flow tests are placed in the directory `test`.
+
+[]($section.id("running_tests"))
+## Running the tests
+
+To run the full set of tests, inside flow, use `F5`, which runs a task that
+invokes:
+
+```
+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
+
+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:
+
+```
+zig build test -Dtest-filter="test_block_name"
+```
+
+[]($section.id("first_test"))
+## Adding tests
+
+Tests are needed when:
+
+* There is some logic that might be difficult to understand given it's
+nature, for example, when there are a lot of branching
+* You find something that could be changed in the future affecting the
+current behavior
+* A bug is fixed
+* A defined behavior could be thought different, for example when in a mode,
+it was defined that something might diverge from other programs.
+
+Tests are placed under `test` directory.  Add your test in the file that
+exercises the functionality and makes proof of it behaving as expected.
+Maintain the logic test as simple as possible. It's possible to add
+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
+
+Some internal logic of a module can be tested without the need to be
+exposed to other modules.
+
+In such cases the module that has the logic should provide a pub
+`test_internal`, by convention, exposing the target functionalities to
+be tested.
+
+For example in `src/tui/mode/helix.zig`, `test_internal` exposes the private
+function
+
+```zig
+fn move_cursor_long_word_right_end(root: Buffer.Root, cursor: *Cursor, metrics: Buffer.Metrics) error{Stop}!void
+```
+
+with
+
+```zig
+pub const test_internal = struct {
+    pub const move_cursor_long_word_right = private.move_cursor_long_word_right;
+.
+.
+.
+};
+```
+
+And in `test/tests_helix.zig`, helix is imported as
+
+```zig
+const helix = @import("tui").exports.mode.helix;
+```
+
+Later on using the function `move_cursor_long_word_right` as
+
+```zig
+try helix.test_internal.move_cursor_long_word_right_end(root, cursor, the_metrics);
+```
+
+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
+
+Three steps are required for adding a new test file:
+
+1. Create a new test file
+1. Include the test to the set of tests
+1. Optionally, make available a module to the build system
+for your particular test
+
+[]($section.id("create_test_file"))
+### Create the test file
+
+Place your test file under `test` directory, the name should be prefixed
+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
+
+Tests files are linked via `test/tests.zig`, import your new test_file
+alphabetically as in our sample:
+
+```zig
+pub const project_manager = @import("tests_project_manager.zig");
+```
+
+[]($section.id("import_in_build_zig"))
+### Import required modules when building tests
+
+In `build.zig` import the required module under `tests.root_module`, for
+the current example:
+
+```zig
+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
+
+[]($section.id("import_editor"))
+### I need to test something that requires importing the editor ¿What do I do?
+
+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 the functions involved in the functionality to make them
+not rely directly with editor and other higher level components, and
+test the lower level ones.
+
+An example of this can be seen in commands
+
+[]($section.id("end_to_end"))
+### Use additional tools to test a running flow session
+
+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
+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
+
+* [How to contribute](/docs/contributing)
+* [User Documentation](/docs)
+* [Other Flow topics](/docs/architecture)

contrib/symbolnerdfontmonolist.txt

@@ -4,3 +4,5 @@ U+eadc
 U+f409
 U+e889
 U+eda4
+U+e8ef
+U+f044

layouts/tutorial.shtml

@@ -2,10 +2,22 @@
 <head id="head">
 </head>
 <body id="body">
-  <h1 :text="$page.title"></h1>
+	<h1 :text="$page.title"></h1>
-  <div :html="$page.content()"></div>
+	<div :html="$page.content()"></div>
-  <hr>
+
-  <p>If you find anything that could be better, because it does not reflect
+	<div>
-  what happens with flow or can be explain better, don't hesitate to
+		<nav id="menu" class="nav">
-  <a href="$page.custom.getOr('githubedit', 'https://github.com/neurocyte/flow-website/')">improve me</a>.</p>
+			<ctx about="$site.page('')"><a href="$ctx.about.link()"><i class="nf nf-fa-terminal"></i></a> <a href="$ctx.about.link()">home</a></ctx>
+			<ctx :if="$site.page('devlog').subpages().first?()"><a href="$if.link()"><i class="nf nf-dev-readthedocs"></i></a> <a href="$if.link()">devlog</a></ctx>
+		<ctx about="$site.page('community')"><a href="https://discord.com/invite/4wvteUPphx"><i class="nf nf-fa-people_carry_box"></i></a> <a href="https://discord.com/invite/4wvteUPphx">join</a></ctx>
+			<ctx :if="$page.custom.get?('codepath')"><a href="$page.custom.get('codepath').prefix('https://github.com/neurocyte/flow/tree/master/')"><i class="nf nf-dev-zig"></i></a> <a href="$page.custom.get('codepath').prefix('https://github.com/neurocyte/flow/tree/master/')">code</a></ctx>
+			<ctx :if="$page.custom.has('codepath').not()"><a href="https://github.com/neurocyte/flow"><i class="nf nf-dev-zig"></i></a> <a href="https://github.com/neurocyte/flow">code</a></ctx>
+			<ctx :if="$page.custom.has('githubedit')">
+		<a href="$page.custom.get('githubedit').prefix('https://github.com/neurocyte/flow-website/tree/master/content')"><i class="nf nf-fa-edit"></i></a> <a href="$page.custom.get('githubedit').prefix('https://github.com/neurocyte/flow-website/tree/master/content')">edit</a>
+			</ctx>
+			<ctx :if="$page.custom.has('githubedit').not()">
+			<a href="$page.custom.getOr('githubedit', 'https://github.com/neurocyte/flow-website/')"><i class="nf nf-fa-edit"></i></a> <a href="$page.custom.getOr('githubedit', 'https://github.com/neurocyte/flow-website/')">edit</a>
+			</ctx>
+		</nav>
+	</div>
 </body>