@icarusmx/creta 1.5.18 → 1.5.19

package/lib/exercises/16-nvim-fold-keymaps.md

@@ -0,0 +1,310 @@
+# Exercise 16: Customizing Fold Keymaps in Neovim (zN instead of zR)
+
+**Objective:** Replace the default `zR` (unfold all) mapping with `zN` so you can unfold all folds with a more intuitive keymap that aligns with your nvim muscle memory.
+
+**Time to complete:** 15 minutes
+
+---
+
+## Why This Matters
+
+Neovim's default fold keymaps follow traditional Vi conventions:
+- `zR` = unfold all (Reduce folds)
+- `zM` = fold all (More folds)
+
+The letter choices are cryptic. If you prefer mnemonics like:
+- `zN` = unfold all (N for "opeN")
+- `zM` = fold all (M stays the same - "More folds" works)
+
+...then this exercise shows you how to map them in your `init.lua`.
+
+---
+
+## Step 1: Understand the Default Fold Keymaps
+
+First, let's see what fold mappings exist by default.
+
+Open your Neovim and check the current mappings:
+
+```vim
+:help fold-commands
+```
+
+The key ones are:
+| Mapping | Action | Default |
+|---------|--------|---------|
+| `zR` | Unfold all | Open all folds in buffer |
+| `zM` | Fold all | Close all folds in buffer |
+| `zr` | Unfold one level | Open one level of folds |
+| `zm` | Fold one level | Close one level of folds |
+| `za` | Toggle fold | Toggle fold at cursor |
+
+---
+
+## Step 2: Locate Your init.lua
+
+Your Neovim configuration file is typically at one of these locations:
+
+```bash
+# Check which one exists
+ls ~/.config/nvim/init.lua
+ls ~/AppData/Local/nvim/init.lua  # Windows
+ls ~/.config/nvim/init.vim         # Old init.vim (less common now)
+```
+
+The standard location on macOS/Linux:
+
+```bash
+~/.config/nvim/init.lua
+```
+
+---
+
+## Step 3: Add the Custom Keymap
+
+Open your `init.lua` in Neovim:
+
+```bash
+nvim ~/.config/nvim/init.lua
+```
+
+Add these lines to create the `zN` mapping:
+
+```lua
+-- Fold keymaps customization
+-- Use zN to unfold all (instead of zR)
+vim.keymap.set('n', 'zN', 'zR', { noremap = true, silent = true, desc = 'Unfold all' })
+
+-- Optional: keep zR as a backup
+-- (Remove this line if you want to completely replace zR with zN)
+-- vim.keymap.set('n', 'zR', 'zN', { noremap = true, silent = true, desc = 'Unfold all (backup)' })
+```
+
+**What each part does:**
+- `'n'` - Normal mode only
+- `'zN'` - The new key you want to press
+- `'zR'` - The command it executes (the built-in unfold all)
+- `noremap = true` - Don't remap recursively
+- `silent = true` - Don't show the command in status line
+- `desc` - Help text when you do `:map zN`
+
+---
+
+## Step 4: Remove or Remap zR
+
+If you want `zR` to stop working (force yourself to use `zN`), add this:
+
+```lua
+-- Disable zR so only zN works
+vim.keymap.set('n', 'zR', '<nop>', { noremap = true, silent = true, desc = 'Disabled - use zN instead' })
+```
+
+Or remap `zR` to something else:
+
+```lua
+-- Remap zR to unfold one level (what zr does)
+vim.keymap.set('n', 'zR', 'zr', { noremap = true, silent = true, desc = 'Unfold one level' })
+```
+
+---
+
+## Step 5: Save and Reload
+
+In Neovim:
+
+```vim
+:w                 " Save the file
+:source %          " Reload the configuration
+```
+
+Or exit and restart Neovim:
+
+```bash
+exit
+nvim
+```
+
+---
+
+## Step 6: Test Your New Mapping
+
+1. Open any file with folds (or create one with folds using `:set foldmethod=syntax`)
+2. Press `zM` to fold all
+3. Press `zN` to unfold all
+4. Verify it works!
+
+---
+
+## Complete Configuration Example
+
+Here's what your `~/.config/nvim/init.lua` fold section should look like:
+
+```lua
+-- ============================================================================
+-- FOLD KEYMAPS
+-- ============================================================================
+
+-- Custom fold mappings for better muscle memory
+vim.keymap.set('n', 'zN', 'zR', { noremap = true, silent = true, desc = 'Unfold all (zN)' })
+vim.keymap.set('n', 'zM', 'zM', { noremap = true, silent = true, desc = 'Fold all (zM)' })
+
+-- Optional: Disable zR to force zN usage
+-- vim.keymap.set('n', 'zR', '<nop>', { noremap = true, silent = true })
+
+-- Optional: Map for one-level fold/unfold with intuitive keys
+-- vim.keymap.set('n', 'zn', 'zr', { noremap = true, silent = true, desc = 'Unfold one level' })
+-- vim.keymap.set('n', 'zm', 'zm', { noremap = true, silent = true, desc = 'Fold one level' })
+
+-- ============================================================================
+```
+
+---
+
+## Verification: Check Your Mapping
+
+After reloading, verify the mapping exists:
+
+```vim
+:map zN
+```
+
+You should see:
+```
+n  zN           zR
+```
+
+This confirms `zN` now executes `zR` (unfold all).
+
+---
+
+## Advanced: Create a Fold Mode Function
+
+If you want even more control, create a function:
+
+```lua
+-- Function-based fold toggle
+local function toggle_fold_level()
+  -- Get current fold level
+  local fold_level = vim.fn.foldlevel(vim.fn.line('.'))
+
+  if fold_level > 0 then
+    vim.cmd('zN')  -- Unfold all
+  else
+    vim.cmd('zM')  -- Fold all
+  end
+end
+
+vim.keymap.set('n', 'z<Space>', toggle_fold_level, { noremap = true, silent = true, desc = 'Toggle fold state' })
+```
+
+Then pressing `z<Space>` intelligently toggles between fold all and unfold all.
+
+---
+
+## Troubleshooting
+
+### Mapping doesn't work
+**Problem:** You press `zN` and nothing happens.
+
+**Solution:**
+1. Verify the mapping was loaded: `:map zN`
+2. Check for conflicts: `:verbose map zN`
+3. Make sure you're in Normal mode (press `Esc` first)
+4. Reload config: `:source %`
+
+### Old mapping still works
+**Problem:** `zR` still unfolds even though you wanted to disable it.
+
+**Solution:**
+- Make sure you added the `<nop>` mapping for `zR`
+- Restart Neovim completely (`:q!` then `nvim`)
+- Check if another plugin is defining `zR`: `:verbose map zR`
+
+### Fold commands not working
+**Problem:** `zN` executes but nothing happens.
+
+**Solution:**
+- Make sure the buffer has folds: `:set foldmethod=syntax` or `:set foldmethod=manual`
+- The buffer must have fold markers (depends on `foldmethod`)
+- Check the file type supports folding
+
+---
+
+## Related Keymaps Worth Adding
+
+While you're customizing folds, consider these related mappings:
+
+```lua
+-- Complete fold mapping suite
+vim.keymap.set('n', 'zN', 'zR', { noremap = true, silent = true, desc = 'Unfold all' })
+vim.keymap.set('n', 'zM', 'zM', { noremap = true, silent = true, desc = 'Fold all' })
+vim.keymap.set('n', 'zn', 'zr', { noremap = true, silent = true, desc = 'Unfold one level' })
+vim.keymap.set('n', 'zm', 'zm', { noremap = true, silent = true, desc = 'Fold one level' })
+vim.keymap.set('n', 'zc', 'zc', { noremap = true, silent = true, desc = 'Close fold' })
+vim.keymap.set('n', 'zo', 'zo', { noremap = true, silent = true, desc = 'Open fold' })
+vim.keymap.set('n', 'za', 'za', { noremap = true, silent = true, desc = 'Toggle fold' })
+```
+
+---
+
+## Pro Tips
+
+1. **Use modelines** - Add to the top of files you edit frequently:
+```vim
+" vim: set foldmethod=syntax foldlevel=1 :
+```
+
+2. **Set default foldlevel** - Add to `init.lua`:
+```lua
+vim.opt.foldlevel = 1  -- Start with one level of folds open
+```
+
+3. **Use with LazyVim** - If using LazyVim, add to `~/.config/nvim/lua/config/keymaps.lua`:
+```lua
+-- Already might have keymaps there
+vim.keymap.set('n', 'zN', 'zR', { desc = 'Unfold all' })
+```
+
+4. **Vim muscle memory** - Remember: `z` is for "**z**ones" (folds), then:
+   - `N` = ope**N** all
+   - `M` = **M**ore closed
+   - `C` = **C**lose
+   - `O` = **O**pen
+   - `A` = **A**lternate (toggle)
+
+---
+
+## Summary
+
+You've successfully:
+- ✅ Understood Neovim's default fold keymaps
+- ✅ Located your `init.lua` configuration
+- ✅ Created a custom `zN` mapping for unfold all
+- ✅ Optionally disabled the old `zR` mapping
+- ✅ Tested your new configuration
+- ✅ Verified the mapping is active
+
+Your new `zN` keymap is now part of your Neovim muscle memory. Use it consistently in your workflow.
+
+---
+
+## Next Steps
+
+1. Create this mapping in your actual `init.lua` right now
+2. Test it for the next week in your daily editing
+3. If you like it, consider adding the one-level mappings (`zn` and `zm`)
+4. Move on to Exercise 17 when you're comfortable with fold navigation
+
+---
+
+## Resources
+
+- `:help fold-commands` - Full fold command documentation
+- `:help mapping` - Full mapping documentation
+- `:help option-window` - View all fold-related options
+- `:map` - List all current mappings
+- `:verbose map zN` - See where a mapping is defined
+
+---
+
+**Keep it simple.** Just two lines for the basic mapping. Everything else is optional optimization.

