shithub: hugo

--- a/content/commands/hugo.md

+++ b/content/commands/hugo.md

@@ -1,5 +1,5 @@

---

-date: 2017-09-26T21:11:49+02:00

+date: 2017-09-26T17:09:31-05:00

 title: "hugo"

 slug: hugo

 url: /commands/hugo/

@@ -67,7 +67,6 @@

 ### SEE ALSO

 * [hugo benchmark](/commands/hugo_benchmark/)	 - Benchmark Hugo by building a site a number of times.

-* [hugo check](/commands/hugo_check/)	 - Contains some verification checks

 * [hugo config](/commands/hugo_config/)	 - Print the site configuration

 * [hugo convert](/commands/hugo_convert/)	 - Convert your content to different formats

 * [hugo env](/commands/hugo_env/)	 - Print Hugo version and environment info

--- a/content/content-management/cross-references.md

+++ b/content/content-management/cross-references.md

@@ -21,12 +21,12 @@

 ## Use `ref` and `relref`

```

-{{</* ref "document" */>}}

+{{</* ref "document.md" */>}}

 {{</* ref "#anchor" */>}}

-{{</* ref "document#anchor" */>}}

-{{</* relref "document" */>}}

+{{</* ref "document.md#anchor" */>}}

+{{</* relref "document.md" */>}}

 {{</* relref "#anchor" */>}}

-{{</* relref "document#anchor" */>}}

+{{</* relref "document.md#anchor" */>}}

```

 The single parameter to `ref` is a string with a content `documentname` (e.g., `about.md`) with or without an appended in-document `anchor` (`#who`) without spaces.

@@ -120,4 +120,4 @@

 [built-in Hugo shortcodes]: /content-management/shortcodes/#using-the-built-in-shortcodes

 [lists]: /templates/lists/

 [output formats]: /templates/output-formats/

-[shortcode]: /content-management/shortcodes/

\ No newline at end of file

+[shortcode]: /content-management/shortcodes/

--- a/content/contribute/documentation.md

+++ b/content/contribute/documentation.md

@@ -143,8 +143,7 @@

 2. This snippet is complete enough to be downloaded and implemented in a Hugo project, as demonstrated by `download="single.html"`.

```

-{{%/* code file="layouts/_default/single.html" download="single.html" */%}}

-```

+{{</* code file="layouts/_default/single.html" download="single.html" */>}}

 {{ define "main" }}

 <main>

     <article>

@@ -162,8 +161,7 @@

     </article>

 </main>

 {{ end }}

-```

-{{%/* /code */%}}

+{{</* /code */>}}

```

 ##### Example 'code' Display

--- a/content/functions/partialCached.md

+++ b/content/functions/partialCached.md

@@ -10,7 +10,7 @@

 menu:

   docs:

     parent: "functions"

-keywords: []

+keywords: [performance]

 signature: ["partialCached LAYOUT INPUT [VARIANT...]"]

 workson: []

 hugoversion:

--- a/content/getting-started/configuration.md

+++ b/content/getting-started/configuration.md

@@ -151,6 +151,8 @@

 staticDir:                  "static"

 # display memory and timing of different steps of the program

 stepAnalysis:               false

+# display metrics about template executions

+templateMetrics:            false

 # theme to use (located by default in /themes/THEMENAME/)

 themesDir:                  "themes"

 theme:                      ""

--- a/content/getting-started/usage.md

+++ b/content/getting-started/usage.md

@@ -44,7 +44,6 @@

 Available Commands:

   benchmark   Benchmark Hugo by building a site a number of times.

-  check       Contains some verification checks

   config      Print the site configuration

   convert     Convert your content to different formats

   env         Print Hugo version and environment info

@@ -54,7 +53,7 @@

   list        Listing out various types of content

   new         Create new content for your site

   server      A high performance webserver

-  undraft     Undraft changes the content's draft status from 'True' to 'False'

+  undraft     Undraft resets the content's draft status

   version     Print the version number of Hugo

 Flags:

@@ -67,6 +66,7 @@

       --cleanDestinationDir        remove files from destination not found in static directories

       --config string              config file (default is path/config.yaml|json|toml)

   -c, --contentDir string          filesystem path to content directory

+      --debug                      debug output

   -d, --destination string         filesystem path to write files to

       --disable404                 do not render 404 page

       --disableKinds stringSlice   disable different kind of pages (home, RSS etc.)

