feature: auto-setup using plugin directory

## Details

Request: #79

This allows users to use this plugin without calling the setup function.

In this case the default configuration will be used.

In the original request the suggestion was to use ftplugin, however since
the filetypes this plugin runs on are configurable this is not possible,
hence the usage of the plugin directory instead.

This change should have no impact to existing user while adding
functionality to avoid the setup paradigm if desired. As a consequence
of other changes that needed to be made the concepts of configuration
and initialization are much better separated instead of being coupled.

In order to support this some minor structural changes needed to be made:

- Color and Manager modules as well as User Command are initialed inside
  plugin directory instead of setup to avoid creating multiple copies.
- FileType autocommand can no longer use a pattern directly since it
  is not known until after user calls setup. Instead the callback now
  runs for every event and we filter out events related to other filetypes.
- Creating user command in plugin directory it makes sense to move
  available commands into a separate API module. Use a metatable to allow
  users to call the API methods without changing require logic.
- Minimal init for unit tests now needs to be ordered and call runtime
  method for this plugin. This mimics what a plugin manager with
  dependencies would do.

Other minor changes:

- Add limitation of not running in Telescope Preview
- Add todo to remove gifs from being inside the repo
- Some unrelated comments added to keep track of things

Author: MeanderingProgrammer

doc/limitations.md

@@ -6,6 +6,16 @@
 
 `LaTeX` formula evaluations are placed above text rather than overlayed.
 
