doc: add recipes

README.md

@@ -11,6 +11,7 @@ https://user-images.githubusercontent.com/506791/209727111-6b4a11f4-634a-4efa-94
 - [Quick start](#quick-start)
 - [Options](#options)
 - [Adapters](#adapters)
+- [Recipes](#recipes)
 - [API](#api)
 - [FAQ](#faq)
 
@@ -321,6 +322,11 @@ This may look familiar. In fact, this is the same url format that netrw uses.
 
 Note that at the moment the ssh adapter does not support Windows machines, and it requires the server to have a `/bin/sh` binary as well as standard unix commands (`ls`, `rm`, `mv`, `mkdir`, `chmod`, `cp`, `touch`, `ln`, `echo`).
 
+## Recipes
+
+- [Toggle file detail view](doc/recipes.md#toggle-file-detail-view)
+- [Hide gitignored files](doc/recipes.md#hide-gitignored-files)
+
 ## API
 
 <!-- API -->

doc/recipes.md

@@ -0,0 +1,77 @@
+# Recipes
+
+Have a cool recipe to share? Open a pull request and add it to this doc!
+
+<!-- TOC -->
+
+- [Toggle file detail view](#toggle-file-detail-view)
+- [Hide gitignored files](#hide-gitignored-files)
+
+<!-- /TOC -->
+
+## Toggle file detail view
+
+```lua
+local detail = false
+require("oil").setup({
+  keymaps = {
+    ["gd"] = {
+      desc = "Toggle file detail view",
+      callback = function()
+        detail = not detail
+        if detail then
+          require("oil").set_columns({ "icon", "permissions", "size", "mtime" })
+        else
+          require("oil").set_columns({ "icon" })
+        end
+      end,
+    },
+  },
+})
+```
+
+## Hide gitignored files
+
+```lua
+local git_ignored = setmetatable({}, {
+  __index = function(self, key)
+    local proc = vim.system(
+      { "git", "ls-files", "--ignored", "--exclude-standard", "--others", "--directory" },
+      {
+        cwd = key,
+        text = true,
+      }
+    )
+    local result = proc:wait()
+    local ret = {}
+    if result.code == 0 then
+      for line in vim.gsplit(result.stdout, "\n", { plain = true, trimempty = true }) do
+        -- Remove trailing slash
+        line = line:gsub("/$", "")
+        table.insert(ret, line)
+      end
+    end
+
+    rawset(self, key, ret)
+    return ret
+  end,
+})
+
+require("oil").setup({
+  view_options = {
+    is_hidden_file = function(name, _)
+      -- dotfiles are always considered hidden
+      if vim.startswith(name, ".") then
+        return true
+      end
+      local dir = require("oil").get_current_dir()
+      -- if no local directory (e.g. for ssh connections), always show
+      if not dir then
+        return false
+      end
+      -- Check if file is gitignored
+      return vim.list_contains(git_ignored[dir], name)
+    end,
+  },
+})
+```

scripts/generate.py

@@ -63,10 +63,25 @@ def update_md_api():
     )
 
 
-def update_readme_toc():
+def update_readme():
-    toc = ["\n"] + generate_md_toc(README, max_level=1) + ["\n"]
+    def get_toc(filename: str) -> List[str]:
+        subtoc = generate_md_toc(os.path.join(DOC, filename))
+        return add_md_link_path("doc/" + filename, subtoc)
+
+    recipes_toc = get_toc("recipes.md")
+
     replace_section(
         README,
+        r"^## Recipes$",
+        r"^#",
+        ["\n"] + recipes_toc + ["\n"],
+    )
+
+
+def update_md_toc(filename: str, max_level: int = 99):
+    toc = ["\n"] + generate_md_toc(filename, max_level) + ["\n"]
+    replace_section(
+        filename,
         r"^<!-- TOC -->$",
         r"^<!-- /TOC -->$",
         toc,
@@ -381,5 +396,7 @@ def main() -> None:
     """Update the README"""
     update_config_options()
     update_md_api()
-    update_readme_toc()
+    update_md_toc(README, max_level=1)
+    update_md_toc(os.path.join(DOC, "recipes.md"))
+    update_readme()
     generate_vimdoc()