docs: Add information about summary front matter variable

This commit is contained in:
Jim McDonald 2019-04-05 23:17:54 +01:00 committed by Bjørn Erik Pedersen
parent 3a62d54745
commit ed65bda3b4
3 changed files with 27 additions and 1 deletions

View file

@ -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.

View file

@ -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][].

View file

@ -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.