Update Markdown re-indexing and document management

Clarified the management of stale documents during Markdown re-indexing and updated the workaround options for document deletion.

Author: mdonovanmsft

articles/search/search-how-to-index-markdown-blobs.md

@@ -444,24 +444,34 @@ The resulting search document in the index would look as follows:
 > These examples specify how to use these parsing modes entirely with or without field mappings, but you can leverage both in one scenario if that suits your needs.
 > 
 
-## Managing Stale Documents from Markdown Re-indexing
+## Managing stale documents from Markdown re-indexing
 
-When working with Markdown files in Azure AI Search, it's important to understand how deletions are handled during re-indexing. The indexer does not automatically delete previously indexed documents when a file is modified or sections are removed. This can lead to duplicate or stale documents remaining in the index.
+The indexer does not automatically delete previously indexed documents when a file is modified or sections are removed. This can lead to duplicate or stale documents remaining in the index.
 
 ### Behavior overview
 
 * **No automatic deletion**: If sections are removed from a Markdown file and the file is re-indexed, the indexer will overwrite existing documents with new ones. However, it does not delete documents that no longer correspond to any content in the updated file.
 * **Potential for duplicates**: This behavior can result in duplicate documents, especially in `oneToMany` parsing mode where each section becomes a separate document. This issue typically arises only when more Markdown sections are deleted than inserted between indexing runs. In such cases, the index retains documents from the previous version that no longer match any current content, leading to stale entries.
+
 ### Workaround options
 
 To ensure the index reflects the current state of your Markdown files, consider one of the following approaches:
 
-#### Option 1. Use the delete API
+#### Option 1. Soft delete with metadata
+This method uses a soft-delete to delete documents associated with a specific blob. See here for more information: [Change and delete detection using indexers for Azure Storage in Azure AI Search](search-howto-index-changed-deleted-blobs.md#soft-delete-strategy-using-custom-metadata):
+
+1. Mark the blob as deleted by setting a metadata field.
+2. Let the indexer run. It will delete all documents in the index associated with that blob.
+3. Remove the soft-delete marker and re-index the file.
+     
+#### Option 2. Use the delete API
+
+Before re-indexing a modified Markdown file, explicitly delete the existing documents associated with that file using the [https://learn.microsoft.com/en-us/rest/api/searchservice/delete-documents](https://learn.microsoft.com/en-us/rest/api/searchservice/preview-api/add-update-delete-documents). You can either:
+
+* Manually indentify individual stale documents by identifying duplicates in the index to be deleted.
+* (**Recommended**) Bulk delete all documents generated from the same parent file before re-indexing.
 
-Before re-indexing a modified Markdown file, explicitly delete the existing documents associated with that file using the https://learn.microsoft.com/en-us/rest/api/searchservice/delete-documents.
-Steps:
-  
-  1. Identify the id  of the documents associated with the file. Use a query like the one below to retrieve the document IDs (e.g., `id`, `chunk_id`, etc.) for all documents tied to a specific file. Replace `metadata_storage_path` with the appropriate field in your index that maps to the file path or blob URI.
+  1. Identify the id  of the documents associated with the file. Use a query like the one below to retrieve the document key IDs (e.g., `id`, `chunk_id`, etc.) for all documents tied to a specific file. Replace `metadata_storage_path` with the appropriate field in your index that maps to the file path or blob URI. Note that this field must be a key.
   ```
   GET https://<search-service>.search.windows.net/indexes/<index-name>/docs?api-version=2025-05-01-preview
   Content-Type: application/json
@@ -472,15 +482,27 @@ Steps:
       "select": "id"
   }
 ```
-  2. Issue a delete request for those documents.
-  3. Re-index the updated file.
-     
-#### Option 2. Soft delete with metadata
-If identifying stale documents in the index is difficult, you can use a soft-delete approach:
 
-1. Mark the blob as deleted by setting a metadata field (e.g., deleted=true).
-2. Let the indexer run. It will delete all documents in the index associated with that blob.
-3. Remove the soft-delete marker and re-index the file.
+  2. Issue a delete request for the documents with the identified keys.
+  ```
+  GET https://<search-service>.search.windows.net/indexes/<index-name>/docs?api-version=2025-05-01-preview
+  Content-Type: application/json
+  api-key: [admin key]
+
+{  
+  "value": [  
+    {  
+      "@search.action": "delete",  
+      "id": "aHR0c...jI1"  
+    },
+    {  
+      "@search.action": "delete",  
+      "id": "aHR0...MQ2"  
+    }  
+  ]  
+}
+```
+  3. Re-index the updated file.
 
 ## Next steps