From eef668b7918e90c8539ac6a222fdb1a334c0a10b Mon Sep 17 00:00:00 2001
From: Ndianabasi Udonkang <ndianabasi@furnish.ng>
Date: Mon, 4 Nov 2024 11:47:09 +0100
Subject: [PATCH] docs: document the `persistentFileNames` option

---
 README.md | 31 ++++++++++++++++++++++++++++++-
 1 file changed, 30 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 1eb3372..8ff87f7 100644
--- a/README.md
+++ b/README.md
@@ -533,7 +533,36 @@ A responsive format with blurhash looks like this:
 }
 ```
 
-Note that when blurhash is disabled, the `blurhash` property will be `undefined` before serialisation and missing after serialisation.
+> [!TIP]
+> When blurhash is disabled, the `blurhash` property will be `undefined` before serialisation and missing after serialisation.
+
+### 12. The `persistentFileNames` Option
+
+When enabled, the `persistentFileNames` option ensures that filenames of attachments remain constant across updates. This is very useful for public images such as OG images for websites where the names of the images should remain constant across updates to avoid breaking previews of your contents across platforms where they have been previously shared.
+
+```ts
+class Post extends BaseModel {
+  @responsiveAttachment({persistentFileNames: true, folder: 'post_images'})
+  public ogImage: ResponsiveAttachmentContract
+}
+
+const post = await Post.findOrFail(123)
+post.ogImage = await ResponsiveAttachment.fromBuffer(ogImageBuffer1, `post_${post.id}`)
+await post.save()
+await post.refresh()
+
+assert.equal(post.ogImage.name, 'post_images/original_post_123.jpg') // true
+
+post.ogImage = await ResponsiveAttachment.fromBuffer(ogImageBuffer2, `post_${post.id}`)
+await post.save()
+await post.refresh()
+
+assert.equal(post.ogImage.name, 'post_images/original_post_123.jpg') // true
+assert.isTrue(await Drive.exists(post.ogImage.name)) // true
+```
+
+> [!TIP]
+> When composing the folder and/or file names for persistent attachments ensure you use attributes of the resources which will not change such as the `id`.
 
 ## Generating URLs