diff --git a/docs/reference/analysis/tokenfilters/apostrophe-tokenfilter.asciidoc b/docs/reference/analysis/tokenfilters/apostrophe-tokenfilter.asciidoc
index f7f8761f610c9..ac64ef95423dc 100644
--- a/docs/reference/analysis/tokenfilters/apostrophe-tokenfilter.asciidoc
+++ b/docs/reference/analysis/tokenfilters/apostrophe-tokenfilter.asciidoc
@@ -1,5 +1,91 @@
 [[analysis-apostrophe-tokenfilter]]
-=== Apostrophe Token Filter
+=== Apostrophe token filter
+++++
+<titleabbrev>Apostrophe</titleabbrev>
+++++
 
-The `apostrophe` token filter strips all characters after an apostrophe,
-including the apostrophe itself.
+Strips all characters after an apostrophe, including the apostrophe itself.
+
+This filter is included in {es}'s built-in <<turkish-analyzer,Turkish language
+analyzer>>. It uses Lucene's
+https://lucene.apache.org/core/4_8_0/analyzers-common/org/apache/lucene/analysis/tr/ApostropheFilter.html[ApostropheFilter],
+which was built for the Turkish language.
+
+
+[[analysis-apostrophe-tokenfilter-analyze-ex]]
+==== Example
+
+The following <<indices-analyze,analyze API>> request demonstrates how the
+apostrophe token filter works.
+
+[source,console]
+--------------------------------------------------
+GET /_analyze
+{
+  "tokenizer" : "standard",
+  "filter" : ["apostrophe"],
+  "text" : "Istanbul'a veya Istanbul'dan"
+}
+--------------------------------------------------
+
+The filter produces the following tokens:
+
+[source,text]
+--------------------------------------------------
+[ Istanbul, veya, Istanbul ]
+--------------------------------------------------
+
+/////////////////////
+[source,console-result]
+--------------------------------------------------
+{
+  "tokens" : [
+    {
+      "token" : "Istanbul",
+      "start_offset" : 0,
+      "end_offset" : 10,
+      "type" : "<ALPHANUM>",
+      "position" : 0
+    },
+    {
+      "token" : "veya",
+      "start_offset" : 11,
+      "end_offset" : 15,
+      "type" : "<ALPHANUM>",
+      "position" : 1
+    },
+    {
+      "token" : "Istanbul",
+      "start_offset" : 16,
+      "end_offset" : 28,
+      "type" : "<ALPHANUM>",
+      "position" : 2
+    }
+  ]
+}
+--------------------------------------------------
+/////////////////////
+
+[[analysis-apostrophe-tokenfilter-analyzer-ex]]
+==== Add to an analyzer
+
+The following <<indices-create-index,create index API>> request uses the
+apostrophe token filter to configure a new 
+<<analysis-custom-analyzer,custom analyzer>>.
+
+[source,console]
+--------------------------------------------------
+PUT /apostrophe_example
+{
+    "settings" : {
+        "analysis" : {
+            "analyzer" : {
+                "standard_apostrophe" : {
+                    "tokenizer" : "standard",
+                    "filter" : ["apostrophe"]
+                }
+            }
+        }
+    }
+}
+--------------------------------------------------