Feature: Snippets

Scope

- Create a template/snippet system in ~/.config/nvim/snippets/
- Auto-discover template files with associated metadata (.md files)
- Integrate with existing picker and explorer context menus
- Support variable substitution and filetype-aware filtering
- Enable both file creation from templates and inline snippet expansion

Main Features

1. Template Structure

- Template Files: Actual code files (e.g., component.tsx, README.md)
- Metadata Files: Companion .md files with frontmatter configuration
- Auto-discovery: Automatically scan and cache templates on startup/demand
- Category Organization: Templates organized in subdirectories by type/language

2. Variable System

- Built-in Variables: {{FILENAME}}, {{DATE}}, {{YEAR}}, {{GIT_AUTHOR}}
- Custom Variables: Defined in metadata with defaults and descriptions
- Transform Functions: PascalCase, camelCase, snake_case conversions
- Interactive Prompts: Request user input for undefined variables

3. Filetype Intelligence

- Context-aware Filtering: Show relevant templates based on current buffer filetype
- Multi-filetype Support: Templates can target multiple filetypes
- Extension Matching: Fallback to file extension when filetype unavailable

Use Cases

Primary Use Cases

1. New File Creation: Create React component in a directory via explorer
2. Boilerplate Generation: Initialize common file structures (tests, configs)
3. Project Scaffolding: Create multiple related files from template sets
4. Code Snippets: Inline expansion of smaller templates via triggers

User Workflow

1. Via Explorer Context Menu:
- Navigate to directory in explorer
- Press 'f' for context menu
- Select "Create from Template"
- Pick template from filtered list
- Enter filename and variables
- File created and opened
2. Via Direct Picker (future):
- Press st (search templates)
- Browse all templates with preview
- Select and specify target directory
3. Via Inline Expansion (optional):
- Type !reactfc in insert mode
- Template expands in current buffer
- Tab through variable placeholders

Auto-Discovery System

Directory Structure

~/.config/nvim/snippets/
├── react/
│ ├── component.tsx
│ ├── component.tsx.md
│ ├── hook.ts
│ └── hook.ts.md
├── vue/
│ ├── component.vue
│ └── component.vue.md
└── general/
├── README.md
└── README.md.md

Metadata Format

---
name: React Functional Component
description: TypeScript React component with props
filetype: [typescriptreact, javascriptreact]
snippet_trigger: reactfc
variables:
- name: COMPONENT_NAME
description: Component name
default: "{{FILENAME}}"
transform: PascalCase
- name: PROPS
description: Props interface content
required: true
---

Discovery Process

1. On Neovim startup or manual trigger
2. Recursively scan ~/.config/nvim/snippets/
3. Parse .md files for metadata
4. Cache templates with categorization
5. Register snippet triggers if specified

---
Phase 2: Integration Recommendations

Custom Picker Implementation (Required)

1. Template Picker

-- New source in snacks.lua
sources = {
templates = {
auto_close = true,
preview = true,
layout = { preset = "telescope" },
format = function(item)
-- Custom formatting for template items
return {
text = item.name,
icon = item.icon or "󰈙",
comment = item.category
}
end,
actions = {
create_with_variables = { ... },
copy_to_clipboard = { ... },
edit_template = { ... }
}
}
}

2. Menu Integration Points

A. Explorer Context Menu (Modify picker-extensions.lua):
-- Add to single_dir actions
{
key = "n",
desc = "New from template",
action = function(picker, item)
-- Launch template picker with target dir
show_template_picker(item.file)
end
}

B. Global Template Browser:
-- Add to snacks.lua keys
{
"st",
function()
Snacks.picker.templates({
cwd = vim.fn.stdpath("config") .. "/snippets"
})
end,
desc = "Search templates"
}

C. Context-Aware Quick Templates:
-- Add smart detection in explorer menu
if item.dir and detect_project_type(item.file) == "react" then
-- Show React-specific quick actions
table.insert(actions, {
key = "rc",
desc = "React component here",
action = quick_react_component
})
end

Future Enhancements

1. Template Sets

- Create multiple related files from one action
- Example: Component + Test + Story files

2. Project Templates

- Whole project scaffolding
- Integration with existing project management

3. Snippet Engine Integration

- LuaSnip for advanced snippets
- Unified variable handling

4. Template Sharing

- Git submodules for team templates
- Template marketplace integration

5. Smart Defaults

- Learn from usage patterns
- Project-specific variable defaults

### R&D Stratagy

First we need to research existing solutions and summarize their
- Benefits
- Shortcommings

Existing solutions in this space:
- LuaSnip + nvim-cmp
- [friendly-snippets](https://github.com/rafamadriz/friendly-snippets)