Permalink
Browse files

Merge commit 'dae5a7c61cceeb0de59f2d755f63e453f71dd9b2'

  • Loading branch information...
bep committed Oct 4, 2017
2 parents a58741a + dae5a7c commit 06e5633400b37bec2ebb6e4a9ea4603a0afcd010
@@ -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
@@ -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/
@@ -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
@@ -10,7 +10,7 @@ categories: [functions]
menu:
docs:
parent: "functions"
keywords: []
keywords: [performance]
signature: ["partialCached LAYOUT INPUT [VARIANT...]"]
workson: []
hugoversion:
@@ -153,6 +153,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: ""
@@ -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
@@ -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" */>}})
```
@@ -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
@@ -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" >}}
@@ -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 -}}
@@ -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 }
@@ -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 }
Oops, something went wrong.

0 comments on commit 06e5633

Please sign in to comment.