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
This commit is contained in:
Bjørn Erik Pedersen 2017-10-04 09:27:29 +02:00
parent 9d68f695e7
commit dae5a7c61c
14 changed files with 227 additions and 26 deletions

View file

@ -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

View file

@ -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.

View file

@ -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

View file

@ -10,7 +10,7 @@ categories: [functions]
menu:
docs:
parent: "functions"
keywords: []
keywords: [performance]
signature: ["partialCached LAYOUT INPUT [VARIANT...]"]
workson: []
hugoversion:

View file

@ -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: ""

View file

@ -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

View file

@ -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,7 +162,7 @@ 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 }}
@ -170,7 +170,7 @@ This is how you link to a given output format:
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" */>}})
```

View file

@ -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

View file

@ -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" >}}

View file

@ -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 -}}

View file

@ -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 }

View file

@ -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 }

View file

@ -26,6 +26,7 @@
@import '_svg';
@import '_chroma';
@import '_chroma2';
@import '_variables';
.nested-blockquote blockquote {

File diff suppressed because one or more lines are too long