@@ -88,6 +88,7 @@

       --renderToMemory             render to memory (only useful for benchmark testing)

   -s, --source string              filesystem path to read files relative from

       --stepAnalysis               display memory and timing of different steps of the program

+      --templateMetrics            display metrics about template executions

   -t, --theme string               theme to use (located in /themes/THEMENAME/)

       --themesDir string           filesystem path to themes directory

       --uglyURLs                   if true, use /filename.html instead of /filename/

@@ -94,6 +95,11 @@

   -v, --verbose                    verbose output

       --verboseLog                 verbose logging

   -w, --watch                      watch filesystem for changes and recreate as needed

+Additional help topics:

+  hugo check     Contains some verification checks

+Use "hugo [command] --help" for more information about a command.

```

 ## The `hugo` Command

--- a/content/templates/output-formats.md

+++ b/content/templates/output-formats.md

@@ -138,7 +138,7 @@

 The following is an example of `YAML` front matter in a content file that defines output formats for the rendered `Page`:

-```

+```yaml

---

 date: "2016-03-19"

 outputs:

@@ -152,7 +152,7 @@

 Each `Page` has both an `.OutputFormats` (all formats, including the current) and an `.AlternativeOutputFormats` variable, the latter of which is useful for creating a `link rel` list in your site's `<head>`:

-```

+```html

 {{ range .AlternativeOutputFormats -}}

 <link rel="{{ .Rel }}" type="{{ .MediaType.Type }}" href="{{ .Permalink | safeURL }}">

 {{ end -}}

@@ -162,7 +162,7 @@

 This is how you link to a given output format:

-```

+```html

 {{ with  .OutputFormats.Get "json" -}}

 <a href="{{ .Permalink }}">{{ .Name }}</a>

 {{- end }}

@@ -170,7 +170,7 @@

 From content files, you can use the [`ref` or `relref` shortcodes](/content-management/shortcodes/#ref-and-relref):

-```

+```html

 [Neat]({{</* ref "blog/neat.md" "amp" */>}})

 [Who]({{</* relref "about.md#who" "amp" */>}})

```

--- a/content/tools/editors.md

+++ b/content/tools/editors.md

