Merge commit 'b9bd35d72e14932fb6588ff62b90cddef0a060fc' as 'docs'

2025-08-21 21:35:28 +02:00 · 2019-10-21 10:22:28 +02:00
parent 39121de4d9 b9bd35d72e
commit 27aef3f1fb
735 changed files with 38220 additions and 0 deletions
--- a/docs/content/en/readfiles/README.md
+++ b/docs/content/en/readfiles/README.md
@@ -0,0 +1,16 @@
+# readdirs Directory for Reusable Content
+
+Files in this directory are:
+
+1. Used in *more than one place* within the Hugo docs
+2. Used in Examples of readdir (i.e. in local file templates)
+
+These files are called using the [`readfile` shortcode (source)](../layouts/readfile.html).
+
+You can call this shortcode in the docs as follows:
+
+
+<code>{</code><code>{</code>% readfile file="/path/to/file.txt" markdown="true" %<code>}</code><code>}</code>
+
+
+`markdown="true"` is optional (default = `"false"`) and parses the string through the Blackfriday renderer.
--- a/docs/content/en/readfiles/bfconfig.md
+++ b/docs/content/en/readfiles/bfconfig.md
@@ -0,0 +1,197 @@
+## Blackfriday Options
+
+`taskLists`
+: default: **`true`**<br>
+    Blackfriday flag: <br>
+    Purpose: `false` turns off GitHub-style automatic task/TODO list generation.
+
+`smartypants`
+: default: **`true`** <br>
+    Blackfriday flag: **`HTML_USE_SMARTYPANTS`** <br>
+    Purpose: `false` disables smart punctuation substitutions, including smart quotes, smart dashes, smart fractions, etc. If `true`, it may be fine-tuned with the `angledQuotes`, `fractions`, `smartDashes`, and `latexDashes` flags (see below).
+
+`smartypantsQuotesNBSP`
+: default: **`false`** <br>
+    Blackfriday flag: **`HTML_SMARTYPANTS_QUOTES_NBSP`** <br>
+    Purpose: `true` enables French style Guillemets with non-breaking space inside the quotes.
+
+`angledQuotes`
+: default: **`false`**<br>
+    Blackfriday flag: **`HTML_SMARTYPANTS_ANGLED_QUOTES`**<br>
+    Purpose: `true` enables smart, angled double quotes. Example: "Hugo" renders to «Hugo» instead of “Hugo”.
+
+`fractions`
+: default: **`true`**<br>
+    Blackfriday flag: **`HTML_SMARTYPANTS_FRACTIONS`** <br>
+    Purpose: <code>false</code> disables smart fractions.<br>
+    Example: `5/12` renders to <sup>5</sup>&frasl;<sub>12</sub>(<code>&lt;sup&gt;5&lt;/sup&gt;&amp;frasl;&lt;sub&gt;12&lt;/sub&gt;</code>).<br> <small><strong>Caveat:</strong> Even with <code>fractions = false</code>, Blackfriday still converts `1/2`, `1/4`, and `3/4` respectively to ½ (<code>&amp;frac12;</code>), ¼ (<code>&amp;frac14;</code>) and ¾ (<code>&amp;frac34;</code>), but only these three.</small>
+
+`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.
+
+`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.
+
+`hrefTargetBlank`
+: default: **`false`** <br>
+    Blackfriday flag: **`HTML_HREF_TARGET_BLANK`** <br>
+    Purpose: `true` opens <s>external links</s> **absolute** links in a new window or tab. While the `target="_blank"` attribute is typically used for external links, Blackfriday does that for _all_ absolute links ([ref](https://discourse.gohugo.io/t/internal-links-in-same-tab-external-links-in-new-tab/11048/8)). One needs to make note of this if they use absolute links throughout, for internal links too (for example, by setting `canonifyURLs` to `true` or via `absURL`).
+
+`nofollowLinks`
+: default: **`false`** <br>
+    Blackfriday flag: **`HTML_NOFOLLOW_LINKS`** <br>
+    Purpose: `true` creates <s>external links</s> **absolute** links with `nofollow` being added to their `rel` attribute. Thereby crawlers are advised to not follow the link. While the `rel="nofollow"` attribute is typically used for external links, Blackfriday does that for _all_ absolute links. One needs to make note of this if they use absolute links throughout, for internal links too (for example, by setting `canonifyURLs` to `true` or via `absURL`).
+
+`noreferrerLinks`
+: default: **`false`** <br>
+    Blackfriday flag: **`HTML_NOREFERRER_LINKS`** <br>
+    Purpose: `true` creates <s>external links</s> **absolute** links with `noreferrer` being added to their `rel` attribute. Thus when following the link no referrer information will be leaked. While the `rel="noreferrer"` attribute is typically used for external links, Blackfriday does that for _all_ absolute links. One needs to make note of this if they use absolute links throughout, for internal links too (for example, by setting `canonifyURLs` to `true` or via `absURL`).
+
+`plainIDAnchors`
+: default **`true`** <br>
+    Blackfriday flag: **`FootnoteAnchorPrefix` and `HeaderIDSuffix`** <br>
+    Purpose: `true` renders any heading and footnote IDs without the document ID. <br>
+    Example: renders `#my-heading` instead of `#my-heading:bec3ed8ba720b970`
+
+`extensions`
+: default: **`[]`** <br>
+    Purpose: Enable one or more Blackfriday's Markdown extensions (**`EXTENSION_*`**). <br>
+    Example: Include `hardLineBreak` in the list to enable Blackfriday's `EXTENSION_HARD_LINE_BREAK`. <br>
+    *See [Blackfriday extensions](#blackfriday-extensions) section for information on all extensions.*
+
+`extensionsmask`
+: default: **`[]`** <br>
+    Purpose: Disable one or more of Blackfriday's Markdown extensions (**`EXTENSION_*`**). <br>
+    Example: Include `autoHeaderIds` as `false` in the list to disable Blackfriday's `EXTENSION_AUTO_HEADER_IDS`. <br>
+    *See [Blackfriday extensions](#blackfriday-extensions) section for information on all extensions.*
+
+`skipHTML`
+: default: **`false`** <br>
+    Blackfriday flag: **`HTML_SKIP_HTML`** <br>
+    Purpose: `true` causes any HTML in the markdown files to be skipped.
+
+## 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/en/readfiles/dateformatting.md
+++ b/docs/content/en/readfiles/dateformatting.md
@@ -0,0 +1,87 @@
+Go templates [format your dates][time] according to a single reference time:
+
+```
+Mon Jan 2 15:04:05 MST 2006
+```
+
+You can think of `MST` as `07`, thus making the reference format string a sequence of numbers. The following is [taken directly from the Go docs][gdex]:
+
+```
+Jan 2 15:04:05 2006 MST
+  1 2  3  4  5    6  -7
+```
+
+### Hugo Date Templating Reference
+
+Each of the following examples show the reference formatting string followed by the string Hugo will output in your HTML.
+
+Note that the examples were rendered and tested in [CST][] and pull from a single example date you might have in your content's front matter:
+
+```
+date: 2017-03-03T14:15:59-06:00
+```
+
+`.Date` (i.e. called via [page variable][pagevars])
+: **Returns**: `2017-03-03 14:15:59 -0600 CST`
+
+`"Monday, January 2, 2006"`
+: **Returns**: `Friday, March 3, 2017`
+
+`"Mon Jan 2 2006"`
+: **Returns**: `Fri Mar 3 2017`
+
+`"January 2nd"`
+: **Returns**: `March 3rd`
+
+`"January 2006"`
+: **Returns**: `March 2017`
+
+`"2006-01-02"`
+: **Returns**: `2017-03-03`
+
+`"Monday"`
+: **Returns**: `Friday`
+
+`"02 Jan 06 15:04 MST"` (RFC822)
+: **Returns**: `03 Mar 17 14:15 CST`
+
+`"02 Jan 06 15:04 -0700"` (RFC822Z)
+: **Returns**: `03 Mar 17 14:15 -0600`
+
+`"Mon, 02 Jan 2006 15:04:05 MST"` (RFC1123)
+: **Returns**: `Fri, 03 Mar 2017 14:15:59 CST`
+
+`"Mon, 02 Jan 2006 15:04:05 -0700"` (RFC339)
+: **Returns**: `Fri, 03 Mar 2017 14:15:59 -0600`
+
+### Cardinal Numbers and Ordinal Abbreviations
+
+Spelled-out cardinal numbers (e.g. "one", "two", and "three") and ordinal abbreviations (e.g. "1st", "2nd", and "3rd") are not currently supported.
+
+To continue with the example above:
+
+```
+{{.Date.Format "Jan 2nd 2006"}}
+```
+
+Hugo assumes you want to append `nd` as a string to the day of the month and outputs the following:
+
+```
+Mar 3nd 2017
+```
+
+### Use `.Local` and `.UTC`
+
+In conjunction with the [`dateFormat` function][dateFormat], you can also convert your dates to `UTC` or to local timezones:
+
+`{{ dateFormat "02 Jan 06 15:04 MST" .Date.UTC }}`
+: **Returns**: `03 Mar 17 20:15 UTC`
+
+`{{ dateFormat "02 Jan 06 15:04 MST" .Date.Local }}`
+: **Returns**: `03 Mar 17 14:15 CST`
+
+[CST]: https://en.wikipedia.org/wiki/Central_Time_Zone
+[dateFormat]: /functions/dateformat/
+[gdex]: https://golang.org/pkg/time/#example_Time_Format
+[pagevars]: /variables/page/
+[time]: https://golang.org/pkg/time/
--- a/docs/content/en/readfiles/index.md
+++ b/docs/content/en/readfiles/index.md
@@ -0,0 +1,3 @@
+---
+headless: true
+---
--- a/docs/content/en/readfiles/pages-vs-site-pages.md
+++ b/docs/content/en/readfiles/pages-vs-site-pages.md
@@ -0,0 +1,32 @@
+* A _regular_ page is a "post" page or a "content" page.
+  * A _leaf bundle_ is a regular page.
+* A _list_ page can list _regular_ pages and other _list_ pages. Some
+  examples are: homepage, section pages, _taxonomy term_ (`/tags/`) and
+  _taxonomy_ (`/tags/foo/`) pages.
+  * A _branch bundle_ is a _list_ page.
+
+`.Site.Pages`
+: Collection of **all** pages of the site: _regular_ pages,
+    sections, taxonomies, etc. -- Superset of everything!
+
+`.Site.RegularPages`
+: Collection of only _regular_ pages.
+
+The above `.Site. ..` page collections can be accessed from any scope in
+the templates.
+
+Below variables return a collection of pages only from the scope of
+the current _list_ page:
+
+`.Pages`
+: Collection of _regular_ pages and _only first-level_
+    section pages under the current _list_ page.
+
+`.RegularPages`
+: Collection of only _regular_ pages under the
+    current _list_ page.
+
+
+Note
+: From the scope of _regular_ pages, `.Pages` and
+    `.RegularPages` return an empty slice.
--- a/docs/content/en/readfiles/sectionvars.md
+++ b/docs/content/en/readfiles/sectionvars.md
@@ -0,0 +1,23 @@
+.CurrentSection
+: The page's current section. The value can be the page itself if it is a section or the homepage.
+
+.FirstSection
+: The page's first section below root, e.g. `/docs`, `/blog` etc.
+
+.InSection $anotherPage
+: Whether the given page is in the current section. Note that this will always return false for pages that are not either regular, home or section pages.
+
+.IsAncestor $anotherPage
+: Whether the current page is an ancestor of the given page. Note that this method is not relevant for taxonomy lists and taxonomy terms pages.
+
+.IsDescendant $anotherPage
+: Whether the current page is a descendant of the given page. Note that this method is not relevant for taxonomy lists and taxonomy terms pages.
+
+.Parent
+: A section's parent section or a page's section.
+
+.Section
+: The [section](/content-management/sections/) this content belongs to. **Note:** For nested sections, this is the first path element in the directory, for example, `/blog/funny/mypost/ => blog`.
+
+.Sections
+: The [sections](/content-management/sections/) below this content.
--- a/docs/content/en/readfiles/testing.txt
+++ b/docs/content/en/readfiles/testing.txt
@@ -0,0 +1,3 @@
+##### Hello World!
+
+Testing one, **two**, *three*. Don't delete this sample file used in the [templates](/templates/) section of the Hugo docs.