@icarusmx/creta 1.5.17 → 1.5.18

package/lib/exercises/15-nvim-plugin-architecture.md

@@ -0,0 +1,564 @@
+# Understanding LazyVim Plugin Architecture
+
+<!-- vim: set foldmethod=marker foldlevel=0: -->
+
+## 📖 LazyVim Reading Guide {{{
+
+**Start with:** `zM` (close all folds) → Navigate with `za` (toggle fold)
+
+**Keys for navigation:**
+- `}` - Jump to next section
+- `{` - Jump to previous section
+- `zM` - Close all folds (overview mode)
+- `zR` - Open all folds (detailed mode)
+
+}}}
+
+## 🎯 Purpose {{{
+
+**What:** Understand your LazyVim plugin configuration structure
+**Why:** Know where to add/modify plugins without breaking your setup
+**Time:** 20 minutes
+**Level:** 🟡 Intermediate
+
+**Entrypoint for ariadna nvim configuration:**
+`~/.config/nvim/lua/plugins/`
+
+Each `.lua` file = one plugin configuration (auto-loaded by LazyVim)
+
+}}}
+
+## Plugin Configuration Locations {{{
+
+### Two Important Directories {{{
+
+1. **`~/.config/nvim/lua/config/`** - LazyVim core settings
+   - `lazy.lua` - Plugin manager setup
+   - `options.lua` - Vim options (tab width, line numbers, etc)
+   - `keymaps.lua` - Custom keybindings
+   - `autocmds.lua` - Auto-commands (events)
+
+2. **`~/.config/nvim/lua/plugins/`** - Your plugin overrides
+   - Each file adds/modifies plugins
+   - Auto-loaded alphabetically
+   - This is where YOU make changes
+
+}}}
+
+### Current Plugin Files {{{
+
+```bash
+~/.config/nvim/lua/plugins/
+├── colorscheme.lua           # Theme (Catppuccin Latte)
+├── example.lua               # Reference examples (disabled)
+├── markdown.lua              # Markdown rendering + Glow preview
+├── neo-tree.lua              # File explorer filters
+├── svelte.lua                # Svelte support
+└── telescope_noignore.lua    # Search hidden/ignored files
+```
+
+}}}
+
+}}}
+
+## Part 1: Color Scheme Configuration {{{
+
+### File: `colorscheme.lua` {{{
+
+**Location:** `~/.config/nvim/lua/plugins/colorscheme.lua`
+
+**Purpose:** Override LazyVim's default theme
+
+**Current Setup:**
+```lua
+return {
+  {
+    "catppuccin/nvim",
+    name = "catppuccin",
+    priority = 1000,
+    opts = {
+      flavour = "latte",              -- Light theme
+      transparent_background = true,   -- See terminal bg
+      color_overrides = {
+        latte = {
+          blue = "#1e66f5",            -- Vibrant blues
+        },
+      },
+    },
+  },
+  {
+    "LazyVim/LazyVim",
+    opts = {
+      colorscheme = "catppuccin",
+    },
+  },
+}
+```
+
+**To change theme:**
+1. Edit this file
+2. Save
+3. Run `:Lazy sync` in nvim
+4. Restart nvim
+
+}}}
+
+### Practice: Try Different Flavors {{{
+
+Catppuccin has 4 flavors. Try changing `flavour = "latte"` to:
+
+- `"latte"` - Light (current)
+- `"frappe"` - Light-ish
+- `"macchiato"` - Dark-ish
+- `"mocha"` - Dark
+
+**Exercise:**
+1. Open `~/.config/nvim/lua/plugins/colorscheme.lua`
+2. Change `flavour = "mocha"`
+3. Save (`:w`)
+4. Quit nvim (`:q`)
+5. Reopen nvim
+6. Notice the dark theme
+7. Change back to `"latte"` if you prefer light
+
+}}}
+
+}}}
+
+## Part 2: Markdown Workflow {{{
+
+### File: `markdown.lua` {{{
+
+**Two plugins for different needs:**
+
+1. **render-markdown.nvim** - Inline preview
+   - Auto-renders when you open `.md` files
+   - Shows formatted headings, code blocks, bullets
+   - Works in normal mode (not insert)
+
+2. **glow.nvim** - Full preview
+   - Press `Shift+L` to open terminal preview
+   - Better for reviewing whole documents
+   - Dark theme, 120 char width
+
+**When to use which:**
+- Editing docs → render-markdown (always on)
+- Reviewing docs → Shift+L for glow
+- Presenting docs → Shift+L for clean view
+
+}}}
+
+### Practice: Test Markdown Preview {{{
+
+**Exercise:**
+1. Create a test markdown file: `nvim ~/test-doc.md`
+2. Type this content:
+
+```markdown
+# Test Document
+
+This is a **bold** paragraph with some *italic* text.
+
+## Code Example
+
+```javascript
+console.log("Hello from markdown!");
+```
+
+- Bullet one
+- Bullet two
+```
+
+3. Save (`:w`) and notice render-markdown formatting
+4. Press `Shift+L` to see Glow preview
+5. Press `q` to exit Glow
+6. Delete the test file: `:!rm %`
+
+}}}
+
+}}}
+
+## Part 3: Project-Specific Configs {{{
+
+### File: `neo-tree.lua` {{{
+
+**Hides config clutter from file explorer**
+
+Files hidden:
+- `eslint.config.js`
+- `jsconfig.json`
+- `vite.config.js`
+- `svelte.config.js`
+- `package-lock.json`
+- `.prettierrc`, `.prettierignore`
+- `.npmrc`, `.gitignore`
+
+**Why:** Keep file tree focused on actual code
+
+**To modify:**
+Add filenames to the `hide_by_name` and `never_show` arrays.
+
+}}}
+
+### File: `svelte.lua` {{{
+
+**Sets up Svelte development:**
+
+1. Treesitter parsers: svelte, html, css, js, ts
+2. Svelte LSP with Svelte 5 support
+3. Disables annoying a11y warnings
+
+**Critical for icarus.mx work**
+
+**The config:**
+```lua
+return {
+  -- Treesitter parsers
+  {
+    "nvim-treesitter/nvim-treesitter",
+    opts = function(_, opts)
+      vim.list_extend(opts.ensure_installed, {
+        "svelte", "html", "css", "javascript", "typescript",
+      })
+    end,
+  },
+  -- LSP support
+  {
+    "neovim/nvim-lspconfig",
+    opts = {
+      servers = {
+        svelte = {
+          settings = {
+            svelte = {
+              plugin = {
+                svelte = {
+                  compilerWarnings = {
+                    ["a11y-autofocus"] = "ignore",
+                    ["a11y-click-events-have-key-events"] = "ignore",
+                  },
+                },
+              },
+            },
+          },
+        },
+      },
+    },
+  },
+}
+```
+
+}}}
+
+### File: `telescope_noignore.lua` {{{
+
+**Overrides LazyVim defaults to search EVERYTHING:**
+
+- `--hidden` - Search dotfiles
+- `--no-ignore` - Search node_modules, .git, etc.
+- Shows gitignored files in neo-tree
+
+**When you need it:**
+- Finding files in node_modules
+- Debugging .git issues
+- Exploring hidden config files
+
+**The config:**
+```lua
+return {
+  {
+    "nvim-telescope/telescope.nvim",
+    opts = function(_, opts)
+      opts.defaults = vim.tbl_deep_extend("force", opts.defaults or {}, {
+        vimgrep_arguments = {
+          "rg", "--color=never", "--no-heading",
+          "--with-filename", "--line-number", "--column",
+          "--smart-case", "--hidden", "--no-ignore",
+        },
+      })
+      opts.pickers = vim.tbl_deep_extend("force", opts.pickers or {}, {
+        find_files = {
+          find_command = { "rg", "--files", "--hidden", "--no-ignore" },
+        },
+      })
+    end,
+  },
+}
+```
+
+}}}
+
+}}}
+
+## Part 4: Adding New Plugins {{{
+
+### The Pattern {{{
+
+**Create a new file:** `~/.config/nvim/lua/plugins/my-plugin.lua`
+
+```lua
+return {
+  {
+    "author/plugin-name",
+    opts = {
+      -- plugin options here
+    },
+  },
+}
+```
+
+**LazyVim automatically loads it** - no imports needed!
+
+}}}
+
+### Example: Add GitHub Copilot {{{
+
+**File:** `~/.config/nvim/lua/plugins/copilot.lua`
+
+```lua
+return {
+  {
+    "zbirenbaum/copilot.lua",
+    cmd = "Copilot",
+    event = "InsertEnter",
+    opts = {
+      suggestion = { enabled = true, auto_trigger = true },
+      panel = { enabled = true },
+    },
+  },
+}
+```
+
+Save → `:Lazy sync` → Restart → Done
+
+}}}
+
+### Example: Add a File Icon Theme {{{
+
+**File:** `~/.config/nvim/lua/plugins/devicons.lua`
+
+```lua
+return {
+  {
+    "nvim-tree/nvim-web-devicons",
+    opts = {
+      override = {
+        md = {
+          icon = "📝",
+          color = "#519aba",
+          name = "Markdown",
+        },
+      },
+    },
+  },
+}
+```
+
+This changes the markdown file icon in neo-tree and telescope.
+
+}}}
+
+### Practice: Add Your Own Plugin {{{
+
+**Exercise: Add a TODO comment highlighter**
+
+1. Create the file:
+```bash
+nvim ~/.config/nvim/lua/plugins/todo-comments.lua
+```
+
+2. Add this config:
+```lua
+return {
+  {
+    "folke/todo-comments.nvim",
+    dependencies = { "nvim-lua/plenary.nvim" },
+    opts = {
+      signs = true,
+      keywords = {
+        TODO = { icon = "✓", color = "info" },
+        HACK = { icon = "⚠", color = "warning" },
+        WARN = { icon = "⚠", color = "warning" },
+        NOTE = { icon = "ℹ", color = "hint" },
+      },
+    },
+  },
+}
+```
+
+3. Save and run `:Lazy sync`
+4. Restart nvim
+5. Try it in a JavaScript file:
+
+```javascript
+// TODO: This will be highlighted
+// HACK: So will this
+// NOTE: And this too
+```
+
+6. Search todos with `:TodoTelescope`
+
+}}}
+
+}}}
+
+## Part 5: Understanding Plugin Loading {{{
+
+### How LazyVim Loads Plugins {{{
+
+When nvim starts:
+
+1. Reads `~/.config/nvim/lua/config/lazy.lua`
+2. This file tells Lazy.nvim to load all files in `plugins/`
+3. Each `.lua` file returns a table of plugin specs
+4. Lazy.nvim merges all specs together
+5. Plugins install/load based on events (`VeryLazy`, `InsertEnter`, etc.)
+
+**Key insight:** Files in `plugins/` don't need to import each other. They're all loaded automatically.
+
+}}}
+
+### Plugin Loading Events {{{
+
+Common events you'll see:
+
+- `VeryLazy` - Load after startup (most plugins)
+- `InsertEnter` - Load when entering insert mode
+- `BufRead` - Load when reading a buffer
+- `FileType` - Load for specific file types
+- `cmd` - Load when command is run
+
+**Example:**
+```lua
+return {
+  {
+    "ellisonleao/glow.nvim",
+    cmd = "Glow",           -- Only loads when :Glow is run
+    ft = { "markdown" },    -- Only for .md files
+  },
+}
+```
+
+This keeps nvim startup fast!
+
+}}}
+
+### Overriding vs Extending {{{
+
+**Overriding** - Replace default config:
+```lua
+opts = {
+  theme = "latte",  -- Replaces entire opts table
+}
+```
+
+**Extending** - Add to default config:
+```lua
+opts = function(_, opts)
+  vim.list_extend(opts.ensure_installed, {
+    "svelte",  -- Adds to existing list
+  })
+end
+```
+
+**Use `opts = function` when you want to keep LazyVim defaults.**
+
+}}}
+
+}}}
+
+## Part 6: Debugging Plugin Issues {{{
+
+### Common Issues {{{
+
+**1. Plugin not loading**
+```vim
+:Lazy           " Open Lazy.nvim UI
+:Lazy log       " Check for errors
+:Lazy sync      " Force re-sync
+```
+
+**2. Config not applying**
+- Did you save the file?
+- Did you restart nvim?
+- Did you run `:Lazy sync`?
+
+**3. Conflicting configs**
+- Check if another file overrides the same plugin
+- LazyVim loads files alphabetically
+- Later files can override earlier ones
+
+}}}
+
+### Useful Commands {{{
+
+```vim
+:Lazy                 " Open plugin manager UI
+:Lazy update          " Update all plugins
+:Lazy sync            " Install/update/clean plugins
+:Lazy clean           " Remove unused plugins
+:Lazy profile         " See plugin load times
+:Lazy log             " View error logs
+
+:checkhealth          " Check nvim health
+:LspInfo              " Check LSP status
+:Mason                " Manage LSP/formatters
+```
+
+}}}
+
+### Practice: Debug a Plugin {{{
+
+**Exercise:**
+
+1. Open Lazy UI: `:Lazy`
+2. Press `p` to see profile (load times)
+3. Press `l` to see logs
+4. Find the `catppuccin` plugin
+5. Press `?` to see help
+6. Press `q` to close
+
+This UI shows you:
+- Which plugins are installed
+- Load order and timing
+- Error messages
+- Update status
+
+}}}
+
+}}}
+
+## 🎯 Outcomes {{{
+
+After this exercise, you can:
+
+✅ Find where your plugins are configured
+✅ Modify existing plugin settings
+✅ Add new plugins without breaking LazyVim
+✅ Understand the difference between `config/` and `plugins/`
+✅ Know your Neovim ariadna entrypoint: `~/.config/nvim/lua/plugins/`
+✅ Debug plugin issues using `:Lazy` commands
+✅ Extend vs override plugin configs
+✅ Use lazy loading for fast startup
+
+**Next Steps:**
+- Explore `example.lua` for more patterns
+- Try adding a plugin you've been wanting
+- Customize keybindings in a new plugin file
+- Browse LazyVim extras: `:LazyExtras`
+
+}}}
+
+## 🧭 Reference Links {{{
+
+- LazyVim docs: https://lazyvim.org
+- Lazy.nvim plugin manager: https://github.com/folke/lazy.nvim
+- Catppuccin theme: https://github.com/catppuccin/nvim
+- Plugin examples: `~/.config/nvim/lua/plugins/example.lua`
+- LazyVim plugins list: https://www.lazyvim.org/plugins
+
+**Your actual config:**
+- Main directory: `~/.config/nvim/`
+- Plugin configs: `~/.config/nvim/lua/plugins/`
+- Core settings: `~/.config/nvim/lua/config/`
+
+}}}