@@ -31,7 +31,7 @@

 ## Emacs

 * [hugo.el](https://github.com/yewton/hugo.el). Some helper functions for creating a Website with Hugo. Note that Hugo also supports [Org-mode][formats].

-* [ox-hugo.el](https://ox-hugo.netlify.com). Native Org-mode exporter that exports to Blackfriday Markdown with Hugo front-matter. `ox-hugo` supports two common Org blogging flows --- exporting multiple Org sub-trees in a single file to multiple Hugo posts, and exporting a single Org file to a single Hugo post. It also leverages the Org tag and property inheritance features. See [*Why ox-hugo?*](https://ox-hugo.netlify.com/doc/why-ox-hugo/) for more.

+* [ox-hugo.el](https://ox-hugo.scripter.co). Native Org-mode exporter that exports to Blackfriday Markdown with Hugo front-matter. `ox-hugo` supports two common Org blogging flows --- exporting multiple Org sub-trees in a single file to multiple Hugo posts, and exporting a single Org file to a single Hugo post. It also leverages the Org tag and property inheritance features. See [*Why ox-hugo?*](https://ox-hugo.scripter.co/doc/why-ox-hugo/) for more.

 ## Vim

--- a/content/troubleshooting/build-performance.md

+++ b/content/troubleshooting/build-performance.md

@@ -1,7 +1,7 @@

---

 title: Build Performance

 linktitle: Build Performance

-description:

+description: An overview of features used for diagnosing and improving performance issues in site builds.

 date: 2017-03-12

 publishdate: 2017-03-12

 lastmod: 2017-03-12

@@ -11,13 +11,101 @@

   docs:

     parent: "troubleshooting"

 weight:

-draft: true

 slug:

 aliases: []

 toc: true

-wip: true

---

-<!-- See https://discourse.gohugo.io/t/new-docs-site-need-feedback/5765/6-->

+{{% note %}}

+The example site used below is from https://github.com/gohugoio/hugo/examples/blog

+{{% /note %}}

-<!-- Lots of forums threads that give the same answers. Should call attention to --verbose, --stepAnalysis, and --renderToMemory (for troubleshooting disk I/O). Highlight partialCached template function. -->

+## Template Metrics

+Hugo is a very fast static site generator, but it is possible to write

+inefficient templates.  Hugo's *template metrics* feature is extremely helpful

+in pinpointing which templates are executed most often and how long those

+executions take **in terms of CPU time**.

+| Metric Name         | Description |

+|---------------------|-------------|

+| cumulative duration | The cumulative time spent executing a given template. |

+| average duration    | The average time spent executing a given template. |

+| maximum duration    | The maximum time a single execution took for a given template. |

+| count               | The number of times a template was executed. |

+| template            | The template name. |

+```

+▶ hugo --templateMetrics

+Started building sites ...

+Built site for language en:

+0 draft content

+0 future content

+0 expired content

+2 regular pages created

+22 other pages created

+0 non-page files copied

+0 paginator pages created

+4 tags created

+3 categories created

+total in 18 ms

+Template Metrics:

+     cumulative       average       maximum

+       duration      duration      duration  count  template

+     ----------      --------      --------  -----  --------

+     6.419663ms     583.605µs     994.374µs     11  _internal/_default/rss.xml

+     4.718511ms    1.572837ms    3.880742ms      3  indexes/category.html

+     4.642666ms    2.321333ms    3.282842ms      2  post/single.html

+     4.364445ms     396.767µs    2.451372ms     11  partials/header.html

+     2.346069ms     586.517µs     903.343µs      4  indexes/tag.html

+     2.330919ms     211.901µs    2.281342ms     11  partials/header.includes.html

+     1.238976ms     103.248µs     446.084µs     12  post/li.html

+       972.16µs      972.16µs      972.16µs      1  _internal/_default/sitemap.xml

+      953.597µs     953.597µs     953.597µs      1  index.html

+      822.263µs     822.263µs     822.263µs      1  indexes/post.html

+      567.498µs       51.59µs     112.205µs     11  partials/navbar.html

+       348.22µs      31.656µs      88.249µs     11  partials/meta.html

+      346.782µs     173.391µs     276.176µs      2  post/summary.html

+      235.184µs       21.38µs     124.383µs     11  partials/footer.copyright.html

+      132.003µs          12µs     117.999µs     11  partials/menu.html

+       72.547µs       6.595µs      63.764µs     11  partials/footer.html

+```

+{{% note %}}

+**A Note About Parallelism**

+Hugo builds pages in parallel where multiple pages are generated

+simultaneously. Because of this parallelism, the sum of "cumulative duration"

+values is usually greater than the actual time it takes to build a site.

+{{% /note %}}

+## Cached Partials

+Some `partial` templates such as sidebars or menus are executed many times

+during a site build.  Depending on the content within the `partial` template and

+the desired output, the template may benefit from caching to reduce the number

+of executions.  The [`partialCached`][partialCached] template function provides

+caching capabilities for `partial` templates.

+{{% tip %}}

+Note that you can create cached variants of each `partial` by passing additional

+parameters to `partialCached` beyond the initial context.  See the

+`partialCached` documentation for more details.

+{{% /tip %}}

+## Step Analysis

+Hugo provides a means of seeing metrics about each step in the site build

+process.  We call that *Step Analysis*.  The *step analysis* output shows the

+total time per step, the cumulative time after each step (in parentheses),

+the memory usage per step, and the total memory allocations per step.

+To enable *step analysis*, use the `--stepAnalysis` option when running Hugo.

+[partialCached]:{{< ref "functions/partialCached.md" >}}

--- a/layouts/shortcodes/code.html

+++ b/layouts/shortcodes/code.html

@@ -1,6 +1,6 @@

 {{ $file := .Get "file" }}

 {{ $isHTML := strings.HasSuffix $file "html" }}

-<div class="code relative bg-primary-color" id="{{ $file | urlize}}">

+<div class="code relative" id="{{ $file | urlize}}">

 	{{- with $file -}}

 		<div class="filename san-serif f6 dib lh-solid pl2 pv2">{{.}}</div>

 	{{- end -}}

--- /dev/null

+++ b/themes/gohugoioTheme/src/css/_chroma.css

@@ -1,0 +1,43 @@

+/* Background */ .chroma { background-color: #f0f0f0 }

+/* Error */ .chroma .ss4 {  }

+/* LineHighlight */ .chroma .hl { background-color: #ffffcc; display: block; width: 100% }

+/* LineNumbers */ .chroma .ln { ; margin-right: 0.4em; padding: 0 0.4em 0 0.4em; }

+/* Keyword */ .chroma .s3e8 { color: #007020; font-weight: bold }

+/* KeywordPseudo */ .chroma .s3ec { color: #007020 }

+/* KeywordType */ .chroma .s3ee { color: #902000 }

+/* NameAttribute */ .chroma .s7d1 { color: #4070a0 }

+/* NameBuiltin */ .chroma .s7d2 { color: #007020 }

+/* NameClass */ .chroma .s7d4 { color: #0e84b5; font-weight: bold }

+/* NameConstant */ .chroma .s7d5 { color: #60add5 }

+/* NameDecorator */ .chroma .s7d6 { color: #555555; font-weight: bold }

+/* NameEntity */ .chroma .s7d7 { color: #d55537; font-weight: bold }

+/* NameException */ .chroma .s7d8 { color: #007020 }

+/* NameFunction */ .chroma .s7d9 { color: #06287e }

+/* NameLabel */ .chroma .s7dc { color: #002070; font-weight: bold }

+/* NameNamespace */ .chroma .s7dd { color: #0e84b5; font-weight: bold }

+/* NameTag */ .chroma .s7e2 { color: #062873; font-weight: bold }

+/* NameVariable */ .chroma .s7e3 { color: #bb60d5 }

+/* LiteralString */ .chroma .sc1c { color: #4070a0 }

+/* LiteralStringDoc */ .chroma .sc23 { color: #4070a0; font-style: italic }

+/* LiteralStringEscape */ .chroma .sc25 { color: #4070a0; font-weight: bold }

+/* LiteralStringInterpol */ .chroma .sc27 { color: #70a0d0; font-style: italic }

+/* LiteralStringOther */ .chroma .sc29 { color: #c65d09 }

+/* LiteralStringRegex */ .chroma .sc2a { color: #235388 }

+/* LiteralStringSymbol */ .chroma .sc2c { color: #517918 }

+/* LiteralNumber */ .chroma .sc80 { color: #40a070 }

+/* Operator */ .chroma .sfa0 { color: #666666 }

+/* OperatorWord */ .chroma .sfa1 { color: #007020; font-weight: bold }

+/* Comment */ .chroma .s1770 { color: #60a0b0; font-style: italic }

+/* CommentSpecial */ .chroma .s1774 { color: #60a0b0; background-color: #fff0f0 }

+/* CommentPreproc */ .chroma .s17d4 { color: #007020 }

+/* GenericDeleted */ .chroma .s1b59 { color: #a00000 }

+/* GenericEmph */ .chroma .s1b5a { font-style: italic }

+/* GenericError */ .chroma .s1b5b { color: #ff0000 }

+/* GenericHeading */ .chroma .s1b5c { color: #000080; font-weight: bold }

+/* GenericInserted */ .chroma .s1b5d { color: #00a000 }

+/* GenericOutput */ .chroma .s1b5e { color: #888888 }

+/* GenericPrompt */ .chroma .s1b5f { color: #c65d09; font-weight: bold }

+/* GenericStrong */ .chroma .s1b60 { font-weight: bold }

+/* GenericSubheading */ .chroma .s1b61 { color: #800080; font-weight: bold }

+/* GenericTraceback */ .chroma .s1b62 { color: #0044dd }

+/* TextWhitespace */ .chroma .s1f41 { color: #bbbbbb }

--- /dev/null

+++ b/themes/gohugoioTheme/src/css/_chroma2.css

@@ -1,0 +1,64 @@

+/* Background */ .chroma { background-color: #f0f0f0 }

+/* Error */ .chroma .err {  }

+/* LineHighlight */ .chroma .hl { background-color: #ffffcc; display: block; width: 100% }

+/* LineNumbers */ .chroma .ln { ; margin-right: 0.4em; padding: 0 0.4em 0 0.4em; }

+/* Keyword */ .chroma .k { color: #007020; font-weight: bold }

+/* KeywordConstant */ .chroma .kc { color: #007020; font-weight: bold }

+/* KeywordDeclaration */ .chroma .kd { color: #007020; font-weight: bold }

+/* KeywordNamespace */ .chroma .kn { color: #007020; font-weight: bold }

+/* KeywordPseudo */ .chroma .kp { color: #007020 }

+/* KeywordReserved */ .chroma .kr { color: #007020; font-weight: bold }

+/* KeywordType */ .chroma .kt { color: #902000 }

+/* NameAttribute */ .chroma .na { color: #4070a0 }

+/* NameBuiltin */ .chroma .nb { color: #007020 }

+/* NameClass */ .chroma .nc { color: #0e84b5; font-weight: bold }

+/* NameConstant */ .chroma .no { color: #60add5 }

+/* NameDecorator */ .chroma .nd { color: #555555; font-weight: bold }

+/* NameEntity */ .chroma .ni { color: #d55537; font-weight: bold }

+/* NameException */ .chroma .ne { color: #007020 }

+/* NameFunction */ .chroma .nf { color: #06287e }

+/* NameLabel */ .chroma .nl { color: #002070; font-weight: bold }

+/* NameNamespace */ .chroma .nn { color: #0e84b5; font-weight: bold }

+/* NameTag */ .chroma .nt { color: #062873; font-weight: bold }

+/* NameVariable */ .chroma .nv { color: #bb60d5 }

+/* LiteralString */ .chroma .s { color: #4070a0 }

+/* LiteralStringAffix */ .chroma .sa { color: #4070a0 }

+/* LiteralStringBacktick */ .chroma .sb { color: #4070a0 }

+/* LiteralStringChar */ .chroma .sc { color: #4070a0 }

+/* LiteralStringDelimiter */ .chroma .dl { color: #4070a0 }

+/* LiteralStringDoc */ .chroma .sd { color: #4070a0; font-style: italic }

+/* LiteralStringDouble */ .chroma .s2 { color: #4070a0 }

+/* LiteralStringEscape */ .chroma .se { color: #4070a0; font-weight: bold }

+/* LiteralStringHeredoc */ .chroma .sh { color: #4070a0 }

+/* LiteralStringInterpol */ .chroma .si { color: #70a0d0; font-style: italic }

+/* LiteralStringOther */ .chroma .sx { color: #c65d09 }

+/* LiteralStringRegex */ .chroma .sr { color: #235388 }

+/* LiteralStringSingle */ .chroma .s1 { color: #4070a0 }

+/* LiteralStringSymbol */ .chroma .ss { color: #517918 }

+/* LiteralNumber */ .chroma .m { color: #40a070 }

+/* LiteralNumberBin */ .chroma .mb { color: #40a070 }

+/* LiteralNumberFloat */ .chroma .mf { color: #40a070 }

+/* LiteralNumberHex */ .chroma .mh { color: #40a070 }

+/* LiteralNumberInteger */ .chroma .mi { color: #40a070 }

+/* LiteralNumberIntegerLong */ .chroma .il { color: #40a070 }

+/* LiteralNumberOct */ .chroma .mo { color: #40a070 }

+/* Operator */ .chroma .o { color: #666666 }

+/* OperatorWord */ .chroma .ow { color: #007020; font-weight: bold }

+/* Comment */ .chroma .c { color: #60a0b0; font-style: italic }

+/* CommentHashbang */ .chroma .ch { color: #60a0b0; font-style: italic }

+/* CommentMultiline */ .chroma .cm { color: #60a0b0; font-style: italic }

+/* CommentSingle */ .chroma .c1 { color: #60a0b0; font-style: italic }

+/* CommentSpecial */ .chroma .cs { color: #60a0b0; background-color: #fff0f0 }

+/* CommentPreproc */ .chroma .cp { color: #007020 }

+/* CommentPreprocFile */ .chroma .cpf { color: #007020 }

+/* GenericDeleted */ .chroma .gd { color: #a00000 }

+/* GenericEmph */ .chroma .ge { font-style: italic }

+/* GenericError */ .chroma .gr { color: #ff0000 }

+/* GenericHeading */ .chroma .gh { color: #000080; font-weight: bold }

+/* GenericInserted */ .chroma .gi { color: #00a000 }

+/* GenericOutput */ .chroma .go { color: #888888 }

+/* GenericPrompt */ .chroma .gp { color: #c65d09; font-weight: bold }

+/* GenericStrong */ .chroma .gs { font-weight: bold }

+/* GenericSubheading */ .chroma .gu { color: #800080; font-weight: bold }

+/* GenericTraceback */ .chroma .gt { color: #0044dd }

+/* TextWhitespace */ .chroma .w { color: #bbbbbb }

--- a/themes/gohugoioTheme/src/css/main.css

+++ b/themes/gohugoioTheme/src/css/main.css

@@ -26,6 +26,7 @@

 @import '_svg';

 @import '_chroma';

+@import '_chroma2';

 @import '_variables';

 .nested-blockquote blockquote {