Preview & go to block references (#3)

Author: gimalay

README.md

@@ -90,6 +90,7 @@ Open any `.md` file in your IWE project and enjoy:
 | `:IWE init` | Initialize IWE project in current directory |
 | `:IWE lsp start/stop/restart/status/toggle_inlay_hints` | Control LSP server |
 | `:IWE telescope find_files/paths/roots/grep/backlinks/headers` | Launch Telescope pickers |
+| `:IWE preview squash/export/export-headers/export-workspace` | Generate previews using IWE CLI |
 | `:IWE info` | Show plugin status and configuration |
 
 ## Telescope Integration
@@ -103,6 +104,15 @@ The plugin provides LSP-powered Telescope pickers:
 - **`:IWE telescope backlinks`** - LSP references as backlinks (gr equivalent)
 - **`:IWE telescope headers`** - Document symbols as headers (go equivalent)
 
+## Preview Integration
+
+The plugin provides preview generation using the IWE CLI:
+
+- **`:IWE preview squash`** - Generate squashed markdown preview (combines content with depth 3)
+- **`:IWE preview export`** - Generate basic DOT graph as SVG (depth 2)
+- **`:IWE preview export-headers`** - Generate DOT graph with headers as SVG (depth 2, includes headers)
+- **`:IWE preview export-workspace`** - Generate full workspace graph as SVG (depth 1, all files)
+
 ## Configuration
 
 The plugin works out of the box, but can be customized:
@@ -119,13 +129,19 @@ require('iwe').setup({
     enable_markdown_mappings = true, -- Core markdown editing keybindings
     enable_telescope_keybindings = false, -- Set to true to enable gf, gs, ga, g/, gr, go
     enable_lsp_keybindings = false, -- Set to true to enable IWE-specific LSP keybindings
+    enable_preview_keybindings = false, -- Set to true to enable preview keybindings
     leader = "<leader>",
     localleader = "<localleader>"
   },
   telescope = {
     enabled = true,
     setup_config = true,
     load_extensions = { "ui-select", "emoji" }
+  },
+  preview = {
+    output_dir = "~/tmp/preview", -- Directory for generated preview files
+    temp_dir = "/tmp", -- Directory for temporary files
+    auto_open = false -- Whether to automatically open generated previews
   }
 })
 ```
@@ -186,6 +202,17 @@ Standard LSP actions are available when the LSP server is active:
 | `<leader>rn` | Rename symbol |
 | `<leader>f` | Format document |
 
+### Preview Keybindings (when `enable_preview_keybindings = true`)
+
+IWE CLI preview generation in markdown files:
+
+| Key | Action |
+|-----|--------|
+| `<leader>ps` | Generate squash preview |
+| `<leader>pe` | Generate export graph preview |
+| `<leader>ph` | Generate export with headers preview |
+| `<leader>pw` | Generate workspace preview |
+
 ### Configuration Options
 
 ```lua
@@ -194,6 +221,7 @@ require('iwe').setup({
     enable_markdown_mappings = true,        -- Enable markdown editing keybindings
     enable_telescope_keybindings = true,   -- Enable telescope navigation keybindings
     enable_lsp_keybindings = true,         -- Enable IWE-specific LSP keybindings
+    enable_preview_keybindings = true,     -- Enable preview keybindings
   }
 })
 ```
@@ -214,6 +242,12 @@ vim.keymap.set('n', '<leader>e', '<Plug>(iwe-lsp-extract-section)')
 vim.keymap.set('n', '<leader>i', '<Plug>(iwe-lsp-inline-reference)')
 vim.keymap.set('n', '<leader>h', '<Plug>(iwe-lsp-rewrite-list-section)')
 vim.keymap.set('n', '<leader>l', '<Plug>(iwe-lsp-rewrite-section-list)')
+
+-- Preview keybindings (when enable_preview_keybindings = true)
+vim.keymap.set('n', '<leader>ps', '<Plug>(iwe-preview-squash)')
+vim.keymap.set('n', '<leader>pe', '<Plug>(iwe-preview-export)')
+vim.keymap.set('n', '<leader>ph', '<Plug>(iwe-preview-export-headers)')
+vim.keymap.set('n', '<leader>pw', '<Plug>(iwe-preview-export-workspace)')
 ```
 
 ## Requirements
@@ -222,6 +256,10 @@ vim.keymap.set('n', '<leader>l', '<Plug>(iwe-lsp-rewrite-section-list)')
 - `iwes` LSP server in PATH
 - `nvim-telescope/telescope.nvim`
 
