Squashed 'docs/' changes from 35abbc86..f887bd7b

f887bd7b Add script to pull theme changes e89bbb2f Update README 78155dec Merge commit '9301947b25099dd402065104b340b1a480906a74' as 'themes/gohugoioTheme' 9301947b Squashed 'themes/gohugoioTheme/' content from commit 7dd8a302 e7557a34 Remove gohugoioTheme submodule a78bbe22 Add link to Go issue 31d1ef40 Add example for taxonomy terms with metadata da978cc7 Fix links in Blackfriday extension documentation 950ad115 Fix reference to Blackfriday Extensions section 12d1d026 Add documentation for Blackfriday Extensions 8c2b8fb5 Fix explaination for uglyURLs config option 378aded7 Use community repository for Arch Linux installation guide 56455e7e Improve 0.26 release notes be7db03a netlify: Build with the new 0.26 d430b2d3 Bump version to 0.26 61adaca0 releaser: Prepare repository for 0.27-DEV abef29a6 releaser: Add release notes to /docs for release of 0.26 5937fe41 releaser: Bump versions for release of 0.26 033752f1 Merge commit 'e81208265bb3cdb7606d051a23d83aeebcb7d34d' bec2bd12 Make the title case style guide configurable f1739a44 Merge commit '50ec65fbe1a48475d3320775dab2c47389c02114' a1aac0e5 helpers: Add support for French Guillemets b8dc1592 doc: Merge commit '2c0d1ccdcd95de0bddeb39dca2e4d08f0d8056d7' 7b3e31b8 Merge commit '6dbde8d731f221b027c0c60b772ba82dad759943' a37e7201 Bump versions to 0.26-DEV git-subtree-dir: docs git-subtree-split: f887bd7b4e3e7c7e76cd63951e5b0d37d8fe0ac7
2025-08-26 22:04:32 +02:00 · 2017-08-10 14:37:03 +02:00
parent ea2cc26b39
commit 0373e43102
265 changed files with 14813 additions and 16 deletions
--- a/docs/content/content-management/taxonomies.md
+++ b/docs/content/content-management/taxonomies.md
@@ -84,7 +84,7 @@ Moonrise Kingdom            <- Content

 ## Hugo Taxonomy Defaults

-Hugo natively supports taxonomies. 
+Hugo natively supports taxonomies.

 Without adding a single line to your site's configuration file, Hugo will automatically create taxonomies for `tags` and `categories`. If you do not want Hugo to create any taxonomies, set `disableKinds` in your site's configuration to the following:

