mirror/hugo
1
0
Fork 0
mirror of https://github.com/gohugoio/hugo.git synced 2025-08-21 21:35:28 +02:00
Code Issues Packages Projects Releases Wiki Activity

Merge commit '07b8d9466dfb59c429c1b470a0443337bc0aeefe'

Browse Source
This commit is contained in:
Bjørn Erik Pedersen
2021-04-20 20:22:53 +02:00
parent d3a64708f4 07b8d9466d
commit 8f7891e70c
64 changed files with 250 additions and 507 deletions
Download Patch File Download Diff File Expand all files Collapse all files

182
docs/content/en/content-management/authors.md
View File

@@ -1,182 +0,0 @@
---
title: Authors
linktitle: Authors
description:
date: 2016-08-22
publishdate: 2017-03-12
lastmod: 2017-03-12
keywords: [authors]
categories: ["content management"]
menu:
docs:
parent: "content-management"
weight: 55
weight: 55 #rem
draft: true
aliases: [/content/archetypes/]
toc: true
comments: Before this page is published, need to also update both site- and page-level variables documentation.
---
Larger sites often have multiple content authors. Hugo provides standardized author profiles to organize relationships between content and content creators for sites operating under a distributed authorship model.
## Author Profiles
You can create a profile containing metadata for each author on your website. These profiles have to be saved under `data/_authors/`. The filename of the profile will later be used as an identifier. This way Hugo can associate content with one or multiple authors. An author's profile can be defined in the JSON, YAML, or TOML format.
### Example: Author Profile
Let's suppose Alice Allison is a blogger. A simple unique identifier would be `alice`. Now, we have to create a file called `alice.toml` in the `data/_authors/` directory. The following example is the standardized template written in TOML:
{{< code file="data/_authors/alice.toml" >}}
givenName = "Alice" # or firstName as alias
familyName = "Allison" # or lastName as alias
displayName = "Alice Allison"
thumbnail = "static/authors/alice-thumb.jpg"
image = "static/authors/alice-full.jpg"
shortBio = "My name is Alice and I'm a blogger."
bio = "My name is Alice and I'm a blogger... some other stuff"
email = "alice.allison@email.com"
weight = 10
[social]
facebook = "alice.allison"
twitter = "alice"
website = "www.example.com"
[params]
random = "whatever you want"
{{< /code >}}
All variables are optional but it's advised to fill all important ones (e.g. names and biography) because themes can vary in their usage.
You can store files for the `thumbnail` and `image` attributes in the `static` folder. Then add the path to the photos relative to `static`; e.g., `/static/path/to/thumbnail.jpg`.
`weight` allows you to define the order of an author in an `.Authors` list and can be accessed on list or via the `.Site.Authors` variable.
The `social` section contains all the links to the social network accounts of an author. Hugo is able to generate the account links for the most popular social networks automatically. This way, you only have to enter your username. You can find a list of all supported social networks [here](#linking-social-network-accounts-automatically). All other variables, like `website` in the example above remain untouched.
The `params` section can contain arbitrary data much like the same-named section in the config file. What it contains is up to you.
## Associate Content Through Identifiers
Earlier it was mentioned that content can be associated with an author through their corresponding identifier. In our case, blogger Alice has the identifier `alice`. In the front matter of a content file, you can create a list of identifiers and assign it to the `authors` variable. Here are examples for `alice` using YAML and TOML, respectively.
```
---
title: Why Hugo is so Awesome
date: 2016-08-22T14:27:502:00
authors: ["alice"]
---
Nothing to read here. Move along...
```
```
+++
title = Why Hugo is so Awesome
date = "2016-08-22T14:27:502:00"
authors: ["alice"]
+++
Nothing to read here. Move along...
```
Future authors who might work on this blog post can append their identifiers to the `authors` array in the front matter as well.
## Work with Templates
After a successful setup it's time to give some credit to the authors by showing them on the website. Within the templates Hugo provides a list of the author's profiles if they are listed in the `authors` variable within the front matter.
The list is accessible via the `.Authors` template variable. Printing all authors of a the blog post is straight forward:
```
{{ range .Authors }}
{{ .DisplayName }}
{{ end }}
=> Alice Allison
```
Even if there are co-authors you may only want to show the main author. For this case you can use the `.Author` template variable **(note the singular form)**. The template variable contains the profile of the author that is first listed with his identifier in the front matter.
{{% note %}}
You can find a list of all template variables to access the profile information in [Author Variables](/variables/authors/).
{{% /note %}}
### Link Social Network Accounts
As aforementioned, Hugo is able to generate links to profiles of the most popular social networks. The following social networks with their corresponding identifiers are supported: `github`, `facebook`, `twitter`, `pinterest`, `instagram`, `youtube` and `linkedin`.
This is can be done with the `.Social.URL` function. Its only parameter is the name of the social network as they are defined in the profile (e.g. `facebook`, `twitter`). Custom variables like `website` remain as they are.
Most articles feature a small section with information about the author at the end. Let's create one containing the author's name, a thumbnail, a (summarized) biography and links to all social networks:
{{< code file="layouts/partials/author-info.html" download="author-info.html" >}}
{{ with .Author }}
<h3>{{ .DisplayName }}</h3>
<img src="{{ .Thumbnail | absURL }}" alt="{{ .DisplayName }}">
<p>{{ .ShortBio }}</p>
<ul>
{{ range $network, $username := .Social }}
<li><a href="{{ $.Author.Social.URL $network }}">{{ $network }}</a></li>
{{ end }}
</ul>
{{ end }}
{{< /code >}}
## Who Published What?
That question can be answered with a list of all authors and another list containing all articles that they each have written. Now we have to translate this idea into templates. The [taxonomy][] feature allows us to logically group content based on information that they have in common; e.g. a tag or a category. Well, many articles share the same author, so this should sound familiar, right?
In order to let Hugo know that we want to group content based on their author, we have to create a new taxonomy called `author` (the name corresponds to the variable in the front matter). Here is the snippet in a `config.yaml` and `config.toml`, respectively:
```
taxonomies:
author: authors
```
```
[taxonomies]
author = "authors"
```
### List All Authors
In the next step we can create a template to list all authors of your website. Later, the list can be accessed at `www.example.com/authors/`. Create a new template in the `layouts/taxonomy/` directory called `authors.term.html`. This template will be exclusively used for this taxonomy.
{{< code file="layouts/taxonomy/author.term.html" download="author.term.html" >}}
<ul>
{{ range $author, $v := .Data.Terms }}
{{ $profile := $.Authors.Get $author }}
<li>
<a href="{{ printf "%s/%s/" $.Data.Plural $author | absURL }}">
{{ $profile.DisplayName }} - {{ $profile.ShortBio }}
</a>
</li>
{{ end }}
</ul>
{{< /code >}}
`.Data.Terms` contains the identifiers of all authors and we can range over it to create a list with all author names. The `$profile` variable gives us access to the profile of the current author. This allows you to generate a nice info box with a thumbnail, a biography and social media links, like at the [end of a blog post](#linking-social-network-accounts-automatically).
### List Each Author's Publications
Last but not least, we have to create the second list that contains all publications of an author. Each list will be shown in its own page and can be accessed at `www.example.com/authors/<IDENTIFIER>`. Replace `<IDENTIFIER>` with a valid author identifier like `alice`.
The layout for this page can be defined in the template `layouts/taxonomy/author.html`.
{{< code file="layouts/taxonomy/author.html" download="author.html" >}}
{{ range .Pages }}
<h2><a href="{{ .Permalink }}">{{ .Title }}</a></h2>
<span>written by {{ .Author.DisplayName }}</span>
{{ .Summary }}
{{ end }}
{{< /code >}}
The example above generates a simple list of all posts written by a single author. Inside the loop you've access to the complete set of [page variables][pagevars]. Therefore, you can add additional information about the current posts like the publishing date or the tags.
With a lot of content this list can quickly become very long. Consider to use the [pagination][] feature. It splits the list into smaller chunks and spreads them over multiple pages.
[pagevars]: /variables/page/
[pagination]: /templates/pagination/

30
docs/content/en/content-management/multilingual.md
View File

@@ -77,9 +77,9 @@ Only the obvious non-global options can be overridden per language. Examples of
You can disable one or more languages. This can be useful when working on a new translation.
```toml
{{< code-toggle file="config" >}}
disableLanguages = ["fr", "ja"]
```
{{< /code-toggle >}}
Note that you cannot disable the default content language.
@@ -330,12 +330,12 @@ From within your templates, use the `i18n` function like this:
{{ i18n "home" }}
```
The function will search for the `"home"` id from `i18n/en-US.toml` file:
The function will search for the `"home"` id:
```
{{< code-toggle file="i18n/en-US" >}}
[home]
other = "Home"
```
{{< /code-toggle >}}
The result will be
@@ -345,18 +345,18 @@ Home
### Query a flexible translation with variables
Often you will want to use to the page variables in the translations strings. To do that, pass on the `.` context when calling `i18n`:
Often you will want to use the page variables in the translation strings. To do so, pass the `.` context when calling `i18n`:
```
{{ i18n "wordCount" . }}
```
The function will pass the `.` context to the `"wordCount"` id in `i18n/en-US.toml` file:
The function will pass the `.` context to the `"wordCount"` id:
```
{{< code-toggle file="i18n/en-US" >}}
[wordCount]
other = "This article has {{ .WordCount }} words."
```
{{< /code-toggle >}}
Assume `.WordCount` in the context has value is 101. The result will be:
@@ -372,13 +372,13 @@ In order to meet singular/plural requirement, you must pass a dictionary (map) w
{{ i18n "readingTime" .ReadingTime }}
```
The function will read `.Count` from `.ReadingTime` and evaluate where the number is singular (`one`) or plural (`other`). After that, it will pass to `readingTime` id in `i18n/en-US.toml` file:
The function will read `.Count` from `.ReadingTime` and evaluate where the number is singular (`one`) or plural (`other`). After that, it will pass to `readingTime` id:
```
{{< code-toggle file="i18n/en-US" >}}
[readingTime]
one = "One minute to read"
other = "{{.Count}} minutes to read"
```
{{< /code-toggle >}}
Assume `.ReadingTime.Count` in the context has value of 525600. The result will be:
@@ -389,7 +389,7 @@ Assume `.ReadingTime.Count` in the context has value of 525600. The result will
If `.ReadingTime.Count` in the context has value is 1. The result is:
```
One minutes to read
One minute to read
```
In case you need to pass custom data: (`(dict "Count" 25)` is minimum requirement)
@@ -433,7 +433,7 @@ This technique extracts the day, month and year by specifying ``.Date.Day``, ``.
You can define your menus for each language independently. Creating multilingual menus works just like [creating regular menus][menus], except they're defined in language-specific blocks in the configuration file:
```
{{< code-toggle file="config" >}}
defaultContentLanguage = "en"
[languages.en]
@@ -454,7 +454,7 @@ languageName = "Deutsch"
url = "/"
name = "Startseite"
weight = 0
```
{{< /code-toggle >}}
The rendering of the main navigation works as usual. `.Site.Menus` will just contain the menu in the current language. Note that `absLangURL` below will link to the correct locale of your website. Without it, menu entries in all languages would link to the English version, since it's the default content language that resides in the root directory.

2
docs/content/en/content-management/organization/index.md
View File

@@ -33,7 +33,7 @@ The bundle documentation is **work in progress**. We will publish more comprehen
{{% /note %}}
# Organization of Content Source
## Organization of Content Source
In Hugo, your content should be organized in a manner that reflects the rendered website.

30
docs/content/en/content-management/page-resources.md
View File

@@ -1,6 +1,6 @@
---
title : "Page Resources"
description : "Page Resources -- images, other pages, documents etc. -- have page-relative URLs and their own metadata."
description : "Page resources -- images, other pages, documents, etc. -- have page-relative URLs and their own metadata."
date: 2018-01-24
categories: ["content management"]
keywords: [bundle,content,resources]
@@ -13,10 +13,32 @@ menu:
parent: "content-management"
weight: 31
---
Page resources are only accessible from [page bundles]({{< relref
"/content-management/page-bundles" >}}), those directories with `index.md` or
`_index.md` files at their root. Page resources are only available to the
page with which they are bundled.
Page resources are available for [page bundles]({{< relref "/content-management/page-bundles" >}}) only,
i.e. a directory with either a `index.md`, or `_index.md` file at its root. Resources are only attached to
the lowest page they are bundled with, and simple which names does not contain `index.md` are not attached any resource.
In this example, `first-post` is a page bundle with access to 10 page resources including audio, data, documents, images, and video. Although `second-post` is also a page bundle, it has no page resources and is unable to directly access the page resources associated with `first-post`.
```text
content
└── post
├── first-post
│ ├── images
│ │ ├── a.jpg
│ │ ├── b.jpg
│ │ └── c.jpg
│ ├── index.md (root of page bundle)
│ ├── latest.html
│ ├── manual.json
│ ├── notice.md
│ ├── office.mp3
│ ├── pocket.mp4
│ ├── rating.pdf
│ └── safety.txt
└── second-post
└── index.md (root of page bundle)
```
## Properties

6
docs/content/en/content-management/shortcodes.md
View File

@@ -64,7 +64,7 @@ and a new line with a "quoted string".` */>}}
### Shortcodes with Markdown
In Hugo `0.55` we changed how the `%` delimiter works. Shortcodes using the `%` as the outer-most delimiter will now be fully rendered when sent to the content renderer (e.g. Blackfriday for Markdown), meaning they can be part of the generated table of contents, footnotes, etc.
In Hugo `0.55` we changed how the `%` delimiter works. Shortcodes using the `%` as the outer-most delimiter will now be fully rendered when sent to the content renderer. They can be part of the generated table of contents, footnotes, etc.
If you want the old behavior, you can put the following line in the start of your shortcode template:
@@ -302,8 +302,8 @@ Read a more extensive description of `ref` and `relref` in the [cross references
Assuming that standard Hugo pretty URLs are turned on.
```
<a href="/blog/neat">Neat</a>
<a href="/about/#who:c28654c202e73453784cfd2c5ab356c0">Who</a>
<a href="https://example.com/blog/neat">Neat</a>
<a href="/about/#who">Who</a>
```
### `tweet`

2
docs/content/en/content-management/syntax-highlighting.md
View File

@@ -36,7 +36,7 @@ Run `hugo gen chromastyles -h` for more options. See https://xyproto.github.io/s
## Highlight Shortcode
Highlighting is carried out via the [built-in shortcode](/content-management/shortcodes/) `highlight`. `highlight` takes exactly one required parameter for the programming language to be highlighted and requires a closing shortcode. Note that `highlight` is *not* used for client-side javascript highlighting.
Highlighting is carried out via the built-in [`highlight` shortcode](https://gohugo.io/content-management/shortcodes/#highlight). It takes exactly one required parameter for the programming language to be highlighted and requires a closing shortcode. Note that `highlight` is *not* used for client-side javascript highlighting.
Options:

2
docs/content/en/content-management/urls.md
View File

@@ -202,7 +202,7 @@ The following demonstrates the concept:
```
content/posts/_index.md
=> example.com/posts/index.html
=> example.com/posts/
content/posts/post-1.md
=> example.com/posts/post-1/
```