aboutsummaryrefslogtreecommitdiffhomepage
diff options
context:
space:
mode:
authorJim McDonald <[email protected]>2019-04-05 23:17:54 +0100
committerBjørn Erik Pedersen <[email protected]>2019-04-06 00:17:54 +0200
commited65bda3b43f6149e41ddb049cbb295a82473bc9 (patch)
tree97183deae11eba57f65edb57b48cca04d35496dc
parent3a62d54745e2cbfda6772390830042908d725c71 (diff)
downloadhugo-ed65bda3b43f6149e41ddb049cbb295a82473bc9.tar.gz
hugo-ed65bda3b43f6149e41ddb049cbb295a82473bc9.zip
docs: Add information about summary front matter variable
-rw-r--r--docs/content/en/content-management/front-matter.md3
-rw-r--r--docs/content/en/content-management/summaries.md23
-rw-r--r--docs/content/en/variables/page.md2
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.