From c1fb5a09b8f89ae9f81b31baf8bb69f2c30b4178 Mon Sep 17 00:00:00 2001
From: Folke Lemaitre <folke.lemaitre@gmail.com>
Date: Mon, 9 Jan 2023 10:52:18 +0100
Subject: [PATCH] docs: more docs

---
 README.md                  | 237 +++++++++++++++++++++++++++++++++++--
 lua/lazyvim/util/build.lua |   4 +-
 2 files changed, 232 insertions(+), 9 deletions(-)

diff --git a/README.md b/README.md
index bf2d374e..78952b8d 100644
--- a/README.md
+++ b/README.md
@@ -25,6 +25,9 @@ require("lazy").setup({
     { "LazyVim/LazyVim", import = "lazyvim.plugins" },
     -- import/override with your plugins
     { import = "plugins" },
+    -- import any extras modules here
+    -- { import = "lazyvim.plugins.extras.lang.typescript" },
+    -- { import = "lazyvim.plugins.extras.lang.json" },
   },
   defaults = {
     lazy = true, -- every plugin is lazy-loaded by default
@@ -33,14 +36,232 @@ require("lazy").setup({
 })
 ```
 
-## ✅ Todo
+## 📂 File Structure
 
-- [ ] documentation
-- [x] treesitter auto-install seems broken. Switch to `ensure_installed` instead?
-- [x] list all plugins in readme
-- [ ] test all-the-things
-- [x] auto-generate keymaps for README.md
-- [x] auto-generate plugins for README.md
+The files under config will be automatically loaded at the appropriate time,
+so you don't need to require those files manually.
+
+You can add your custom plugin specs under `lua/plugins/`. All files there
+will be automatically loaded by [lazy.nvim](https://github.com/folke/lazy.nvim)
+
+<pre>
+~/.config/nvim
+├── lua
+│   ├── config
+│   │   ├── autocmds.lua
+│   │   ├── keymaps.lua
+│   │   ├── lazy.lua
+│   │   └── options.lua
+│   └── plugins
+│       ├── spec1.lua
+│       ├── **
+│       └── spec2.lua
+└── init.toml
+</pre>
+
+## 🚀 Configuring **LazyVim**
+
+Configuring **LazyVim** is exactly the same as using **lazy.nvim** to build
+a config from scratch.
+
+For the full plugin spec documentation please check the **lazy.nvim**
+[readme](https://github.com/folke/lazy.nvim).
+
+<details><summary>Example spec: <code>lua/plugins/example.lua</code></summary>
+
+<!-- examples:start -->
+
+```lua
+-- every spec file under config.plugins will be loaded automatically by lazy.nvim
+--
+-- In your plugin files, you can:
+-- * add extra plugins
+-- * disable/enabled LazyVim plugins
+-- * override the configuration of LazyVim plugins
+return {
+  -- change trouble config
+  {
+    "folke/trouble.nvim",
+    -- opts will be merged with the parent spec
+    opts = { use_diagnostic_signs = true },
+  },
+
+  -- disable trouble
+  { "folke/trouble.nvim", enabled = false },
+
+  -- add symbols-outline
+  {
+    "simrat39/symbols-outline.nvim",
+    cmd = "SymbolsOutline",
+    keys = { { "<leader>cs", "<cmd>SymbolsOutline<cr>", desc = "Symbols Outline" } },
+    config = true,
+  },
+
+  -- override nvim-cmp and add cmp-emoji
+  {
+    "hrsh7th/nvim-cmp",
+    dependencies = { "hrsh7th/cmp-emoji" },
+    ---@param opts cmp.ConfigSchema
+    opts = function(_, opts)
+      local cmp = require("cmp")
+      opts.sources = cmp.config.sources(vim.list_extend(opts.sources, { { name = "emoji" } }))
+    end,
+  },
+
+  -- change some telescope options and add telescope-fzf-native
+  {
+    "nvim-telescope/telescope.nvim",
+    dependencies = { { "nvim-telescope/telescope-fzf-native.nvim", build = "make" } },
+    keys = {
+      -- add a keymap to browse plugin files
+      -- stylua: ignore
+      {
+        "<leader>fp",
+        function() require("telescope.builtin").find_files({ cwd = require("lazy.core.config").options.root }) end,
+        desc = "Find Plugin File",
+      },
+    },
+    -- change some options
+    opts = {
+      defaults = {
+        layout_strategy = "horizontal",
+        layout_config = { prompt_position = "top" },
+        sorting_strategy = "ascending",
+        winblend = 0,
+      },
+    },
+    -- apply the config and additionally load fzf-native
+    config = function(_, opts)
+      local telescope = require("telescope")
+      telescope.setup(opts)
+      telescope.load_extension("fzf")
+    end,
+  },
+
+  -- add pyright and setup tsserver with typescript.nvim
+  {
+    "neovim/nvim-lspconfig",
+    dependencies = {
+      "jose-elias-alvarez/typescript.nvim",
+      init = function()
+        require("lazyvim.util").on_attach(function(_, buffer)
+          -- stylua: ignore
+          vim.keymap.set( "n", "<leader>co", "TypescriptOrganizeImports", { buffer = buffer, desc = "Organize Imports" })
+          vim.keymap.set("n", "<leader>cR", "TypescriptRenameFile", { desc = "Rename File", buffer = buffer })
+        end)
+      end,
+    },
+    ---@class PluginLspOpts
+    opts = {
+      ---@type lspconfig.options
+      servers = {
+        -- pyright will be automatically installed with mason and loaded with lspconfig
+        pyright = {},
+        tsserver = {},
+      },
+      -- you can do any additional lsp server setup here
+      -- return true if you don't want this server to be setup with lspconfig
+      ---@type table<string, fun(server:string, opts:_.lspconfig.options):boolean?>
+      setup = {
+        -- example to setup with typescript.nvim
+        tsserver = function(_, opts)
+          require("typescript").setup({ server = opts })
+          return true
+        end,
+        -- Specify * to use this function as a fallback for any server
+        -- ["*"] = function(server, opts) end,
+      },
+    },
+  },
+
+  -- for typescript, LazyVim also includes extra specs to properly setup lspconfig,
+  -- treesitter, mason and typescript.nvim. So instead of the above, you can use:
+  { import = "lazyvim.plugins.extras.lang.typescript" },
+
+  -- add more treesitter parsers
+  {
+    "nvim-treesitter/nvim-treesitter",
+    opts = {
+      ensure_installed = {
+        "bash",
+        "help",
+        "html",
+        "javascript",
+        "json",
+        "lua",
+        "markdown",
+        "markdown_inline",
+        "python",
+        "query",
+        "regex",
+        "tsx",
+        "typescript",
+        "vim",
+        "yaml",
+      },
+    },
+  },
+
+  -- since `vim.tbl_deep_extend`, can only merge tables and not lists, the code above
+  -- would overwrite `ensure_installed` with the ne value.
+  -- If you'd rather extend the default config, use the code below instead:
+  {
+    "nvim-treesitter/nvim-treesitter",
+    opts = function(_, opts)
+      vim.list_extend(opts.ensure_installed, {
+        -- add tsx and treesitter
+        ensure_installed = {
+          "tsx",
+          "typescript",
+        },
+      })
+    end,
+  },
+
+  -- the opts function can als be used to change the default opts:
+  {
+    "nvim-lualine/lualine.nvim",
+    event = "VeryLazy",
+    opts = function(_, opts)
+      table.insert(opts.sections.lualine_x, "😄")
+    end,
+  },
+
+  -- or you can return new options to override all the defaults
+  {
+    "nvim-lualine/lualine.nvim",
+    event = "VeryLazy",
+    opts = function()
+      return {
+        --[[add your custom lualine config here]]
+      }
+    end,
+  },
+
+  -- use mini.starter instead of alpha
+  { import = "lazyvim.plugins.extras.ui.mini-starter" },
+
+  -- add jsonls and schemastore ans setup treesitter for json, json5 and jsonc
+  { import = "lazyvim.plugins.extras.lang.json" },
+
+  -- add any tools you want to have installed below
+  {
+    "williamboman/mason.nvim",
+    opts = {
+      ensure_installed = {
+        "stylua",
+        "shellcheck",
+        "shfmt",
+        "flake8",
+      },
+    },
+  },
+}
+```
+
+<!-- examples:end -->
+
+</details>
 
 ## ⌨️ Keymaps
 
@@ -198,7 +419,7 @@ possible keymaps starting with `<space>`.
 
 <!-- plugins:start -->
 
-<details><summary>Core Plugins</summary>
+<details><summary>Core</summary>
 
 - [alpha-nvim](https://github.com/goolord/alpha-nvim)
 - [catppuccin](https://github.com/catppuccin/nvim)
diff --git a/lua/lazyvim/util/build.lua b/lua/lazyvim/util/build.lua
index 1d629afa..06caefc0 100644
--- a/lua/lazyvim/util/build.lua
+++ b/lua/lazyvim/util/build.lua
@@ -101,7 +101,7 @@ function M.update()
 
   ---@type string[]
   local plugins = {
-    "<details><summary>Core Plugins</summary>",
+    "<details><summary>Core</summary>",
     "",
     Docs.plugins(core.plugins).content,
     "",
@@ -138,6 +138,8 @@ require("lazy").setup({
     end
   end)
   data.plugins = { content = table.concat(plugins, "\n") }
+  local examples = vim.fn.fnamemodify(root .. "/../LazyVim-starter/lua/plugins/example.lua", ":p")
+  data.examples = Util.read_file(examples):gsub("^[^\n]+\n[^\n]+\n[^\n]+\n", "")
   Docs.save(data)
 end