docs: Add information about summary front matter variable

3 files changed, 27 insertions, 1 deletions

diff --git a/docs/content/en/content-management/front-matter.md b/docs/content/en/content-management/front-matter.md
index 130160917..4a52b160c 100644
--- a/docs/content/en/content-management/front-matter.md
+++ b/docs/content/en/content-management/front-matter.md
@@ -111,6 +111,9 @@ series
 slug
 : appears as the tail of the output URL. A value specified in front matter will override the segment of the URL based on the filename.
 
+summary
+: text used when providing a summary of the article in the `.Summary` page variable; details available in the [content-summaries](/content-management/summaries/) section.
+
 title
 : the title for the content.
 
diff --git a/docs/content/en/content-management/summaries.md b/docs/content/en/content-management/summaries.md
index 63d64aa3c..dcbf5914d 100644
--- a/docs/content/en/content-management/summaries.md
+++ b/docs/content/en/content-management/summaries.md
@@ -23,6 +23,7 @@ With the use of the `.Summary` [page variable][pagevariables], Hugo generates su
 
 * Automatic Summary Split
 * Manual Summary Split
+* Front Matter Summary
 
 It is natural to accompany the summary with links to the original content, and a common design pattern is to see this link in the form of a "Read More ..." button. See the `.RelPermalink`, `.Permalink`, and `.Truncated` [page variables][pagevariables].
 
@@ -60,6 +61,28 @@ Cons
 Be careful to enter <code>&#60;&#33;&#45;&#45;more&#45;&#45;&#62;</code> exactly; i.e., all lowercase and with no whitespace.
 {{% /warning %}}
 
+### Front Matter Summary
+
+You might want your summary to be something other than the text that starts the article.  In this case you can provide a separate summary in the `summary` variable of the article front matter.
+
+Pros
+: Complete freedom of text independent of the content of the article.  Markup can be used within the summary.
+
+Cons
+: Extra work for content authors as they need to write an entirely separate piece of text as the summary of the article.
+
+## Summary Selection Order
+
+Because there are multiple ways in which a summary can be specified it is useful to understand the order of selection Hugo follows when deciding on the text to be returned by `.Summary`.  It is as follows:
+
+1. If there is a <code>&#60;&#33;&#45;&#45;more&#45;&#45;&#62;</code> summary divider present in the article the text up to the divider will be provided as per the manual summary split method
+2. If there is a `summary` variable in the article front matter the value of the variable will be provided as per the front matter summary method
+3. The text at the start of the article will be provided as per the automatic summary split method
+
+{{% warning "Competing selections" %}}
+Hugo uses the _first_ of the above steps that returns text.  So if, for example, your article has both `summary` variable in its front matter and a <code>&#60;&#33;&#45;&#45;more&#45;&#45;&#62;</code> summary divider Hugo will use the manual summary split method.
+{{% /warning %}}
+
 ## Example: First 10 Articles with Summaries
 
 You can show content summaries with the following code. You could use the following snippet, for example, in a [section template][].
diff --git a/docs/content/en/variables/page.md b/docs/content/en/variables/page.md
index c4ddc8200..c8ca5ac83 100644
--- a/docs/content/en/variables/page.md
+++ b/docs/content/en/variables/page.md
@@ -153,7 +153,7 @@ http://remarkjs.com)
 : returns the site for the first language. If this is not a multilingual setup, it will return itself.
 
 .Summary
-: a generated summary of the content for easily showing a snippet in a summary view. The breakpoint can be set manually by inserting <code>&lt;!&#x2d;&#x2d;more&#x2d;&#x2d;&gt;</code> at the appropriate place in the content page. See [Content Summaries](/content-management/summaries/) for more details.
+: a generated summary of the content for easily showing a snippet in a summary view. The breakpoint can be set manually by inserting <code>&lt;!&#x2d;&#x2d;more&#x2d;&#x2d;&gt;</code> at the appropriate place in the content page, or the summary can be written independent of the page text.  See [Content Summaries](/content-management/summaries/) for more details.
 
 .TableOfContents
 : the rendered [table of contents](/content-management/toc/) for the page.