feat: Allow specifying the overwrite mode for singlefile archives. Fixes #1125

1 files changed, 16 insertions, 0 deletions

diff --git a/docs/docs/14-Guides/03-singlefile.md b/docs/docs/14-Guides/03-singlefile.md
index bc4acb64..c0f4e174 100644
--- a/docs/docs/14-Guides/03-singlefile.md
+++ b/docs/docs/14-Guides/03-singlefile.md
@@ -11,9 +11,25 @@ Karakeep supports being a destination for the [SingleFile extension](https://git
 5. In the `authorization token` field, paste an API key that you can get from your karakeep settings.
 6. Set `data field name` to `file`.
 7. Set `URL field name` to `url`.
+8. (Optional) Add `&ifexists=MODE` to the URL where MODE is one of `skip`, `overwrite`, `overwrite-recrawl`, `append`, or `append-recrawl`. See "Handling Existing Bookmarks" section below for details.
 
 Now, go to any page and click the singlefile extension icon. Once it's done with the upload, the bookmark should show up in your karakeep instance. Note that the singlefile extension doesn't show any progress on the upload. Given that archives are typically large, it might take 30+ seconds until the upload is done and starts showing up in Karakeep.
 
+## Handling Existing Bookmarks
+
+When uploading a page that already exists in your archive (same URL), you can control the behavior by setting the `ifexists` query parameter in the upload URL. The available modes are:
+
+- `skip` (default): If the bookmark already exists, skip creating a new one
+- `overwrite`: Replace existing precrawled archive (only the most recent archive is kept)
+- `overwrite-recrawl`: Replace existing archive and queue a recrawl to update content
+- `append`: Add new archive version alongside existing ones
+- `append-recrawl`: Add new archive and queue a recrawl
+
+To use these modes, append `?ifexists=MODE` to your upload URL, replacing `MODE` with your desired behavior.
+
+For example:  
+`https://YOUR_SERVER_ADDRESS/api/v1/bookmarks/singlefile?ifexists=overwrite`
+
 
 ## Recommended settings