@@ -229,6 +229,19 @@ By using taxonomic weight, the same piece of content can appear in different pos
 Currently taxonomies only support the [default `weight => date` ordering of list content](/templates/lists/#default-weight-date). For more information, see the documentation on [taxonomy templates](/templates/taxonomy-templates/).
 {{% /note %}}

+## Add custom metadata to a Taxonomy Term
+
+If you need to add custom metadata to your taxonomy terms, you will need to create a page for that term at `/content/<TAXONOMY>/<TERM>/_index.md` and add your metadata in it's front matter. Continuing with our 'Actors' example, let's say you want to add a wikipedia page link to each actor. Your terms pages would be something like this:
+
+{{< code file="/content/actors/bruce-willis/_index.md" >}}
+  ---
+  title: "Bruce Willis"
+  wikipedia: "https://en.wikipedia.org/wiki/Bruce_Willis"
+  ---
+{{< /code >}}
+
+You can later use your custom metadata as shown in the [Taxonomy Terms Templates documentation](/templates/taxonomy-templates/#displaying-custom-meta-data-in-taxonomy-terms-templates).
+
 [`urlize` template function]: /functions/urlize/
 [content section]: /content-management/sections/
 [content type]: /content-management/types/
--- a/docs/content/functions/scratch.md
+++ b/docs/content/functions/scratch.md
@@ -22,6 +22,10 @@ aliases: [/extras/scratch/,/doc/scratch/]

 In most cases you can do well without `Scratch`, but there are some use cases that aren't solvable with Go's templates without `Scratch`'s help, due to scoping issues.

+{{% note %}}
+See [this Go issue](https://github.com/golang/go/issues/10608) for the main motivation behind Scratch.
+{{% /note %}}
+
 `Scratch` is added to both `Page` and `Shortcode` -- with following methods:

 * `Set` and `Add` takes a `key` and the `value` to add.
--- a/docs/content/getting-started/configuration.md
+++ b/docs/content/getting-started/configuration.md
@@ -155,6 +155,10 @@ stepAnalysis:               false
 themesDir:                  "themes"
 theme:                      ""
 title:                      ""
+# Title Case style guide for the title func and other automatic title casing in Hugo.
+// Valid values are "AP" (default), "Chicago" and "Go" (which was what you had in Hugo <= 0.25.1).
+// See https://www.apstylebook.com/ and http://www.chicagomanualofstyle.org/home.html
+titleCaseStyle:             "AP"
 # if true, use /filename.html instead of /filename/
 # Title Case style guide for the title func and other automatic title casing in Hugo.
 // Valid values are "AP" (default), "Chicago" and "Go" (which was what you had in Hugo <= 0.25.1).
@@ -392,4 +396,4 @@ Hugo v0.20 introduced the ability to render your content to multiple output form
 [Output Formats]: /templates/output-formats/
 [templates]: /templates/
 [toml]: https://github.com/toml-lang/toml
-[yaml]: http://yaml.org/spec/
+[yaml]: http://yaml.org/spec/
--- a/docs/content/getting-started/installing.md
+++ b/docs/content/getting-started/installing.md
@@ -441,15 +441,12 @@ sudo apt-get install hugo

 * Might not be the latest version, especially if you are using an older, stable version (e.g., Ubuntu 16.04 LTS). Until backports and PPA are available, you may consider installing the Hugo snap package to get the latest version of Hugo.

-### Arch
+### Arch Linux

-You can also install Hugo from the [Arch user repository](https://aur.archlinux.org/) on Arch Linux or derivatives such as Manjaro.
-
-Be aware that Hugo is built from source. This means that additional tools like [Git](https://git-scm.com) and [Go](https://golang.org/doc/install) will be installed as well.
+You can also install Hugo from the Arch Linux [community](https://www.archlinux.org/packages/community/x86_64/hugo/) repository. Applies also for derivatives such as Manjaro.

 ```
-sudo pacman -S yaourt
-yaourt -S hugo
+sudo pacman -Sy hugo
 ```

 ### Fedora, CentOS, and Red Hat
--- a/docs/content/readfiles/bfconfig.md
+++ b/docs/content/readfiles/bfconfig.md
@@ -1,7 +1,9 @@
+## Blackfriday Options
+
 `taskLists`
 : default: **`true`**<br>
    Blackfriday flag: <br>
-    Purpose: `false` turns off GitHub-style automatic task/TODO list generation
+    Purpose: `false` turns off GitHub-style automatic task/TODO list generation.

 `smartypants`
 : default: **`true`** <br>
@@ -27,14 +29,14 @@
 `smartDashes`
 : default: **`true`** <br>
    Blackfriday flag: **`HTML_SMARTY_DASHES`** <br>
-    Purpose: `false` disables smart dashes; i.e., the conversion of multiple hyphens into an en dash or em dash. If `true`, its behavior can be modified with the `latexDashes` flag below.
+    Purpose: `false` disables smart dashes; i.e., the conversion of multiple hyphens into an en-dash or em-dash. If `true`, its behavior can be modified with the `latexDashes` flag below.

 `latexDashes`
 : default: **`true`** <br>
    Blackfriday flag: **`HTML_SMARTYPANTS_LATEX_DASHES`** <br>
    Purpose: `false` disables LaTeX-style smart dashes and selects conventional smart dashes. Assuming `smartDashes`: <br>
    If `true`, `--` is translated into &ndash; (`&ndash;`), whereas `---` is translated into &mdash; (`&mdash;`). <br>
-    However, *spaced* single hyphen between two words is translated into an en&nbsp;dash&mdash; e.g., "`12 June - 3 July`" becomes `12 June ndash; 3 July` upon rendering.
+    However, *spaced* single hyphen between two words is translated into an en&nbsp;dash&mdash; e.g., "`12 June - 3 July`" becomes `12 June &ndash; 3 July` upon rendering.

 `hrefTargetBlank`
 : default: **`false`** <br>
@@ -51,10 +53,132 @@
 : default: **`[]`** <br>
    Blackfriday flag: **`EXTENSION_*`** <br>
    Purpose: Enable one or more Blackfriday's Markdown extensions (if they aren't Hugo defaults). <br>
-    Example: Include `hardLineBreak` in the list to enable Blackfriday's `EXTENSION_HARD_LINK_BREAK`
+    Example: Include `hardLineBreak` in the list to enable Blackfriday's `EXTENSION_HARD_LINK_BREAK`. <br>
+    *See [Blackfriday extensions](#blackfriday-extensions) section for more information.*

 `extensionsmask`
 : default: **`[]`** <br>
    Blackfriday flag: **`EXTENSION_*`** <br>
    Purpose: Enable one or more of Blackfriday's Markdown extensions (if they aren't Hugo defaults). <br>
-    Example: Include `autoHeaderIds` as `false` in the list to disable Blackfriday's `EXTENSION_AUTO_HEADER_IDS`.
+    Example: Include `autoHeaderIds` as `false` in the list to disable Blackfriday's `EXTENSION_AUTO_HEADER_IDS`. <br>
+    *See [Blackfriday extensions](#blackfriday-extensions) section for more information.*
+
+## Blackfriday extensions
+
+`noIntraEmphasis`
+: default: *enabled* <br>
+    Purpose: The "\_" character is commonly used inside words when discussing
+    code, so having Markdown interpret it as an emphasis command is usually the
+    wrong thing.  When enabled, Blackfriday lets you treat all emphasis markers
+    as normal characters when they occur inside a word.
+
+`tables`
+: default: *enabled* <br>
+    Purpose: When enabled, tables can be created by drawing them in the input
+    using the below syntax:
+    Example:
+
+           Name | Age
+        --------|------
+            Bob | 27
+          Alice | 23
+
+`fencedCode`
+: default: *enabled* <br>
+    Purpose: When enabled, in addition to the normal 4-space indentation to mark
+    code blocks, you can explicitly mark them and supply a language (to make
+    syntax highlighting simple).
+
+    You can use 3 or more backticks to mark the beginning of the block, and the
+    same number to mark the end of the block.
+
+    Example:
+
+         ```md
+        # Heading Level 1
+        Some test
+        ## Heading Level 2
+        Some more test
+        ```
+
+`autolink`
+: default: *enabled* <br>
+    Purpose: When enabled, URLs that have not been explicitly marked as links
+    will be converted into links.
+
+`strikethrough`
+: default: *enabled* <br>
+    Purpose: When enabled, text wrapped with two tildes will be crossed out. <br>
+    Example: `~~crossed-out~~`
+
+`laxHtmlBlocks`
+: default: *disabled* <br>
+    Purpose: When enabled, loosen up HTML block parsing rules.
+
+`spaceHeaders`
+: default: *enabled* <br>
+    Purpose: When enabled, be strict about prefix header rules.
+
+`hardLineBreak`
+: default: *disabled* <br>
+    Purpose: When enabled, newlines in the input translate into line breaks in
+    the output.
+
+
+`tabSizeEight`
+: default: *disabled* <br>
+    Purpose: When enabled, expand tabs to eight spaces instead of four.
+
+`footnotes`
+: default: *enabled* <br>
+    Purpose: When enabled, Pandoc-style footnotes will be supported.  The
+    footnote marker in the text that will become a superscript text; the
+    footnote definition will be placed in a list of footnotes at the end of the
+    document. <br>
+    Example:
+
+        This is a footnote.[^1]
+
+        [^1]: the footnote text.
+
+`noEmptyLineBeforeBlock`
+: default: *disabled* <br>
+    Purpose: When enabled, no need to insert an empty line to start a (code,
+    quote, ordered list, unordered list) block.
+
+
+`headerIds`
+: default: *enabled* <br>
+    Purpose: When enabled, allow specifying header IDs with `{#id}`.
+
+`titleblock`
+: default: *disabled* <br>
+    Purpose: When enabled, support [Pandoc-style title blocks][1].
+
+`autoHeaderIds`
+: default: *enabled* <br>
+    Purpose: When enabled, auto-create the header ID's from the headline text.
+
+`backslashLineBreak`
+: default: *enabled* <br>
+    Purpose: When enabled, translate trailing backslashes into line breaks.
+
+`definitionLists`
+: default: *enabled* <br>
+    Purpose: When enabled, a simple definition list is made of a single-line
+    term followed by a colon and the definition for that term. <br>
+    Example:
+
+        Cat
+        : Fluffy animal everyone likes
+
+        Internet
+        : Vector of transmission for pictures of cats
+
+    Terms must be separated from the previous definition by a blank line.
+
+`joinLines`
+: default: *enabled* <br>
+    Purpose: When enabled, delete newlines and join the lines.
+
+[1]: http://pandoc.org/MANUAL.html#extension-pandoc_title_block
--- a/docs/content/templates/taxonomy-templates.md
+++ b/docs/content/templates/taxonomy-templates.md
@@ -117,6 +117,21 @@ type WeightedPages []WeightedPage
 .Pages
 : Returns a slice of pages, which then can be ordered using any of the [list methods][renderlists].

+## Displaying custom metadata in Taxonomy Terms Templates
+
+If you need to display custom metadata for each taxonomy term, you will need to create a page for that term at `/content/<TAXONOMY>/<TERM>/_index.md` and add your metadata in it's front matter, [as explained in the taxonomies documentation](/content-management/taxonomies/#add-custom-meta-data-to-a-taxonomy-term). Based on the Actors taxonomy example shown there, within your taxonomy terms template, you may access your custom fields by iterating through the variable `.Data.Pages` as such:
+
+```
+<ul>
+  {{ range .Data.Pages }}
+     <li>
+       <a href="{{ .Permalink }}">{{ .Title }}</a>
+       {{ .Params.wikipedia }}
+     </li>
+  {{ end }}
+</ul>
+```
+
 <!-- Begin /taxonomies/ordering/ -->

 ## Order Taxonomies