Squashed 'docs/' changes from 36d7e22f5..000ab7c42

000ab7c42 Fix `ref` and `relref` shortcode usage patterns 4e7123d20 Add som code fence lang tags 21d4f97d1 Update homepage for ox-hugo tool 668969fc4 Remove superflous back ticks f78cf6490 Fix code example 05aaee8ce Remove background color from code shortcode dcb0998d0 Add a Build Performance page draft 50e04593a Document templateMetrics usage 67ad36691 Merge commit 'f66d59b8991c264c3366895b5e148ea810a184cd' f66d59b89 Squashed 'themes/gohugoioTheme/' changes from ca53082d..cdaa89c8 git-subtree-dir: docs git-subtree-split: 000ab7c423341bb215d4ccb4a9e54d3d64957e24
mufidtk · Oct 4, 2017 · dae5a7c · dae5a7c
1 parent 9d68f69
commit dae5a7c
Show file tree

Hide file tree

Showing 14 changed files with 227 additions and 26 deletions.
diff --git 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 @@ hugo [flags]
 
 ### 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

diff --git a/content/content-management/cross-references.md b/content/content-management/cross-references.md
@@ -21,12 +21,12 @@ toc: true
 ## 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 @@ Ensuring heading uniqueness across the site is accomplished with a unique identi
 [built-in Hugo shortcodes]: /content-management/shortcodes/#using-the-built-in-shortcodes
 [lists]: /templates/lists/
 [output formats]: /templates/output-formats/
-[shortcode]: /content-management/shortcodes/
+[shortcode]: /content-management/shortcodes/
diff --git a/content/contribute/documentation.md b/content/contribute/documentation.md
@@ -143,8 +143,7 @@ This example HTML code block tells Hugo users the following:
 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 @@ This example HTML code block tells Hugo users the following:
     </article>
 </main>
 {{ end }}
-```
-{{%/* /code */%}}
+{{</* /code */>}}
 ```
 
 ##### Example 'code' Display

diff --git a/content/functions/partialCached.md b/content/functions/partialCached.md
@@ -10,7 +10,7 @@ categories: [functions]
 menu:
   docs:
     parent: "functions"
-keywords: []
+keywords: [performance]
 signature: ["partialCached LAYOUT INPUT [VARIANT...]"]
 workson: []
 hugoversion:

diff --git a/content/getting-started/configuration.md b/content/getting-started/configuration.md
@@ -151,6 +151,8 @@ source:                     ""
 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:                      ""

diff --git a/content/getting-started/usage.md b/content/getting-started/usage.md
@@ -44,7 +44,6 @@ Usage:
 
 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 @@ Available Commands:
   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 @@ Flags:
       --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,12 +88,18 @@ Flags:
       --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/
   -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

diff --git a/content/templates/output-formats.md b/content/templates/output-formats.md
@@ -138,7 +138,7 @@ outputs:
 
 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 @@ outputs:
 
 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,15 +162,15 @@ Note that `.Permalink` and `.RelPermalink` on `Page` will return the first outpu
 
 This is how you link to a given output format:
 
-```
+```html
 {{ with  .OutputFormats.Get "json" -}}
 <a href="{{ .Permalink }}">{{ .Name }}</a>
 {{- end }}
 ```
 
 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" */>}})
 ```

diff --git a/content/tools/editors.md b/content/tools/editors.md
@@ -31,7 +31,7 @@ The Hugo community uses a wide range of preferred tools and has developed plug-i
 ## 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
 

diff --git 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 @@ menu:
   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" >}}
diff --git 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 -}}

diff --git a/themes/gohugoioTheme/src/css/_chroma.css b/themes/gohugoioTheme/src/css/_chroma.css
@@ -0,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 }
diff --git a/themes/gohugoioTheme/src/css/_chroma2.css b/themes/gohugoioTheme/src/css/_chroma2.css
@@ -0,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 }