diff options
author | Bjørn Erik Pedersen <bjorn.erik.pedersen@gmail.com> | 2018-04-16 07:45:38 +0200 |
---|---|---|
committer | Bjørn Erik Pedersen <bjorn.erik.pedersen@gmail.com> | 2018-04-16 07:45:38 +0200 |
commit | 7c597c7d756652c3cd50f3b538559ef505d817b9 (patch) | |
tree | f6944d69b0191694b7d184a5b7fba507baa0153c /docs | |
parent | e136c26d0cf9e74b78e8d13abee059848546391c (diff) | |
parent | 047c4188dfc854f658d16f1e4a9501f9c97a31c7 (diff) |
Merge commit '047c4188dfc854f658d16f1e4a9501f9c97a31c7'
Diffstat (limited to 'docs')
41 files changed, 12138 insertions, 368 deletions
diff --git a/docs/content/about/new-in-032/index.md b/docs/content/about/new-in-032/index.md index 41bd58937..b8ca6430e 100644 --- a/docs/content/about/new-in-032/index.md +++ b/docs/content/about/new-in-032/index.md @@ -61,7 +61,7 @@ Note that changes to any resource inside the `content` folder will trigger a rel #### List all Resources -```html +```go-html-template {{ range .Resources }} <li><a href="{{ .RelPermalink }}">{{ .ResourceType | title }}</a></li> {{ end }} @@ -73,7 +73,7 @@ For an absolute URL, use `.Permalink`. #### List All Resources by Type -```html +```go-html-template {{ with .Resources.ByType "image" }} {{ end }} @@ -83,7 +83,7 @@ Type here is `page` for pages, else the main type in the MIME type, so `image`, #### Get a Specific Resource -```html +```go-html-template {{ $logo := .Resources.GetByPrefix "logo" }} {{ with $logo }} {{ end }} @@ -91,7 +91,7 @@ Type here is `page` for pages, else the main type in the MIME type, so `image`, #### Include Page Resource Content -```html +```go-html-template {{ with .Resources.ByType "page" }} {{ range . }} <h3>{{ .Title }}</h3> @@ -146,7 +146,7 @@ This is the shortcode used in the examples above: And it is used like this: -```html +```go-html-template {{</* imgproc sunset Resize "300x" */>}} ``` diff --git a/docs/content/content-management/comments.md b/docs/content/content-management/comments.md index 355bf0042..20932a825 100644 --- a/docs/content/content-management/comments.md +++ b/docs/content/content-management/comments.md @@ -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: diff --git a/docs/content/content-management/front-matter.md b/docs/content/content-management/front-matter.md index a6a3f2403..2fc18ee31 100644 --- a/docs/content/content-management/front-matter.md +++ b/docs/content/content-management/front-matter.md @@ -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 diff --git a/docs/content/content-management/image-processing/index.md b/docs/content/content-management/image-processing/index.md index 1f84ba04d..ecc85bb51 100644 --- a/docs/content/content-management/image-processing/index.md +++ b/docs/content/content-management/image-processing/index.md @@ -23,7 +23,7 @@ The `image` is a [Page Resource]({{< relref "content-management/page-resources" To get all images in a [Page Bundle]({{< relref "content-management/organization#page-bundles" >}}): -```html +```go-html-template {{ with .Resources.ByType "image" }} {{ end }} @@ -131,7 +131,7 @@ This is the shortcode used in the examples above: And it is used like this: -```html +```go-html-template {{</* imgproc sunset Resize "300x" /*/>}} ``` diff --git a/docs/content/content-management/menus.md b/docs/content/content-management/menus.md index 1353ce0e2..c2eadf50f 100644 --- a/docs/content/content-management/menus.md +++ b/docs/content/content-management/menus.md @@ -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`. diff --git a/docs/content/content-management/multilingual.md b/docs/content/content-management/multilingual.md index d27195a9a..28a6e4fec 100644 --- a/docs/content/content-management/multilingual.md +++ b/docs/content/content-management/multilingual.md @@ -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 diff --git a/docs/content/content-management/page-bundles.md b/docs/content/content-management/page-bundles.md index 09aeae8ea..34620a5e2 100644 --- a/docs/content/content-management/page-bundles.md +++ b/docs/content/content-management/page-bundles.md @@ -93,7 +93,7 @@ anywhere: But you can get it by `.Site.GetPage`. Here is an example: -```html +```go-html-template {{ $headless := .Site.GetPage "page" "some-headless-bundle" }} {{ $reusablePages := $headless.Resources.Match "author*" }} <h2>Authors</h2> diff --git a/docs/content/content-management/page-resources.md b/docs/content/content-management/page-resources.md index f3b12d8c4..cefb1cd47 100644 --- a/docs/content/content-management/page-resources.md +++ b/docs/content/content-management/page-resources.md @@ -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: diff --git a/docs/content/content-management/related.md b/docs/content/content-management/related.md index 8ae6e79ce..6f66e4468 100644 --- a/docs/content/content-management/related.md +++ b/docs/content/content-management/related.md @@ -34,6 +34,11 @@ To list up to 5 related pages is as simple as including something similar to thi {{ end }} {{< /code >}} + +{{% note %}} +Read [this blog article](https://regisphilibert.com/blog/2018/04/hugo-optmized-relashionships-with-related-content/) for a great explanation more advanced usage of this feature. +{{% /note %}} + The full set of methods available on the page lists can bee seen in this Go interface: ```go diff --git a/docs/content/content-management/static-files.md b/docs/content/content-management/static-files.md index 12d27ccf2..fe5ea77e0 100644 --- a/docs/content/content-management/static-files.md +++ b/docs/content/content-management/static-files.md @@ -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: diff --git a/docs/content/content-management/syntax-highlighting.md b/docs/content/content-management/syntax-highlighting.md index 67d443fd4..e7eb011c8 100644 --- a/docs/content/content-management/syntax-highlighting.md +++ b/docs/content/content-management/syntax-highlighting.md @@ -147,7 +147,7 @@ See [Highlight](/functions/highlight/). It is also possible to add syntax highlighting with GitHub flavored code fences. To enable this, set the `pygmentsCodeFences` to `true` in Hugo's [configuration file](/getting-started/configuration/); ```` -```html +```go-html-template <section id="main"> <div> <h1 id="title">{{ .Title }}</h1> @@ -159,6 +159,11 @@ It is also possible to add syntax highlighting with GitHub flavored code fences. ``` ```` +## List of Chroma Highlighting Languages + +The full list of Chroma lexers and their aliases (which is the identifier used in the `hightlight` template func or when doing highlighting in code fences): + +{{< chroma-lexers >}} ## Highlight with Pygments Classic diff --git a/docs/content/content-management/taxonomies.md b/docs/content/content-management/taxonomies.md index 1a59ebe3e..287c6f899 100644 --- a/docs/content/content-management/taxonomies.md +++ b/docs/content/content-management/taxonomies.md @@ -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. diff --git a/docs/content/content-management/urls.md b/docs/content/content-management/urls.md index dd91fbced..d33725b72 100644 --- a/docs/content/content-management/urls.md +++ b/docs/content/content-management/urls.md @@ -29,19 +29,12 @@ These examples use the default values for `publish |