diff options
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 `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/`. diff --git a/docs/content/functions/where.md b/docs/content/functions/where.md index 3aa03296b..eb3111215 100644 --- a/docs/content/functions/where.md +++ b/docs/content/functions/where.md @@ -22,7 +22,7 @@ needsexample: true `where` filters an array to only the elements containing a matching value for a given field. -``` |