From 0d97ea4e36507aa4ba65795675bcf3cfe6ec3321 Mon Sep 17 00:00:00 2001
From: Jonas Widen <jonas.widen@widens.eu>
Date: Sun, 16 Mar 2025 20:20:40 +0100
Subject: [PATCH] Update docs

---
 README.md | 113 +++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 111 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 441c0e4..19587f3 100644
--- a/README.md
+++ b/README.md
@@ -24,6 +24,8 @@ Use your favorite Neovim package manager. Here's how to install with Lazy.nvim:
 
 ## Configuration
 
+### API Key Setup
+
 Set your API key using one of these methods:
 
 1. Environment variable:
@@ -37,6 +39,107 @@ export GEMINI_API_KEY="your-api-key-here"
 vim.g.gemini_api_key = "your-api-key-here"
 ```
 
+### Plugin Configuration
+
+The plugin can be configured during setup. Here's an example with all available options and their defaults:
+
+```lua
+require("gemini").setup({
+    -- Model configuration
+    model = "gemini-2.0-flash", -- The Gemini model to use
+
+    -- Window appearance
+    window = {
+        -- Window width (can be number or function)
+        width = function() 
+            return math.floor(vim.o.columns / 3)
+        end,
+        -- Window height (can be number or function)
+        height = function()
+            return vim.o.lines - 2
+        end,
+        border = "rounded",     -- Border style: "none", "single", "double", "rounded"
+        title = "Gemini Chat Session",
+        title_pos = "center",   -- Title position: "left", "center", "right"
+    },
+
+    -- Keymaps in chat window
+    mappings = {
+        close = 'q',           -- Close chat window
+        return_focus = '<Esc>', -- Return to previous window
+        new_query = 'i',       -- Start new query
+    },
+
+    -- Highlight groups for chat messages
+    highlights = {
+        user = "GeminiUser",         -- Highlight group for user messages
+        separator = "GeminiSeparator", -- Highlight group for message separators
+    },
+})
+```
+
+### Customizing Highlights
+
+The plugin defines two highlight groups that you can customize:
+
+```lua
+-- In your init.lua or colorscheme
+vim.api.nvim_set_hl(0, "GeminiUser", { fg = "#EBCB8B", bold = true })
+vim.api.nvim_set_hl(0, "GeminiSeparator", { fg = "#616E88", bold = true })
+```
+
+### Default Keymaps
+
+The plugin sets up the following default keymaps:
+
+- `<leader>gc`: Open chat window for a new query
+- `<leader>gs`: Open chat window with current buffer as context
+- `<leader>gq`: Clear chat history
+
+You can override these by adding your own mappings after setup:
+
+```lua
+-- Example of custom keymaps
+vim.keymap.set("n", "<leader>m", function()
+    require("gemini").prompt_query()
+end, { desc = "Chat with Gemini AI" })
+
+vim.keymap.set("n", "<leader>M", function()
+    require("gemini").prompt_query(vim.api.nvim_buf_get_lines(0, 0, -1, false))
+end, { desc = "Chat with Gemini AI (with buffer context)" })
+```
+
+### Configuration Tips
+
+1. **Window Size**: The window size functions can be customized to your needs:
+```lua
+window = {
+    width = function()
+        -- Use 40% of screen width
+        return math.floor(vim.o.columns * 0.4)
+    end,
+    height = function()
+        -- Use 80% of screen height
+        return math.floor(vim.o.lines * 0.8)
+    end
+}
+```
+
+2. **Fixed Dimensions**: You can use fixed numbers instead of functions:
+```lua
+window = {
+    width = 80,   -- Fixed width of 80 columns
+    height = 40,  -- Fixed height of 40 lines
+}
+```
+
+3. **Custom Border Style**: Choose from available border styles:
+```lua
+window = {
+    border = "double",  -- Options: "none", "single", "double", "rounded"
+}
+```
+
 ## Usage
 
 The plugin provides several ways to interact with Gemini:
@@ -70,7 +173,13 @@ The chat window appears on the right side of your editor and provides the follow
 - `q`: Close the chat window (history is preserved)
 - `<Esc>`: Return focus to previous buffer
 - Normal mode scrolling commands (`j`, `k`, `<C-d>`, `<C-u>`, etc.) work as expected
-- Window automatically scrolls to show new messages at the top
+
+Chat Window Display:
+- Your latest query is automatically positioned at the top of the window
+- The AI's response appears directly below your query
+- Previous conversation history is accessible by scrolling up
+- Messages are clearly marked with "User:" and "Assistant:" prefixes
+- Messages are separated by horizontal lines for better readability
 
 File operations in the chat window are intentionally disabled:
 - `:w`, `:e`, `:sp`, `:vs` and similar commands are blocked
@@ -91,7 +200,7 @@ File operations in the chat window are intentionally disabled:
 - Support for the latest Gemini 2.0 Flash model
 - Markdown syntax highlighting for responses
 - Context-aware queries using current buffer content
-- Automatic scrolling to new messages
+- Smart conversation display with latest query at the top
 - Protected chat window to prevent accidental modifications
 
 ## Troubleshooting