docs: migrating docs from readme

docs/spec/lazy_loading.md

@@ -0,0 +1,57 @@
+# Lazy Loading
+
+**lazy.nvim** automagically lazy-loads Lua modules, so it is not needed to
+specify `module=...` everywhere in your plugin specification. This means that if
+you have a plugin `A` that is lazy-loaded and a plugin `B` that requires a
+module of plugin `A`, then plugin `A` will be loaded on demand as expected.
+
+If you don't want this behavior for a certain plugin, you can specify that with `module=false`.
+You can then manually load the plugin with `:Lazy load foobar.nvim`.
+
+You can configure **lazy.nvim** to lazy-load all plugins by default with `config.defaults.lazy = true`.
+
+Additionally, you can also lazy-load on **events**, **commands**,
+**file types** and **key mappings**.
+
+Plugins will be lazy-loaded when one of the following is `true`:
+
+- The plugin only exists as a dependency in your spec
+- It has an `event`, `cmd`, `ft` or `keys` key
+- `config.defaults.lazy == true`
+
+## 🌈 Colorschemes
+
+Colorscheme plugins can be configured with `lazy=true`. The plugin will automagically load
+when doing `colorscheme foobar`.
+
+> **NOTE:** since **start** plugins can possibly change existing highlight groups,
+> it's important to make sure that your main **colorscheme** is loaded first.
+> To ensure this you can use the `priority=1000` field. **_(see the examples)_**
+
+## ⌨️ Lazy Key Mappings
+
+The `keys` property can be a `string` or `string[]` for simple normal-mode mappings, or it
+can be a `LazyKeysSpec` table with the following key-value pairs:
+
+- **[1]**: (`string`) lhs **_(required)_**
+- **[2]**: (`string|fun()`) rhs **_(optional)_**
+- **mode**: (`string|string[]`) mode **_(optional, defaults to `"n"`)_**
+- **ft**: (`string|string[]`) `filetype` for buffer-local keymaps **_(optional)_**
+- any other option valid for `vim.keymap.set`
+
+Key mappings will load the plugin the first time they get executed.
+
+When `[2]` is `nil`, then the real mapping has to be created by the `config()` function.
+
+```lua
+-- Example for neo-tree.nvim
+{
+  "nvim-neo-tree/neo-tree.nvim",
+    keys = {
+      { "<leader>ft", "<cmd>Neotree toggle<cr>", desc = "NeoTree" },
+    },
+    config = function()
+      require("neo-tree").setup()
+    end,
+}
+```