package/lib/exercises/17-ariadna-custom-fold-keymaps.md

@@ -0,0 +1,373 @@
+# Customizing Fold Keymaps in Ariadna (zN instead of zR)
+
+<!-- vim: set foldmethod=marker foldlevel=0: -->
+
+## 📖 Ariadna Reading Guide {{{
+
+**Start with:** `zM` (close all folds) → Navigate with `za` (toggle fold under cursor)
+
+**Keys for navigation:**
+- `}` - Jump to next section
+- `{` - Jump to previous section
+- `zM` - Close all folds (overview mode)
+- `zN` - Open all folds (will use this after implementing!)
+
+}}}
+
+## 🎯 Purpose {{{
+
+**What:** Replace Neovim's default fold keymaps with more intuitive ones
+**Why:** The default `zR` is cryptic; `zN` (for "opeN") is more memorable
+**Time:** 10 minutes
+**Level:** 🟢 Beginner
+**Entrypoint for ariadna setup:** `~/.config/nvim/lua/plugins/`
+
+}}}
+
+## Part 1: Understanding Default Fold Commands {{{
+
+### Why Fold Commands Matter {{{
+
+Ariadna uses fold markers (`{{{` and `}}}`) throughout documentation to create navigable sections. But the default Neovim keymaps are cryptic:
+
+- `zR` = unfold all (Reduce? No one knows...)
+- `zM` = fold all (More folds? Still confusing!)
+- `zr` = unfold one level
+- `zm` = fold one level
+
+These follow old Vi conventions, not modern mnemonics.
+
+}}}
+
+### The Better Alternative {{{
+
+We want:
+- `zN` = unfold all (N for "**opeN**")
+- `zM` = fold all (M for "**More** closed" - keep this)
+- `zn` = unfold one level (lowercase n)
+- `zm` = fold one level (lowercase m)
+
+This is much more memorable and aligns with your muscle memory.
+
+}}}
+
+}}}
+
+## Part 2: Creating the Plugin File {{{
+
+### Step 1: Create the Folds Plugin {{{
+
+Create a new file in Ariadna's plugin directory:
+
+```bash
+nvim ~/.config/nvim/lua/plugins/folds.lua
+```
+
+This is where all Ariadna plugins live. LazyVim auto-loads every `.lua` file in this directory.
+
+}}}
+
+### Step 2: Add the Configuration {{{
+
+Add this to `folds.lua`:
+
+```lua
+-- Custom fold keymaps for Ariadna
+-- Replace cryptic zR/zM with intuitive zN/zM
+
+return {
+  {
+    "fold-keymaps/custom",
+    init = function()
+      local map = vim.keymap.set
+
+      -- Main fold commands
+      map("n", "zN", "zR", { desc = "Unfold all (zN = opeN)" })
+      map("n", "zM", "zM", { desc = "Fold all (zM = More closed)" })
+
+      -- Optional: One-level fold/unfold
+      map("n", "zn", "zr", { desc = "Unfold one level" })
+      map("n", "zm", "zm", { desc = "Fold one level" })
+
+      -- Optional: Disable zR to force zN usage
+      -- Uncomment if you want to completely replace zR
+      -- map("n", "zR", "<nop>", { desc = "Use zN instead (unfold all)" })
+    end,
+  },
+}
+```
+
+**What each mapping does:**
+- `map("n", "zN", "zR", ...)` - In Normal mode, pressing `zN` executes `zR` (unfold all)
+- `desc` - Help text for `:map zN` or which-key
+
+}}}
+
+### Step 3: Save and Reload {{{
+
+In Neovim:
+
+```vim
+:w                " Save folds.lua
+:source %         " Reload configuration
+```
+
+Or exit and restart Neovim - LazyVim will auto-load the new plugin.
+
+}}}
+
+}}}
+
+## Part 3: Testing Your Custom Keymaps {{{
+
+### Test Zone: Try Your New Keymaps {{{
+
+Now that you've created `folds.lua`, test it:
+
+1. **Fold all content:**
+   Press `zM` (or `zm zm zm...` to fold level by level)
+
+2. **Unfold all content:**
+   Press `zN` (this is your new mapping!)
+
+3. **Verify it works:**
+   Check the output shows all sections visible again
+
+4. **One-level folds:**
+   Try `zn` (unfold one level) and `zm` (fold one level)
+
+The keymaps should respond immediately. If they don't:
+- Did you save `folds.lua`?
+- Did you reload nvim?
+- Check: `:map zN` should show the mapping
+
+}}}
+
+### Advanced: Verify the Mapping {{{
+
+In Neovim, run:
+
+```vim
+:map zN
+```
+
+You should see output like:
+
+```
+n  zN           zR
+```
+
+This confirms `zN` is mapped to `zR` (unfold all). If nothing shows, the mapping didn't load.
+
+}}}
+
+}}}
+
+## Part 4: Ariadna-Specific Context {{{
+
+### Why This Matters for Ariadna Users {{{
+
+Ariadna documents are built with fold markers for optimal navigation:
+
+```lua
+-- These fold markers structure everything
+-- {{{ = start fold
+-- }}} = end fold
+```
+
+When you're reading Ariadna docs or editing structured Lua files, you'll:
+
+1. Start with `zM` (fold all) to see structure
+2. Navigate with `}` to jump sections
+3. Use `za` to toggle individual folds
+4. Use `zN` to unfold everything when you need full content
+
+This is the "Ariadna way" of reading documentation.
+
+}}}
+
+### Where You'll Use This {{{
+
+Every Ariadna document uses this pattern:
+
+- `01-developing-muscle-for-nvim.md` - Has fold markers
+- `15-nvim-plugin-architecture.md` - Heavily folded
+- Your own `.md` files - You'll add fold markers too
+
+Plus any Lua files you write in `~/.config/nvim/lua/` will benefit from custom fold navigation.
+
+}}}
+
+}}}
+
+## Part 5: Optional Customizations {{{
+
+### Option 1: Disable Old zR Mapping {{{
+
+If you want to completely replace `zR` with `zN` (force new muscle memory):
+
+**Edit** `~/.config/nvim/lua/plugins/folds.lua`:
+
+```lua
+-- Disable zR to force zN usage
+map("n", "zR", "<nop>", { desc = "Use zN instead" })
+```
+
+This makes `zR` do nothing, so you're forced to use `zN`.
+
+}}}
+
+### Option 2: Add Custom Fold Default Level {{{
+
+You can set the default fold level when opening files:
+
+```lua
+vim.opt.foldlevel = 1  -- Start with one level open
+```
+
+Add this to `~/.config/nvim/lua/config/options.lua` (or create a new section in folds.lua):
+
+```lua
+init = function()
+  -- Set default fold behavior
+  vim.opt.foldlevel = 1
+  vim.opt.foldmethod = "marker"  -- Use {{{ }}} markers
+end
+```
+
+}}}
+
+### Option 3: Add Smart Fold Toggle {{{
+
+Create a function that intelligently toggles between fold all/unfold all:
+
+```lua
+local function smart_fold_toggle()
+  local fold_level = vim.fn.foldlevel(vim.fn.line('.'))
+  if fold_level > 0 then
+    vim.cmd('zN')  -- Unfold all
+  else
+    vim.cmd('zM')  -- Fold all
+  end
+end
+
+map("n", "z<Space>", smart_fold_toggle, { desc = "Smart fold toggle" })
+```
+
+Now `z<Space>` intelligently switches between folded/unfolded state.
+
+}}}
+
+}}}
+
+## Part 6: Troubleshooting {{{
+
+### Mapping Doesn't Work {{{
+
+**Problem:** You press `zN` and nothing happens.
+
+**Solutions:**
+1. Verify mapping loaded: `:map zN` (should show output)
+2. Reload config: `:source %` or restart nvim
+3. Check you're in Normal mode (press `Esc` first)
+4. Verify `folds.lua` file exists: `ls ~/.config/nvim/lua/plugins/folds.lua`
+
+}}}
+
+### Old zR Mapping Still Works {{{
+
+**Problem:** `zR` still unfolds even though you wanted to disable it.
+
+**Solutions:**
+1. Make sure you added the `<nop>` mapping in `folds.lua`
+2. Restart Neovim completely (`:q!` then `nvim`)
+3. Check for conflicts: `:verbose map zR`
+
+}}}
+
+### File Has No Folds {{{
+
+**Problem:** `zM` doesn't do anything.
+
+**Solutions:**
+1. File must use fold markers: `{{{` and `}}}`
+2. Set foldmethod: `:set foldmethod=marker`
+3. Try on an Ariadna document that has fold markers
+
+}}}
+
+}}}
+
+## 🎯 Outcomes {{{
+
+After this exercise, you can:
+
+✅ Create custom Neovim keymaps in Ariadna plugin files
+✅ Replace cryptic default keymaps with intuitive ones
+✅ Use `zN` instead of `zR` for "open" all folds
+✅ Structure your Lua files with fold markers for navigation
+✅ Read Ariadna documentation using fold navigation
+✅ Customize Ariadna's behavior without forking the repo
+✅ Debug and verify custom keymaps with `:map`
+
+**Your new workflow:**
+- `zM` - Fold all (see structure)
+- `}` - Jump to next section
+- `za` - Toggle individual fold
+- `zN` - Unfold all (see content)
+
+**Next Steps:**
+- Try the custom `zN` mapping in actual Ariadna files
+- Add fold markers to your own documentation
+- Experiment with one-level folds (`zn`/`zm`)
+- Move on to Exercise 18 when comfortable
+
+}}}
+
+## 🧭 Reference Links {{{
+
+**Ariadna Locations:**
+- Plugin files: `~/.config/nvim/lua/plugins/`
+- Core settings: `~/.config/nvim/lua/config/`
+- Your config: `~/.config/nvim/init.lua`
+
+**Neovim Documentation:**
+- `:help fold-commands` - Full fold documentation
+- `:help map` - Mapping documentation
+- `:help foldmethod` - Fold detection options
+
+**Vim Mnemonics:**
+- `z` = zones (folds)
+- `N` = ope**N** (unfold all)
+- `M` = **M**ore folds (fold all)
+- `n` = ope**n** (unfold one level)
+- `m` = **m**ore folds (fold one level)
+
+**Related Exercises:**
+- Exercise 01 - Developing Muscle Memory (uses fold navigation)
+- Exercise 15 - LazyVim Plugin Architecture (plugin structure)
+
+}}}
+
+## 📝 Quick Reference: What You Just Created {{{
+
+**File:** `~/.config/nvim/lua/plugins/folds.lua`
+
+**What it does:**
+1. Maps `zN` to `zR` (unfold all)
+2. Maps `zM` to `zM` (fold all - no change needed)
+3. Maps `zn` to `zr` (unfold one level - optional)
+4. Maps `zm` to `zm` (fold one level - optional)
+
+**How to modify:**
+- Edit the file and save
+- Reload: `:source %` or restart nvim
+- Verify: `:map zN`
+
+**How to remove:**
+```bash
+rm ~/.config/nvim/lua/plugins/folds.lua
+# Then restart nvim
+```
+
+}}}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@icarusmx/creta",
-  "version": "1.5.18",
+  "version": "1.5.19",
   "description": "Salgamos de este laberinto.",
   "type": "module",
   "bin": {