From b77ed915ab1e53720a6283702816cea2695a2638 Mon Sep 17 00:00:00 2001
From: Steven Arcangeli <stevearc@stevearc.com>
Date: Thu, 13 Jun 2024 16:17:59 -0400
Subject: [PATCH] doc: add recipes

---
 README.md           |  6 ++++
 doc/recipes.md      | 77 +++++++++++++++++++++++++++++++++++++++++++++
 scripts/generate.py | 23 ++++++++++++--
 3 files changed, 103 insertions(+), 3 deletions(-)
 create mode 100644 doc/recipes.md

diff --git a/README.md b/README.md
index 5b4022f..bfb0b31 100644
--- a/README.md
+++ b/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 -->
diff --git a/doc/recipes.md b/doc/recipes.md
new file mode 100644
index 0000000..3a78a1f
--- /dev/null
+++ b/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,
+  },
+})
+```
diff --git a/scripts/generate.py b/scripts/generate.py
index 7202dc8..8875e9f 100755
--- a/scripts/generate.py
+++ b/scripts/generate.py
@@ -63,10 +63,25 @@ def update_md_api():
     )
 
 
-def update_readme_toc():
-    toc = ["\n"] + generate_md_toc(README, max_level=1) + ["\n"]
+def update_readme():
+    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()