diff options
Diffstat (limited to 'content/en/content-management')
| -rw-r--r-- | content/en/content-management/archetypes.md | 2 | ||||
| -rw-r--r-- | content/en/content-management/comments.md | 2 | ||||
| -rw-r--r-- | content/en/content-management/formats.md | 2 | ||||
| -rw-r--r-- | content/en/content-management/menus.md | 3 | ||||
| -rw-r--r-- | content/en/content-management/related.md | 106 | ||||
| -rw-r--r-- | content/en/content-management/summaries.md | 30 |
6 files changed, 73 insertions, 72 deletions
diff --git a/content/en/content-management/archetypes.md b/content/en/content-management/archetypes.md index 904ca8c31..ff4a2d783 100644 --- a/content/en/content-management/archetypes.md +++ b/content/en/content-management/archetypes.md @@ -35,7 +35,7 @@ The above will create a new content file in `content/posts/my-first-post.md` usi 3. `themes/my-theme/archetypes/posts.md` 4. `themes/my-theme/archetypes/default.md` -The last two list items is only applicable if you use a theme and it uses the `my-theme` theme name as an example. +The last two list items are only applicable if you use a theme and it uses the `my-theme` theme name as an example. ## Create a New Archetype Template diff --git a/content/en/content-management/comments.md b/content/en/content-management/comments.md index 268dc4c0e..17914ba2c 100644 --- a/content/en/content-management/comments.md +++ b/content/en/content-management/comments.md @@ -59,7 +59,7 @@ There are a few alternatives to commenting on static sites for those who do not * [Muut](http://muut.com/) * [isso](http://posativ.org/isso/) (Self-hosted, Python) * [Tutorial on Implementing Isso with Hugo][issotutorial] - +* [Utterances](https://utteranc.es/) (Open source, Github comments widget built on Github issues) <!-- I don't think this is worth including in the documentation since it seems that Steve is no longer supporting or developing this project. rdwatters - 2017-02-29.--> <!-- * [Kaiju](https://github.com/spf13/kaiju) --> diff --git a/content/en/content-management/formats.md b/content/en/content-management/formats.md index ab9fdd781..f7a466c3c 100644 --- a/content/en/content-management/formats.md +++ b/content/en/content-management/formats.md @@ -240,7 +240,7 @@ Markdown syntax is simple enough to learn in a single sitting. The following are [mdcheatsheet]: https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet [mdguide]: https://www.markdownguide.org/ [mdtutorial]: http://www.markdowntutorial.com/ -[Miek Gieben's website]: https://miek.nl/2016/March/05/mmark-syntax-document/ +[Miek Gieben's website]: https://miek.nl/2016/march/05/mmark-syntax-document/ [mmark]: https://github.com/miekg/mmark [mmarkgh]: https://github.com/miekg/mmark/wiki/Syntax [org]: http://orgmode.org/ diff --git a/content/en/content-management/menus.md b/content/en/content-management/menus.md index 4278b03be..bc48c82e7 100644 --- a/content/en/content-management/menus.md +++ b/content/en/content-management/menus.md @@ -80,7 +80,7 @@ You can also add entries to menus that aren’t attached to a piece of content. Here’s an example snippet pulled from a configuration file: -{{< code-toggle file="config.toml" >}} +{{< code-toggle file="config" >}} [[menu.main]] name = "about hugo" pre = "<i class='fa fa-heart'></i>" @@ -90,6 +90,7 @@ Here’s an example snippet pulled from a configuration file: [[menu.main]] name = "getting started" pre = "<i class='fa fa-road'></i>" + post = "<span class='alert'>New!</span>" weight = -100 url = "/getting-started/" {{< /code-toggle >}} diff --git a/content/en/content-management/related.md b/content/en/content-management/related.md index 9a4c77d40..636e95970 100644 --- a/content/en/content-management/related.md +++ b/content/en/content-management/related.md @@ -14,13 +14,13 @@ aliases: [/content/related/,/related/] toc: true --- -{{% note %}} -We currently do not index **Page content**. We thought we would release something that will make most people happy before we start solving [Sherlock's last case](https://github.com/joearms/sherlock). -{{% /note %}} + +Hugo uses a set of factors to identify a page's related content based on Front Matter parameters. This can be tuned to the desired set of indices and parameters or left to Hugo's default [Related Content configuration](#configure-related-content). ## List Related Content -To list up to 5 related pages is as simple as including something similar to this partial in your single page template: + +To list up to 5 related pages (which share the same _date_ or _keyword_ parameters) is as simple as including something similar to this partial in your single page template: {{< code file="layouts/partials/related.html" >}} {{ $related := .Site.RegularPages.Related . | first 5 }} @@ -34,67 +34,62 @@ To list up to 5 related pages is as simple as including something similar to thi {{ end }} {{< /code >}} +### Methods -{{% note %}} -Read [this blog article](https://regisphilibert.com/blog/2018/04/hugo-optmized-relashionships-with-related-content/) for a great explanation of more advanced usage of this feature. -{{% /note %}} +Here is the list of "Related" methods available on a page collection such `.RegularPages`. -The full set of methods available on the page lists can be seen in this Go interface: +#### .Related PAGE +Returns a collection of pages related the given one. -```go -// A PageGenealogist finds related pages in a page collection. This interface is implemented -// by Pages and PageGroup, which makes it available as `{{ .RegularPages.Related . }}` etc. -type PageGenealogist interface { +``` +{{ $related := .RegularPages.Related . }} +``` - // Template example: - // {{ $related := .RegularPages.Related . }} - Related(doc related.Document) (Pages, error) +#### .RelatedIndices PAGE INDICE1 [INDICE2 ...] +Returns a collection of pages related to a given one restricted to a list of indices. - // Template example: - // {{ $related := .RegularPages.RelatedIndices . "tags" "date" }} - RelatedIndices(doc related.Document, indices ...interface{}) (Pages, error) +``` +{{ $related := .RegularPages.RelatedIndices . "tags" "date" }} +``` + +#### .RelatedTo KEYVALS [KEYVALS2 ...] +Returns a collection of pages related together by a set of indices and their match. - // Template example: - // {{ $related := .RegularPages.RelatedTo ( keyVals "tags" "hugo" "rocks") ( keyVals "date" .Date ) }} - RelatedTo(args ...types.KeyValues) (Pages, error) -} +In order to build those set and pass them as argument, one must use the `keyVals` function where the first agrument would be the `indice` and the consective ones its potential `matches`. + +``` +{{ $related := .RegularPages.RelatedTo ( keyVals "tags" "hugo" "rocks") ( keyVals "date" .Date ) }} ``` + +{{% note %}} +Read [this blog article](https://regisphilibert.com/blog/2018/04/hugo-optmized-relashionships-with-related-content/) for a great explanation of more advanced usage of this feature. +{{% /note %}} + ## Configure Related Content Hugo provides a sensible default configuration of Related Content, but you can fine-tune this in your configuration, on the global or language level if needed. +### Default configuration + +Without any `related` configuration set on the project, Hugo's Related Content methods will use the following. + +```yaml +related: + threshold: 80 + includeNewer: false + toLower: false + indices: + - name: keywords + weight: 100 + - name: date + weight: 10 +``` + +Custom configuration should be set using the same syntax. + {{% note %}} If you add a `related` config section, you need to add a complete configuration. It is not possible to just set, say, `includeNewer` and use the rest from the Hugo defaults. {{% /note %}} -Below is a sample `config.toml` section: - -``` -[related] - -# Only include matches with rank >= threshold. This is a normalized rank between 0 and 100. -threshold = 80 - -# To get stable "See also" sections we, by default, exclude newer related pages. -includeNewer = false - -# Will lower case keywords in both queries and in the indexes. -toLower = false - -[[related.indices]] -name = "keywords" -weight = 150 -[[related.indices]] -name = "author" -toLower = true -weight = 30 -[[related.indices]] -name = "tags" -weight = 100 -[[related.indices]] -name = "date" -weight = 10 -pattern = "2006" -``` ### Top Level Config Options threshold @@ -135,9 +130,6 @@ He should now be able to add an improved version of that "Related Content" secti * If you don't use any of the `Related` methods, you will not use the Relate Content feature, and performance will be the same as before. * Calling `.RegularPages.Related` etc. will create one inverted index, also sometimes named posting list, that will be reused for any lookups in that same page collection. Doing that in addition to, as an example, calling `.Pages.Related` will work as expected, but will create one additional inverted index. This should still be very fast, but worth having in mind, especially for bigger sites. - - - - - - +{{% note %}} +We currently do not index **Page content**. We thought we would release something that will make most people happy before we start solving [Sherlock's last case](https://github.com/joearms/sherlock). +{{% /note %}} diff --git a/content/en/content-management/summaries.md b/content/en/content-management/summaries.md index 0f8939377..63d64aa3c 100644 --- a/content/en/content-management/summaries.md +++ b/content/en/content-management/summaries.md @@ -21,32 +21,40 @@ With the use of the `.Summary` [page variable][pagevariables], Hugo generates su ## Summary Splitting Options -* Hugo-defined Summary Split -* User-defined Summary Split +* Automatic Summary Split +* Manual Summary Split 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]. -### Hugo-defined: Automatic Summary Splitting +### Automatic Summary Splitting -By default, Hugo automatically takes the first 70 words of your content as its summary and stores it into the `.Summary` page variable for use in your templates. Taking the Hugo-defined approach to summaries may save time, but it has pros and cons: +By default, Hugo automatically takes the first 70 words of your content as its summary and stores it into the `.Summary` page variable for use in your templates. You may customize the summary length by setting `summaryLength` in your [site configuration](/getting-started/configuration/). -* **Pros:** Automatic, no additional work on your part. -* **Cons:** All HTML tags are stripped from the summary, and the first 70 words, whether they belong to a heading or to different paragraphs, are all put into one paragraph. +{{% note %}} +You can customize how HTML tags in the summary are loaded using functions such as `plainify` and `safeHTML`. +{{% /note %}} {{% note %}} -The Hugo-defined summaries are set to use word count calculated by splitting the text by one or more consecutive white space characters. If you are creating content in a `CJK` language and want to use Hugo's automatic summary splitting, set `hasCJKLanguage` to `true` in you [site configuration](/getting-started/configuration/). +The Hugo-defined summaries are set to use word count calculated by splitting the text by one or more consecutive whitespace characters. If you are creating content in a `CJK` language and want to use Hugo's automatic summary splitting, set `hasCJKLanguage` to `true` in your [site configuration](/getting-started/configuration/). {{% /note %}} -### User-defined: Manual Summary Splitting +### Manual Summary Splitting + +Alternatively, you may add the <code><!--more--></code> summary divider where you want to split the article. -Alternatively, you may add the <code><!--more--></code> summary divider where you want to split the article. For [org content][org], use `# more` where you want to split the article. Content that comes before the summary divider will be used as that content's summary and stored in the `.Summary` page variable with all HTML formatting intact. +For [Org mode content][org], use `# more` where you want to split the article. + +Content that comes before the summary divider will be used as that content's summary and stored in the `.Summary` page variable with all HTML formatting intact. {{% note "Summary Divider"%}} The concept of a *summary divider* is not unique to Hugo. It is also called the "more tag" or "excerpt separator" in other literature. {{% /note %}} -* Pros: Freedom, precision, and improved rendering. All HTML tags and formatting are preserved. -* Cons: Extra work for content authors, since they need to remember to type <code><!--more--></code> (or `# more` for [org content][org]) in each content file. This can be automated by adding the summary divider below the front matter of an [archetype](/content-management/archetypes/). +Pros +: Freedom, precision, and improved rendering. All HTML tags and formatting are preserved. + +Cons +: Extra work for content authors, since they need to remember to type <code><!--more--></code> (or `# more` for [org content][org]) in each content file. This can be automated by adding the summary divider below the front matter of an [archetype](/content-management/archetypes/). {{% warning "Be Precise with the Summary Divider" %}} Be careful to enter <code><!--more--></code> exactly; i.e., all lowercase and with no whitespace. |