diff options
| -rw-r--r-- | docs/content/en/content-management/front-matter.md | 3 | ||||
| -rw-r--r-- | docs/content/en/content-management/summaries.md | 23 | ||||
| -rw-r--r-- | docs/content/en/variables/page.md | 2 |
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><!--more--></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><!--more--></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><!--more--></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><!--more--></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><!--more--></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. |