TheCloud/hugoDocs
1
0
Fork 0
mirror of https://github.com/gohugoio/hugoDocs.git synced 2025-09-14 14:04:51 -04:00
Code Issues Packages Projects Releases Wiki Activity

use code-toggle shortcode when relevant

Browse Source 
Content Management ✅
This commit is contained in:
Regis Philibert 2018-04-06 15:41:50 -04:00 committed by Bjørn Erik Pedersen
parent 455b8b53b8
commit 8ae3aadd73
9 changed files with 43 additions and 245 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

10
content/content-management/comments.md
View File

@ -27,15 +27,11 @@ Hugo comes with all the code you need to load Disqus into your templates. Before
### Configure Disqus
Disqus comments require you set a single value in your [site's configuration file][configuration]. The following show the configuration variable in a `config.toml` and `config.yml`, respectively:
Disqus comments require you set a single value in your [site's configuration file][configuration] like so:
```
{{< code-toggle copy="false" >}}
disqusShortname = "yourdiscussshortname"
```
```
disqusShortname: "yourdiscussshortname"
```
{{</ code-toggle >}}
For many websites, this is enough configuration. However, you also have the option to set the following in the [front matter][] of a single content file:

38
content/content-management/front-matter.md
View File

@ -34,9 +34,9 @@ YAML
JSON
: a single JSON object surrounded by '`{`' and '`}`', followed by a new line.
### TOML Example
### Example
```
{{< code-toggle >}}
+++
title = "spf13-vim 3.0 release and new website"
description = "spf13-vim is a cross platform distribution of vim plugins and resources for Vim."
@ -48,39 +48,7 @@ categories = [
]
slug = "spf13-vim-3-0-release-and-new-website"
+++
```
### YAML Example
```
---
title: "spf13-vim 3.0 release and new website"
description: "spf13-vim is a cross platform distribution of vim plugins and resources for Vim."
tags: [ ".vimrc", "plugins", "spf13-vim", "vim" ]
lastmod: 2015-12-23
date: "2012-04-06"
categories:
- "Development"
- "VIM"
slug: "spf13-vim-3-0-release-and-new-website"
---
```
### JSON Example
```
{
"title": "spf13-vim 3.0 release and new website",
"description": "spf13-vim is a cross platform distribution of vim plugins and resources for Vim.",
"tags": [ ".vimrc", "plugins", "spf13-vim", "vim" ],
"date": "2012-04-06",
"categories": [
"Development",
"VIM"
],
"slug": "spf13-vim-3-0-release-and-new-website"
}
```
{{</ code-toggle >}}
## Front Matter Variables

22
content/content-management/menus.md
View File

@ -118,9 +118,9 @@ menu:
You can also add entries to menus that aren’t attached to a piece of content. This takes place in your Hugo project's [`config` file][config].
Here’s an example snippet pulled from a `config.toml`:
Here’s an example snippet pulled from a configuration file:
{{< code file="config.toml" >}}
{{< code-toggle file="config.toml" >}}
[[menu.main]]
name = "about hugo"
pre = "<i class='fa fa-heart'></i>"
@ -132,23 +132,7 @@ Here’s an example snippet pulled from a `config.toml`:
pre = "<i class='fa fa-road'></i>"
weight = -100
url = "/getting-started/"
{{< /code >}}
Here's the equivalent snippet in a `config.yaml`:
{{< code file="config.yml" >}}
menu:
main:
- name: "about hugo"
pre: "<i class='fa fa-heart'></i>"
weight: -110
identifier: "about"
url: "/about/"
- name: "getting started"
pre: "<i class='fa fa-road'></i>"
weight: -100
url: "/getting-started/"
{{< /code >}}
{{< /code-toggle >}}
{{% note %}}
The URLs must be relative to the context root. If the `baseURL` is `https://example.com/mysite/`, then the URLs in the menu must not include the context root `mysite`. Using an absolute URL will override the baseURL. If the value used for `URL` in the above example is `https://subdomain.example.com/`, the output will be `https://subdomain.example.com`.

14
content/content-management/multilingual.md
View File

@ -21,9 +21,9 @@ You should define the available languages in a `languages` section in your site
## Configure Languages
The following is an example of a TOML site configuration for a multilingual Hugo project:
The following is an example of a site configuration for a multilingual Hugo project:
{{< code file="config.toml" download="config.toml" >}}
{{< code-toggle file="config" >}}
DefaultContentLanguage = "en"
copyright = "Everything is mine"
@ -45,7 +45,7 @@ weight = 2
linkedin = "lien-francais"
[languages.fr.params.navigation]
help = "Aide"
{{< /code >}}
{{< /code-toggle >}}
Anything not defined in a `[languages]` block will fall back to the global
value for that key (e.g., `copyright` for the English [`en`] language).
@ -92,7 +92,7 @@ This means that you can now configure a `baseURL` per `language`:
Example:
```bash
{{< code-toggle file="config" >}}
[languages]
[languages.no]
baseURL = "https://example.no"
@ -105,7 +105,7 @@ baseURL = "https://example.com"
languageName = "English"
weight = 2
title = "In English"
```
{{</ code-toggle >}}
With the above, the two sites will be generated into `public` with their own root:
@ -132,7 +132,7 @@ Live reload and `--navigateToChanged` between the servers work as expected.
Taxonomies and [Blackfriday configuration][config] can also be set per language:
{{< code file="bf-config.toml" >}}
{{< code-toggle file="config" >}}
[Taxonomies]
tag = "tags"
@ -152,7 +152,7 @@ weight = 2
title = "Français"
[languages.fr.Taxonomies]
plaque = "plaques"
{{< /code >}}
{{</ code-toggle >}}
## Translate Your Content

44
content/content-management/page-resources.md
View File

@ -83,9 +83,9 @@ params
: A map of custom key/values.
### Resources metadata: YAML Example
### Resources metadata example
~~~yaml
{{< code-toggle copy="false">}}
title: Application
date : 2018-01-25
resources :
@ -108,41 +108,7 @@ resources :
- src : "**.docx"
params :
icon : "word"
~~~
### Resources metadata: TOML Example
~~~toml
title = Application
date : 2018-01-25
[[resources]]
src = "images/sunset.jpg"
name = "header"
[[resources]]
src = "documents/photo_specs.pdf"
title = "Photo Specifications"
[resources.params]
icon = "photo"
[[resources]]
src = "documents/guide.pdf"
title = "Instruction Guide"
[[resources]]
src = "documents/checklist.pdf"
title = "Document Checklist"
[[resources]]
src = "documents/payment.docx"
title = "Proof of Payment"
[[resources]]
src = "**.pdf"
name = "pdf-file-:counter"
[resources.params]
icon = "pdf"
[[resources]]
src = "**.docx"
[resources.params]
icon = "word"
~~~
{{</ code-toggle >}}
From the example above:
@ -165,14 +131,14 @@ The counter starts at 1 the first time they are used in either `name` or `title`
For example, if a bundle has the resources `photo_specs.pdf`, `other_specs.pdf`, `guide.pdf` and `checklist.pdf`, and the front matter has specified the `resources` as:
~~~toml
{{< code-toggle copy="false">}}
[[resources]]
src = "*specs.pdf"
title = "Specification #:counter"
[[resources]]
src = "**.pdf"
name = "pdf-file-:counter"
~~~
{{</ code-toggle >}}
the `Name` and `Title` will be assigned to the resource files as follows:

6
content/content-management/static-files.md
View File

@ -15,11 +15,11 @@ toc: true
The `static` folder is where you place all your **static files**, e.g. stylesheets, JavaScript, images etc.
You can set the name of the static folder to use in your configuration file, for example `config.toml`. From **Hugo 0.31** you can configure as many static directories as you need. All the files in all the static directories will form a union filesystem.
You can set the name of the static folder to use in your configuration file. From **Hugo 0.31** you can configure as many static directories as you need. All the files in all the static directories will form a union filesystem.
Example:
```toml
{{< code-toggle copy="false" file="config" >}}
staticDir = ["static1", "static2"]
[languages]
[languages.no]
@ -35,7 +35,7 @@ baseURL = "https://example.com"
languageName = "English"
weight = 2
title = "In English"
```
{{</ code-toggle >}}
In the above, with no theme used:

78
content/content-management/taxonomies.md
View File

@ -103,23 +103,14 @@ When taxonomies are used---and [taxonomy templates][] are provided---Hugo will a
Taxonomies must be defined in your [website configuration][config] before they can be used throughout the site. You need to provide both the plural and singular labels for each taxonomy. For example, `singular key = "plural value"` for TOML and `singular key: "plural value"` for YAML.
### Example: TOML Taxonomy Configuration
### Example: Taxonomy Configuration
```
{{< code-toggle copy="false" >}}
[taxonomies]
tag = "tags"
category = "categories"
series = "series"
```
### Example: YAML Taxonomy Configuration
```
taxonomies:
tag: "tags"
category: "categories"
series: "series"
```
{{</ code-toggle >}}
### Preserve Taxonomy Values
@ -145,53 +136,16 @@ Assigning content to a taxonomy is done in the [front matter][]. Simply create a
If you would like the ability to quickly generate content files with preconfigured taxonomies or terms, read the docs on [Hugo archetypes](/content-management/archetypes/).
{{% /note %}}
### Example: TOML Front Matter with Taxonomies
### Example: Front Matter with Taxonomies
```
+++
{{< code-toggle copy="false">}}
title = "Hugo: A fast and flexible static site generator"
tags = [ "Development", "Go", "fast", "Blogging" ]
categories = [ "Development" ]
series = [ "Go Web Dev" ]
slug = "hugo"
project_url = "https://github.com/gohugoio/hugo"
+++
```
### Example: YAML Front Matter with Taxonomies
```
---
title: "Hugo: A fast and flexible static site generator"
tags: ["Development", "Go", "fast", "Blogging"]
categories: ["Development"]
series: ["Go Web Dev"]
slug: "hugo"
project_url: "https://github.com/gohugoio/hugo"
---
```
### Example: JSON Front Matter with Taxonomies
```
{
"title": "Hugo: A fast and flexible static site generator",
"tags": [
"Development",
"Go",
"fast",
"Blogging"
],
"categories" : [
"Development"
],
"series" : [
"Go Web Dev"
],
"slug": "hugo",
"project_url": "https://github.com/gohugoio/hugo"
}
```
{{</ code-toggle >}}
## Order Taxonomies
@ -199,29 +153,15 @@ A content file can assign weight for each of its associate taxonomies. Taxonomic
The following TOML and YAML examples show a piece of content that has a weight of 22, which can be used for ordering purposes when rendering the pages assigned to the "a", "b" and "c" values of the `tags` taxonomy. It has also been assigned the weight of 44 when rendering the "d" category page.
### Example: TOML Taxonomic `weight`
### Example: Taxonomic `weight`
```
+++
{{< code-toggle copy="false" >}}
title = "foo"
tags = [ "a", "b", "c" ]
tags_weight = 22
categories = ["d"]
categories_weight = 44
+++
```
### Example: YAML Taxonomic `weight`
```
---
title: foo
tags: [ "a", "b", "c" ]
tags_weight: 22
categories: ["d"]
categories_weight: 44
---
```
{{</ code-toggle >}}
By using taxonomic weight, the same piece of content can appear in different positions in different taxonomies.

13
content/content-management/urls.md
View File

@ -29,19 +29,12 @@ These examples use the default values for `publishDir` and `contentDir`; i.e., `
For example, if one of your [sections][] is called `post` and you want to adjust the canonical path to be hierarchical based on the year, month, and post title, you could set up the following configurations in YAML and TOML, respectively.
### YAML Permalinks Configuration Example
### Permalinks Configuration Example
{{< code file="config.yml" copy="false" >}}
{{< code-toggle file="config" copy="false" >}}
permalinks:
post: /:year/:month/:title/
{{< /code >}}
### TOML Permalinks Configuration Example
{{< code file="config.toml" copy="false" >}}
[permalinks]
post = "/:year/:month/:title/"
{{< /code >}}
{{< /code-toggle >}}
Only the content under `post/` will have the new URL structure. For example, the file `content/post/sample-entry.md` with `date: 2017-02-27T19:20:00-05:00` in its front matter will render to `public/2017/02/sample-entry/index.html` at build time and therefore be reachable at `https://example.com/2017/02/sample-entry/`.

63
content/getting-started/configuration.md
View File

@ -250,9 +250,11 @@ Similar to the template [lookup order][], Hugo has a default set of rules for se
In your `config` file, you can direct Hugo as to how you want your website rendered, control your website's menus, and arbitrarily define site-wide parameters specific to your project.
## YAML Configuration
## Example Configuration
{{< code file="config.yml">}}
The following is a typical example of a configuration file. The values nested under `params:` will populate the [`.Site.Params`][] variable for use in [templates][]:
{{< code-toggle file="config">}}
baseURL: "https://yoursite.example.com/"
title: "My Hugo Site"
footnoteReturnLinkContents: "↩"
@ -266,49 +268,7 @@ params:
- "foo1"
- "foo2"
SidebarRecentLimit: 5
{{< /code >}}
The following is a typical example of a YAML configuration file. The values nested under `params:` will populate the [`.Site.Params`][] variable for use in [templates][]:
{{< code file="config.yml">}}
baseURL: "https://yoursite.example.com/"
title: "My Hugo Site"
footnoteReturnLinkContents: "↩"
permalinks:
post: /:year/:month/:title/
params:
Subtitle: "Hugo is Absurdly Fast!"
AuthorName: "Jon Doe"
GitHubUser: "spf13"
ListOfFoo:
- "foo1"
- "foo2"
SidebarRecentLimit: 5
{{< /code >}}
## TOML Configuration
The following is an example of a TOML configuration file. The values under `[params]` will populate the `.Site.Params` variable for use in [templates][]:
{{< code file="config.toml">}}
contentDir = "content"
layoutDir = "layouts"
publishDir = "public"
buildDrafts = false
baseURL = "https://yoursite.example.com/"
canonifyURLs = true
title = "My Hugo Site"
[taxonomies]
category = "categories"
tag = "tags"
[params]
subtitle = "Hugo is Absurdly Fast!"
author = "John Doe"
{{< /code >}}
{{< /code-toggle >}}
## Configure with Environment Variables
@ -416,22 +376,13 @@ However, if you have specific needs with respect to Markdown, Hugo exposes some
2. Blackfriday flags must be grouped under the `blackfriday` key and can be set on both the site level *and* the page level. Any setting on a page will override its respective site setting.
{{% /note %}}
{{< code file="bf-config.toml" >}}
{{< code-toggle file="config" >}}
[blackfriday]
angledQuotes = true
fractions = false
plainIDAnchors = true
extensions = ["hardLineBreak"]
{{< /code >}}
{{< code file="bf-config.yml" >}}
blackfriday:
angledQuotes: true
fractions: false
plainIDAnchors: true
extensions:
- hardLineBreak
{{< /code >}}
{{< /code-toggle >}}
## Configure Additional Output Formats