+**For Preview Functionality:**
+- `iwe` CLI in PATH (install from [iwe-org/iwe](https://github.com/iwe-org/iwe))
+- `neato` (Graphviz) for SVG generation
+
 **Recommended:**
 - [`MeanderingProgrammer/markdown.nvim`](https://github.com/MeanderingProgrammer/markdown.nvim) - Enhanced markdown rendering that pairs perfectly with IWE's editing features
 
@@ -235,6 +273,7 @@ Run `:checkhealth iwe` to diagnose any issues with:
 - Telescope integration
 - Project structure
 - Dependencies
+- Preview functionality (IWE CLI and Graphviz)
 
 ## Contributing
 

doc/iwe.txt

@@ -108,8 +108,11 @@ COMMANDS                                                          *iwe-commands*
                         Actions: start, stop, restart, status
 
     telescope {action} Control Telescope pickers
-                        Actions: find_files, paths, roots, grep, backlinks,
-                        headers, setup
+                        Actions: find_files, paths, roots, grep, blockreferences,
+                        backlinks, headers, setup
+
+    preview {action}   Generate previews using IWE CLI
+                        Actions: squash, export, export-headers, export-workspace
 
     info               Show plugin configuration and status
 
@@ -138,7 +141,8 @@ Telescope keybindings (when enable_telescope_keybindings = true):
   `gs`              <Plug>(iwe-telescope-paths)
   `ga`              <Plug>(iwe-telescope-roots)
   `g/`              <Plug>(iwe-telescope-grep)
-  `gr`              <Plug>(iwe-telescope-backlinks)
+  `gr`              <Plug>(iwe-telescope-blockreferences)
+  `gR`              <Plug>(iwe-telescope-backlinks)
   `go`              <Plug>(iwe-telescope-headers)
 
 IWE LSP keybindings (when enable_lsp_keybindings = true):
@@ -147,6 +151,12 @@ IWE LSP keybindings (when enable_lsp_keybindings = true):
   `<leader>h`       <Plug>(iwe-lsp-rewrite-list-section)
   `<leader>l`       <Plug>(iwe-lsp-rewrite-section-list)
 
+Preview keybindings (when enable_preview_keybindings = true):
+  `<leader>ps`      <Plug>(iwe-preview-squash)
+  `<leader>pe`      <Plug>(iwe-preview-export)
+  `<leader>ph`      <Plug>(iwe-preview-export-headers)
+  `<leader>pw`      <Plug>(iwe-preview-export-workspace)
+
 Default Neovim LSP keybindings (available when LSP is active):
   `gD`              Go to declaration
   `gd`              Go to definition  
@@ -172,12 +182,17 @@ Available <Plug> Mappings:~
 *<Plug>(iwe-telescope-paths)*      Workspace symbols - paths (gs equivalent)
 *<Plug>(iwe-telescope-roots)*      Namespace symbols - roots (ga equivalent)
 *<Plug>(iwe-telescope-grep)*       Live grep search (g/ equivalent)
-*<Plug>(iwe-telescope-backlinks)*  LSP references - backlinks (gr equivalent)
+*<Plug>(iwe-telescope-blockreferences)* LSP references - blockreferences (gr equivalent)
+*<Plug>(iwe-telescope-backlinks)*  LSP references - backlinks (gR equivalent)
 *<Plug>(iwe-telescope-headers)*    Document symbols - headers (go equivalent)
 *<Plug>(iwe-lsp-extract-section)*  Extract section (refactor)
 *<Plug>(iwe-lsp-inline-reference)* Inline reference (refactor)
 *<Plug>(iwe-lsp-rewrite-list-section)* Rewrite list section (refactor)
 *<Plug>(iwe-lsp-rewrite-section-list)* Rewrite section list (refactor)
+*<Plug>(iwe-preview-squash)*       Generate squash markdown preview
+*<Plug>(iwe-preview-export)*       Generate export graph preview
+*<Plug>(iwe-preview-export-headers)* Generate export graph with headers preview
+*<Plug>(iwe-preview-export-workspace)* Generate workspace graph preview
 
 ================================================================================
 FUNCTIONS                                                        *iwe-functions*
@@ -212,12 +227,27 @@ require('iwe.telescope').pickers.roots()             *iwe.telescope.roots*
 require('iwe.telescope').pickers.grep()              *iwe.telescope.grep*
     Launch live grep picker (g/ equivalent).
 
+require('iwe.telescope').pickers.blockreferences()    *iwe.telescope.blockreferences*
+    Launch LSP references picker - blockreferences (gr equivalent).
+
 require('iwe.telescope').pickers.backlinks()         *iwe.telescope.backlinks*
-    Launch LSP references picker - backlinks (gr equivalent).
+    Launch LSP references picker - backlinks (gR equivalent).
 
 require('iwe.telescope').pickers.headers()           *iwe.telescope.headers*
     Launch document symbols picker - headers (go equivalent).
 
+require('iwe.preview').generate_squash_preview()      *iwe.preview.squash*
+    Generate squashed markdown preview using iwe CLI.
+
+require('iwe.preview').generate_export_preview()      *iwe.preview.export*
+    Generate basic DOT graph as SVG using iwe CLI.
+
+require('iwe.preview').generate_export_headers_preview() *iwe.preview.export-headers*
+    Generate DOT graph with headers as SVG using iwe CLI.
+
+require('iwe.preview').generate_export_workspace_preview() *iwe.preview.export-workspace*
+    Generate full workspace graph as SVG using iwe CLI.
+
 
 ================================================================================
 HEALTH CHECKS                                                      *iwe-health*
@@ -233,6 +263,7 @@ The health check verifies:
 • Configuration path validity
 • Telescope availability and extensions
 • Optional dependencies
+• Preview functionality (iwe CLI and Graphviz)
 • Current LSP server status
 
 ================================================================================

doc/tags

@@ -4,18 +4,15 @@
 <Plug>(iwe-insert-week)	iwe.txt	/*<Plug>(iwe-insert-week)*
 <Plug>(iwe-link-next)	iwe.txt	/*<Plug>(iwe-link-next)*
 <Plug>(iwe-link-prev)	iwe.txt	/*<Plug>(iwe-link-prev)*
-<Plug>(iwe-lsp-code-action)	iwe.txt	/*<Plug>(iwe-lsp-code-action)*
-<Plug>(iwe-lsp-declaration)	iwe.txt	/*<Plug>(iwe-lsp-declaration)*
-<Plug>(iwe-lsp-definition)	iwe.txt	/*<Plug>(iwe-lsp-definition)*
-<Plug>(iwe-lsp-diagnostic-next)	iwe.txt	/*<Plug>(iwe-lsp-diagnostic-next)*
-<Plug>(iwe-lsp-diagnostic-prev)	iwe.txt	/*<Plug>(iwe-lsp-diagnostic-prev)*
 <Plug>(iwe-lsp-extract-section)	iwe.txt	/*<Plug>(iwe-lsp-extract-section)*
-<Plug>(iwe-lsp-implementation)	iwe.txt	/*<Plug>(iwe-lsp-implementation)*
 <Plug>(iwe-lsp-inline-reference)	iwe.txt	/*<Plug>(iwe-lsp-inline-reference)*
-<Plug>(iwe-lsp-rename)	iwe.txt	/*<Plug>(iwe-lsp-rename)*
 <Plug>(iwe-lsp-rewrite-list-section)	iwe.txt	/*<Plug>(iwe-lsp-rewrite-list-section)*
 <Plug>(iwe-lsp-rewrite-section-list)	iwe.txt	/*<Plug>(iwe-lsp-rewrite-section-list)*
 <Plug>(iwe-lsp-start)	iwe.txt	/*<Plug>(iwe-lsp-start)*
+<Plug>(iwe-preview-export)	iwe.txt	/*<Plug>(iwe-preview-export)*
+<Plug>(iwe-preview-export-headers)	iwe.txt	/*<Plug>(iwe-preview-export-headers)*
+<Plug>(iwe-preview-export-workspace)	iwe.txt	/*<Plug>(iwe-preview-export-workspace)*
+<Plug>(iwe-preview-squash)	iwe.txt	/*<Plug>(iwe-preview-squash)*
 <Plug>(iwe-telescope-backlinks)	iwe.txt	/*<Plug>(iwe-telescope-backlinks)*
 <Plug>(iwe-telescope-find-files)	iwe.txt	/*<Plug>(iwe-telescope-find-files)*
 <Plug>(iwe-telescope-grep)	iwe.txt	/*<Plug>(iwe-telescope-grep)*
@@ -38,6 +35,10 @@ iwe.get_project_root()	iwe.txt	/*iwe.get_project_root()*
 iwe.is_in_project()	iwe.txt	/*iwe.is_in_project()*
 iwe.lsp_available()	iwe.txt	/*iwe.lsp_available()*
 iwe.nvim	iwe.txt	/*iwe.nvim*
+iwe.preview.export	iwe.txt	/*iwe.preview.export*
+iwe.preview.export-headers	iwe.txt	/*iwe.preview.export-headers*
+iwe.preview.export-workspace	iwe.txt	/*iwe.preview.export-workspace*
+iwe.preview.squash	iwe.txt	/*iwe.preview.squash*
 iwe.setup()	iwe.txt	/*iwe.setup()*
 iwe.start_lsp()	iwe.txt	/*iwe.start_lsp()*
 iwe.telescope.backlinks	iwe.txt	/*iwe.telescope.backlinks*

lua/iwe/commands.lua

@@ -3,6 +3,7 @@ local M = {}
 
 local lsp = require('iwe.lsp')
 local telescope = require('iwe.telescope')
+local preview = require('iwe.preview')
 
 
 ---Get completion for LSP commands
@@ -17,6 +18,12 @@ local function complete_telescope_commands()
   return { 'find_files', 'paths', 'roots', 'grep', 'backlinks', 'headers', 'setup' }
 end
 
+---Get completion for Preview commands
+---@return string[]
+local function complete_preview_commands()
+  return { 'squash', 'export', 'export-headers', 'export-workspace' }
+end
+
 ---Initialize IWE project in current directory
 local function init_iwe_project()
   local cwd = vim.fn.getcwd()
@@ -112,6 +119,27 @@ local function handle_telescope_command(subcmd)
   end
 end
 
+---Handle Preview subcommands
+---@param subcmd string The subcommand (squash, export, export-headers, export-workspace)
+local function handle_preview_command(subcmd)
+  if not preview.is_available() then
+    vim.notify("Preview not available - please install iwe CLI and neato (Graphviz)", vim.log.levels.ERROR)
+    return
+  end
+
+  if subcmd == 'squash' then
+    preview.generate_squash_preview()
+  elseif subcmd == 'export' then
+    preview.generate_export_preview()
+  elseif subcmd == 'export-headers' then
+    preview.generate_export_headers_preview()
+  elseif subcmd == 'export-workspace' then
+    preview.generate_export_workspace_preview()
+  else
+    vim.notify(string.format("Unknown Preview command: %s", subcmd), vim.log.levels.ERROR)
+  end
+end
+
 ---Main IWE command handler
 ---@param opts table Command options from nvim_create_user_command
 local function iwe_command(opts)
@@ -137,6 +165,12 @@ local function iwe_command(opts)
       return
     end
     handle_telescope_command(args[2])
+  elseif subcmd == 'preview' or subcmd == 'prev' then
+    if #args < 2 then
+      vim.notify("Usage: IWE preview <squash|export|export-headers|export-workspace>", vim.log.levels.ERROR)
+      return
+    end
+    handle_preview_command(args[2])
   elseif subcmd == 'init' then
     init_iwe_project()
   elseif subcmd == 'info' then
@@ -163,13 +197,18 @@ local function iwe_command(opts)
       string.format("  Setup Config: %s", config.telescope.setup_config),
       string.format("  Extensions: %s", table.concat(config.telescope.load_extensions, ", ")),
       "",
+      "Preview Configuration:",
+      string.format("  Output Dir: %s", config.preview.output_dir),
+      string.format("  Auto Open: %s", config.preview.auto_open),
+      "",
       "Status:",
       string.format("  LSP Available: %s", lsp.is_available() and "Yes" or "No")
     }
 
     local clients = vim.lsp.get_clients({ name = 'iwes' })
     table.insert(lines, string.format("  LSP Running: %s", #clients > 0 and "Yes" or "No"))
     table.insert(lines, string.format("  Telescope Available: %s", telescope.is_available() and "Yes" or "No"))
+    table.insert(lines, string.format("  Preview Available: %s", preview.is_available() and "Yes" or "No"))
 
     -- Check for .iwe marker in current directory
     local iwe_root = vim.fs.root(0, {'.iwe'})
@@ -181,7 +220,7 @@ local function iwe_command(opts)
     end
   else
     vim.notify(string.format("Unknown IWE command: %s", subcmd), vim.log.levels.ERROR)
-    vim.notify("Available commands: lsp, telescope, init, info", vim.log.levels.INFO)
+    vim.notify("Available commands: lsp, telescope, preview, init, info", vim.log.levels.INFO)
   end
 end
 
@@ -196,7 +235,7 @@ local function complete_iwe_command(arg_lead, cmd_line, _)
 
   -- If we're completing the first argument after IWE
   if arg_count == 1 then
-    local subcommands = { 'lsp', 'telescope', 'tel', 'init', 'info' }
+    local subcommands = { 'lsp', 'telescope', 'tel', 'preview', 'prev', 'init', 'info' }
     return vim.tbl_filter(function(cmd)
       return cmd:find('^' .. vim.pesc(arg_lead))
     end, subcommands)
@@ -209,6 +248,8 @@ local function complete_iwe_command(arg_lead, cmd_line, _)
       return complete_lsp_commands()
     elseif subcmd == 'telescope' or subcmd == 'tel' then
       return complete_telescope_commands()
+    elseif subcmd == 'preview' or subcmd == 'prev' then
+      return complete_preview_commands()
     end
   end