package/lib/exercises/README.md

@@ -112,6 +112,12 @@ Each phase builds on knowledge from previous phases.
 **Time:** Design exercise
 **Level:** 🔴 Advanced
 
+### 15. [Understanding LazyVim Plugin Architecture](./15-nvim-plugin-architecture.md)
+**What:** Master your Neovim plugin configuration structure
+**Why:** Add/modify plugins without breaking your setup
+**Time:** 20 minutes
+**Level:** 🟡 Intermediate
+
 ---
 
 ## 🎯 How to Use These Guides
@@ -153,6 +159,10 @@ Prefer to browse by subject?
 - [Shell Aliases](./13-shell-aliases.md)
 - [curl + Pipes](./06-curl-and-pipes.md)
 
+### Neovim Configuration
+- [Developing Muscle Memory for Neovim](./01-developing-muscle-for-nvim.md)
+- [Understanding LazyVim Plugin Architecture](./15-nvim-plugin-architecture.md)
+
 ### JavaScript & Development
 - [Array & Object Manipulation](./04-array-object-manipulation.md)
 - [SvelteKit First Steps](./05-svelte-first-steps.md)
@@ -170,6 +180,7 @@ Prefer to browse by subject?
 
 ### Meta/Tooling
 - [Install Skills Command](./12-install-skills.md)
+- [Understanding LazyVim Plugin Architecture](./15-nvim-plugin-architecture.md)
 
 ---
 

package/package.json

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