diff --git a/docs/plugins/mapper-attachments.asciidoc b/docs/plugins/mapper-attachments.asciidoc
index 2a53a1a4a99..f90c1ec9716 100644
--- a/docs/plugins/mapper-attachments.asciidoc
+++ b/docs/plugins/mapper-attachments.asciidoc
@@ -1,6 +1,8 @@
 [[mapper-attachments]]
 === Mapper Attachments Plugin
 
+deprecated[3.0.0,The `mapper-attachments` plugin has been replaced by the <<ingest-attachment, `ingest-attachment`>> plugin]
+
 The mapper attachments plugin lets Elasticsearch index file attachments in common formats (such as PPT, XLS, PDF)
 using the Apache text extraction library http://lucene.apache.org/tika/[Tika].
 
diff --git a/docs/plugins/mapper.asciidoc b/docs/plugins/mapper.asciidoc
index fcfc877f8f9..9d4fddc741b 100644
--- a/docs/plugins/mapper.asciidoc
+++ b/docs/plugins/mapper.asciidoc
@@ -10,8 +10,9 @@ The core mapper plugins are:
 
 <<mapper-attachments>>::
 
-The mapper-attachments integrates http://lucene.apache.org/tika/[Apache Tika] to provide a new field
-type `attachment` to allow indexing of documents such as PDFs and Microsoft Word.
+deprecated[3.0.0,The `mapper-attachments` plugin has been replaced by the <<ingest-attachment, `ingest-attachment`>> plugin]:
+The mapper-attachments integrates http://lucene.apache.org/tika/[Apache Tika] to provide a new field type `attachment`
+to allow indexing of documents such as PDFs and Microsoft Word.
 
 <<mapper-size>>::
 
diff --git a/docs/reference/migration/migrate_3_0.asciidoc b/docs/reference/migration/migrate_3_0.asciidoc
index 4732557c96c..a525ed3d7a0 100644
--- a/docs/reference/migration/migrate_3_0.asciidoc
+++ b/docs/reference/migration/migrate_3_0.asciidoc
@@ -445,6 +445,13 @@ cloud:
 
 Cloud GCE plugin has been renamed to {plugins}/discovery-gce.html[Discovery GCE plugin].
 
+
+==== Mapper Attachments plugin deprecated
+
+Mapper attachments has been deprecated. Users should use now the {plugins}/ingest-attachment.html[`ingest-attachment`]
+plugin.
+
+
 [[breaking_30_java_api_changes]]
 === Java API changes