Skip to content
Permalink
Browse files

docs: Add information about summary front matter variable

  • Loading branch information...
mcdee authored and bep committed Apr 5, 2019
1 parent 3a62d54 commit ed65bda3b43f6149e41ddb049cbb295a82473bc9
@@ -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.

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

0 comments on commit ed65bda

Please sign in to comment.
You can’t perform that action at this time.