From 535d4cfd5ed35b8294b5651f97ea7a4d2eaea6d5 Mon Sep 17 00:00:00 2001
From: Barrett Ruth <62671086+barrettruth@users.noreply.github.com>
Date: Wed, 11 Mar 2026 15:43:13 -0400
Subject: [PATCH] docs: add FAQ entry for redirecting markdown output to /tmp
 (#56)

Problem: the `markdown` and `github` presets write `.html` output to the
working directory, which clutters the project.

Solution: add a FAQ entry to both `README.md` and `doc/preview.txt`
showing how to override the `output` field to redirect to `/tmp`.
---
 README.md       | 16 ++++++++++++++++
 doc/preview.txt | 21 ++++++++++++++++++++-
 2 files changed, 36 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 6d896ac..7012cfe 100644
--- a/README.md
+++ b/README.md
@@ -82,6 +82,22 @@ vim.g.preview = {
 }
 ```
 
+**Q: Markdown compilation drops `.html` files in my working directory. How do I
+send output to `/tmp` instead?**
+
+Override the `output` field. The `args` function references `ctx.output`, so the
+compiled file lands wherever `output` points:
+
+```lua
+vim.g.preview = {
+  github = {
+    output = function(ctx)
+      return '/tmp/' .. vim.fn.fnamemodify(ctx.file, ':t:r') .. '.html'
+    end,
+  },
+}
+```
+
 **Q: How do I set up SyncTeX (forward/inverse search)?**
 
 See `:help preview-synctex` for full recipes covering Zathura, Sioyek, and
diff --git a/doc/preview.txt b/doc/preview.txt
index f16b1ae..be1d82b 100644
--- a/doc/preview.txt
+++ b/doc/preview.txt
@@ -27,7 +27,8 @@ CONTENTS                                                   *preview-contents*
   7. Lua API ................................................... |preview-api|
   8. Events ............................................... |preview-events|
   9. Health ............................................... |preview-health|
-  10. SyncTeX ............................................. |preview-synctex|
+  10. FAQ ..................................................... |preview-faq|
+  11. SyncTeX ............................................. |preview-synctex|
 
 ==============================================================================
 REQUIREMENTS                                           *preview-requirements*
@@ -314,6 +315,24 @@ Checks: ~
 - Each configured provider's binary is executable
 - Each configured provider's opener binary (if any) is executable
 
+==============================================================================
+FAQ                                                            *preview-faq*
+
+Q: Markdown/GFM compilation drops `.html` files in my working directory.
+   How do I send output to `/tmp` instead?
+
+A: Override the `output` field. The `args` function references `ctx.output`,
+   so the compiled file lands wherever `output` points: >lua
+
+    vim.g.preview = {
+      github = {
+        output = function(ctx)
+          return '/tmp/' .. vim.fn.fnamemodify(ctx.file, ':t:r') .. '.html'
+        end,
+      },
+    }
+<
+
 ==============================================================================
 SYNCTEX                                                    *preview-synctex*