+## Does Not Run in Telescope Preview
+
+[ISSUE #98](https://github.com/MeanderingProgrammer/markdown.nvim/issues/98)
+
+Telescope has a special way of previewing files that does not work like a
+standard buffer: [info](https://github.com/nvim-telescope/telescope.nvim?tab=readme-ov-file#previewers)
+
+Due to this the events this plugin relies on to attach to and render buffers
+do not get triggered.
+
 # Resolved Limitations
 
 ## Telescope Opening File

doc/render-markdown.txt

@@ -1,4 +1,4 @@
-*render-markdown.txt*           For 0.10.0           Last change: 2024 July 25
+*render-markdown.txt*           For 0.10.0           Last change: 2024 July 26
 
 ==============================================================================
 Table of Contents                          *render-markdown-table-of-contents*

doc/todo.md

@@ -6,3 +6,4 @@
   same hardware should still be useful.
 - Look into showing marks when switching buffers, currently remains hidden
 - Figure out how to display the many configuration options & impact
+- Remove demos from repository, store elsewhere

lua/render-markdown/api.lua

@@ -0,0 +1,19 @@
+local manager = require('render-markdown.manager')
+local state = require('render-markdown.state')
+
+---@class render.md.Api
+local M = {}
+
+function M.enable()
+    manager.set_all(true)
+end
+
+function M.disable()
+    manager.set_all(false)
+end
+
+function M.toggle()
+    manager.set_all(not state.enabled)
+end
+
+return M

lua/render-markdown/colors.lua

@@ -55,6 +55,7 @@ M.colors = {
     Error      = 'DiagnosticError',
 }
 
+---Should only be called from plugin directory
 function M.setup()
     for name, link in pairs(M.colors) do
         vim.api.nvim_set_hl(0, M.prefix .. name, { link = link, default = true })

lua/render-markdown/init.lua

@@ -1,8 +1,6 @@
-local colors = require('render-markdown.colors')
-local manager = require('render-markdown.manager')
 local state = require('render-markdown.state')
 
----@class render.md.Init
+---@class render.md.Init: render.md.Api
 local M = {}
 
 ---@class render.md.Mark
@@ -454,55 +452,11 @@ function M.setup(opts)
         state.inline_query = vim.treesitter.query.parse('markdown_inline', state.config.inline_query)
         state.inline_link_query = vim.treesitter.query.parse('markdown_inline', state.config.inline_link_query)
     end)
-
-    colors.setup()
-    manager.setup()
-
-    vim.api.nvim_create_user_command('RenderMarkdown', M.command, {
-        nargs = '*',
-        desc = 'markdown.nvim commands',
-        complete = function(_, cmdline)
-            if cmdline:find('RenderMarkdown%s+%S+%s+.*') then
-                return {}
-            elseif cmdline:find('RenderMarkdown%s+') then
-                return { 'enable', 'disable', 'toggle' }
-            else
-                return {}
-            end
-        end,
-    })
-end
-
----@param opts any
-function M.command(opts)
-    local args = opts.fargs
-    if #args == 0 then
-        M.enable()
-    elseif #args == 1 then
-        if args[1] == 'enable' then
-            M.enable()
-        elseif args[1] == 'disable' then
-            M.disable()
-        elseif args[1] == 'toggle' then
-            M.toggle()
-        else
-            vim.notify('markdown.nvim: unexpected command: ' .. args[1], vim.log.levels.ERROR)
-        end
-    else
-        vim.notify('markdown.nvim: unexpected # arguments: ' .. #args, vim.log.levels.ERROR)
-    end
-end
-
-function M.enable()
-    manager.set_all(true)
-end
-
-function M.disable()
-    manager.set_all(false)
-end
-
-function M.toggle()
-    manager.set_all(not state.enabled)
 end
 
-return M
+return setmetatable(M, {
+    __index = function(_, key)
+        -- Allows API methods to be accessed from top level
+        return require('render-markdown.api')[key]
+    end,
+})

lua/render-markdown/manager.lua

@@ -17,11 +17,11 @@ local M = {}
 ---@type integer
 M.group = vim.api.nvim_create_augroup('RenderMarkdown', { clear = true })
 
+---Should only be called from plugin directory
 function M.setup()
-    -- Attach to buffers based on matching filetype, this will add additional events
+    -- Attempt to attach to all buffers, cannot use pattern to support plugin directory
     vim.api.nvim_create_autocmd({ 'FileType' }, {
         group = M.group,
-        pattern = state.config.file_types,
         callback = function(event)
             M.attach(event.buf)
         end,
@@ -70,6 +70,7 @@ function M.attach(buf)
             ui.schedule_refresh(buf, true)
         end,
     })
+    -- Use information specific to this event to determine whether to render or not
     vim.api.nvim_create_autocmd({ 'ModeChanged' }, {
         group = M.group,
         buffer = buf,
@@ -80,6 +81,8 @@ function M.attach(buf)
             -- Only need to re-render if render state is changing. I.e. going from normal mode to
             -- command mode with the default config, both are rendered, so no point re-rendering
             if prev_rendered ~= should_render then
+                -- Since we do not listen to changes that happen while the user is in insert mode
+                -- we must assume changes were made and re-parse the buffer
                 ui.schedule_refresh(buf, true)
             end
         end,
@@ -89,7 +92,7 @@ function M.attach(buf)
             group = M.group,
             buffer = buf,
             callback = function()
-                -- Moving cursor should not result in text change, skip parsing
+                -- Moving cursor should not result in modifications to buffer so can avoid re-parsing
                 ui.schedule_refresh(buf, false)
             end,
         })

plugin/render-markdown.lua

@@ -0,0 +1,39 @@
+if vim.g.loaded_render_markdown then
+    return
+end
+vim.g.loaded_render_markdown = true
+
+require('render-markdown').setup({})
+require('render-markdown.colors').setup()
+require('render-markdown.manager').setup()
+
+vim.api.nvim_create_user_command('RenderMarkdown', function(opts)
+    local args = opts.fargs
+    if #args == 0 then
+        require('render-markdown.api').enable()
+    elseif #args == 1 then
+        if args[1] == 'enable' then
+            require('render-markdown.api').enable()
+        elseif args[1] == 'disable' then
+            require('render-markdown.api').disable()
+        elseif args[1] == 'toggle' then
+            require('render-markdown.api').toggle()
+        else
+            vim.notify('markdown.nvim: unexpected command: ' .. args[1], vim.log.levels.ERROR)
+        end
+    else
+        vim.notify('markdown.nvim: unexpected # arguments: ' .. #args, vim.log.levels.ERROR)
+    end
+end, {
+    nargs = '*',
+    desc = 'markdown.nvim commands',
+    complete = function(_, cmdline)
+        if cmdline:find('RenderMarkdown%s+%S+%s+.*') then
+            return {}
+        elseif cmdline:find('RenderMarkdown%s+') then
+            return { 'enable', 'disable', 'toggle' }
+        else
+            return {}
+        end
+    end,
+})

tests/minimal.lua

@@ -1,13 +1,14 @@
 ---@param path_name string
----@param plugin_name string?
-local function source_plugin(path_name, plugin_name)
+local function source_plugin(path_name)
     local data_path = vim.fn.stdpath('data')
     assert(type(data_path) == 'string')
     local plugin_path = vim.fs.find(path_name, { path = data_path })
     vim.opt.rtp:prepend(unpack(plugin_path))
-    if plugin_name ~= nil then
-        vim.cmd.runtime('plugin/' .. plugin_name)
-    end
+end
+
+---@param plugin_name string
+local function add_runtime(plugin_name)
+    vim.cmd.runtime('plugin/' .. plugin_name)
 end
 
 ---@param required_parsers string[]
@@ -21,10 +22,16 @@ local function ensure_installed(required_parsers)
     end
 end
 
+-- Source dependencies first
+source_plugin('nvim-treesitter')
+add_runtime('nvim-treesitter.lua')
+source_plugin('mini.nvim')
+-- Now we can safely source this plugin
 vim.opt.rtp:prepend('.')
-source_plugin('plenary.nvim', 'plenary.vim')
-source_plugin('nvim-treesitter', 'nvim-treesitter.lua')
-source_plugin('mini.nvim', nil)
+add_runtime('render-markdown.lua')
+-- Used for unit testing, not an actual dependency of this plugin
+source_plugin('plenary.nvim')
+add_runtime('plenary.vim')
 
 -- https://github.com/ThePrimeagen/refactoring.nvim/blob/master/scripts/minimal.vim
 ensure_installed({ 'markdown', 'markdown_inline', 'latex' })