doc: Installation/Quickstart for lazy in README.md seems unhelpful

[osamuaoki]

Prerequisites

• [X] I am using the latest stable release of Neovim
• [X] I am using the latest version of the plugin

Neovim Version

v0.10.0-dev-440+g0e01e8155

Neorg setup

Looking at https://github.com/nvim-neorg/neorg#-installationquickstart

I used this lazy startup example for "lazy" into ~/.config/nvim/lua/plugin~/norog.lua.

This start up code is placed into the start up code provided by lazy upstream provided structure as in https://github.com/LazyVim/starter . Its upstream doc site is at https://www.lazyvim.org/

Actual behavior

Start up fails:

Re-sourcing your config is not supported with lazy.nvim            
Invalid spec module: `plugins.neorg`
Expected a `table` of specs, but a `boolean` was returned instead

Expected behavior

Successful start up by following example :-)

Steps to reproduce

As described as above.

Potentially conflicting plugins

No response

Other information

No response

Help

None

Implementation help

lazy is quite different from other plug-in manager. It automatically install required packages. No need to use "require".

So configuration example presented on this README.md started with "require("neorg").setup" looks odd for me. Its repeats look even more odd.

I see successful example at: https://github.com/pysan3/Norg-Tutorial/blob/main/norg_tutorial.md#kickstart-config

I am using: https://github.com/osamuaoki/starter/blob/osamu/lua/plugins/neorg.lua (minor mod to the above)

Both of these works fine with lazy.

These functioning examples provides:

• No "require" so no repeated use of "require"
• Delayed loading using "ft=..."

Since lazy is quite different, it may be best to replace this unhelpful example content with a pointer to the functioning example written by the expert I followed. I mean to https://github.com/pysan3/Norg-Tutorial/blob/main/norg_tutorial.md then more details are also covered.

[osamuaoki]

Oh, typo. I should have said:

So configuration example presented on this README.md started with "require("lazy").setup" looks odd for me. Its use of "require("norg").setup" look even more odd.

[Aumnescio]

Not a dev, but I'll comment in case this maybe offers some clarity.

The example shows the plugin spec for Neorg added "inline" to lazy's setup. It is a way some people might use lazy. Pulling the spec that is inside the require("lazy").setup() into a separate file under ./lua/plugins should work as you'd expect.

Ex:

return {
  {
    "nvim-neorg/neorg",
    build = ":Neorg sync-parsers",
    dependencies = { "nvim-lua/plenary.nvim" },
    config = function()
      require("neorg").setup {
        load = {
          ["core.defaults"] = {}, -- Loads default behaviour
          ["core.concealer"] = {}, -- Adds pretty icons to your documents
          ["core.dirman"] = { -- Manages Neorg workspaces
            config = {
              workspaces = {
                notes = "~/notes",
              },
            },
          },
        },
      }
    end
  }
}

As for the config / setup: The use of require(<plugin>).setup() inside the config block/field/function is very normal, lazy just offers an alternative way which does not require using the config field explicitly. If it's not added manually, I think lazy adds:

config = function(_, opts)
    require("<plugin>").setup(opts)
end

implicitly, by default.

End result is the same as writing out the contents of the opts table inside the setup call directly. Just a minor code-style thing. The current style is very familiar to people that were using packer.

[Aumnescio]

I personally find the example at norg tutoial "odd". To me that looks less approachable for a newcomer.

The end result isn't particularly any different. In the case of misnamed variables, the version with extracted variables is even a tad annoying to me. I think Neorg calls the plugins modules. Wrapping it all in a M (Lua module naming convention) also just adds unnecessary noise, and will confuse people that have no idea what the M is.

[osamuaoki]

Thanks.  I think I was a bit confused over error messages.

Yes.  this is it.  It is a good simple example for so-called lazy kickstart compatible configuration.

On Mon, 2023-06-05 at 23:13 -0700, Aumnescio wrote:

return { { "nvim-neorg/neorg", build = ":Neorg sync-parsers", dependencies = { "nvim-lua/plenary.nvim" }, config = function() require("neorg").setup { load = { ["core.defaults"] = {}, -- Loads default behaviour ["core.concealer"] = {}, -- Adds pretty icons to your documents ["core.dirman"] = { -- Manages Neorg workspaces config = { workspaces = { notes = "~/notes", }, }, }, }, } end } }

But this doesn't do delayed loading as most of us who bothers to use lazy.

So adding  ft="norg", in above example may be a good idea.

Osamu

[osamuaoki]

I think adding followings should help newbies using lazy.nvim plugin manager with upstream created kickstart method template described in Lazyvim.

When the lazy.nvim plugin manager is used by the method described in Lazyvim, you create a ~/.config/nvim/lua/plugins/neorg.lua file with above code lines while replacing the initial line require("lazy").setup({ with return { and the last line }) with }.

This should help newbies to adopt neorg easily without twisting their head.

By the way, I realized https://github.com/nvim-neorg/neorg/wiki/Dependencies#lazynvim had more contexts. This used opts = { load = { .... style without require. But as you stated, this is a trivial style difference.