github/hugo
1
0
Fork 0
mirror of https://github.com/gohugoio/hugo.git synced 2024-11-29 07:42:05 -05:00
Code Issues Projects Releases Packages Wiki Activity

Merge commit '61c27b58b353c73772aae572c7d822fdfdf7791b'

Browse source
This commit is contained in:
Bjørn Erik Pedersen 2017-09-25 09:02:42 +02:00
commit 932ae52709
39 changed files with 511 additions and 339 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

4
docs/README.md
View file

@ -10,6 +10,10 @@ Note that this repository contains solely the documentation for Hugo. For contri
*Pull requests shall **only** contain changes to the actual documentation. However, changes on the code base of Hugo **and** the documentation shall be a single, atomic pull request in the [hugo](https://github.com/gohugoio/hugo) repository.* *Pull requests shall **only** contain changes to the actual documentation. However, changes on the code base of Hugo **and** the documentation shall be a single, atomic pull request in the [hugo](https://github.com/gohugoio/hugo) repository.*
## Branches
* The `master` branch is where the site is automatically built from, and is the place to put changes relevant to the current Hugo version.
* The `next` branch is where we store changes that is related to the next Hugo release. This can be previewed here: https://next--gohugoio.netlify.com/
## Build ## Build

5
docs/config.toml
View file

@ -21,6 +21,11 @@ disableAliases = true
# It is (currently) not in use, but you can do ```go in a content file if you want to. # It is (currently) not in use, but you can do ```go in a content file if you want to.
pygmentsCodeFences = true pygmentsCodeFences = true
pygmentsOptions = ""
# Use the Chroma stylesheet
pygmentsUseClasses = true
pygmentsUseClassic = false
# See https://help.farbox.com/pygments.html # See https://help.farbox.com/pygments.html
pygmentsStyle = "friendly" pygmentsStyle = "friendly"

22
docs/content/commands/_index.md
View file

@ -1,22 +0,0 @@
---
title: Command Line Reference
linktitle: CLI Overview
description: Comprehensive list of Hugo templating functions, including basic and advanced usage examples.
date: 2017-02-01
publishdate: 2017-02-01
lastmod: 2017-02-01
categories: [commands]
keywords: [cli,command line]
menu:
docs:
parent: "commands"
weight: 1
weight: 01 #rem
draft: false
aliases: [/cli/]
---
The following list contains auto-generated and up-to-date (thanks to [Cobra][]) documentation for all the CLI commands in Hugo.
[Cobra]: https://github.com/spf13/cobra

5
docs/content/commands/hugo.md
View file

@ -1,5 +1,5 @@
--- ---
date: 2017-07-16T23:23:14+02:00 date: 2017-09-25T08:30:15+02:00
title: "hugo" title: "hugo"
slug: hugo slug: hugo
url: /commands/hugo/ url: /commands/hugo/
@ -34,6 +34,7 @@ hugo [flags]
--cleanDestinationDir remove files from destination not found in static directories --cleanDestinationDir remove files from destination not found in static directories
--config string config file (default is path/config.yaml|json|toml) --config string config file (default is path/config.yaml|json|toml)
-c, --contentDir string filesystem path to content directory -c, --contentDir string filesystem path to content directory
--debug debug output
-d, --destination string filesystem path to write files to -d, --destination string filesystem path to write files to
--disable404 do not render 404 page --disable404 do not render 404 page
--disableKinds stringSlice disable different kind of pages (home, RSS etc.) --disableKinds stringSlice disable different kind of pages (home, RSS etc.)
@ -77,4 +78,4 @@ hugo [flags]
* [hugo undraft](/commands/hugo_undraft/) - Undraft resets the content's draft status * [hugo undraft](/commands/hugo_undraft/) - Undraft resets the content's draft status
* [hugo version](/commands/hugo_version/) - Print the version number of Hugo * [hugo version](/commands/hugo_version/) - Print the version number of Hugo
###### Auto generated by spf13/cobra on 16-Jul-2017 ###### Auto generated by spf13/cobra on 25-Sep-2017

5
docs/content/commands/hugo_benchmark.md
View file

@ -1,5 +1,5 @@
--- ---
date: 2017-07-16T23:23:14+02:00 date: 2017-09-25T08:30:15+02:00
title: "hugo benchmark" title: "hugo benchmark"
slug: hugo_benchmark slug: hugo_benchmark
url: /commands/hugo_benchmark/ url: /commands/hugo_benchmark/
@ -59,6 +59,7 @@ hugo benchmark [flags]
``` ```
--config string config file (default is path/config.yaml|json|toml) --config string config file (default is path/config.yaml|json|toml)
--debug debug output
--log enable Logging --log enable Logging
--logFile string log File path (if set, logging enabled automatically) --logFile string log File path (if set, logging enabled automatically)
--quiet build in quiet mode --quiet build in quiet mode
@ -69,4 +70,4 @@ hugo benchmark [flags]
### SEE ALSO ### SEE ALSO
* [hugo](/commands/hugo/) - hugo builds your site * [hugo](/commands/hugo/) - hugo builds your site
###### Auto generated by spf13/cobra on 16-Jul-2017 ###### Auto generated by spf13/cobra on 25-Sep-2017

5
docs/content/commands/hugo_check.md
View file

@ -1,5 +1,5 @@
--- ---
date: 2017-07-16T23:23:14+02:00 date: 2017-09-25T08:30:15+02:00
title: "hugo check" title: "hugo check"
slug: hugo_check slug: hugo_check
url: /commands/hugo_check/ url: /commands/hugo_check/
@ -23,6 +23,7 @@ Contains some verification checks
``` ```
--config string config file (default is path/config.yaml|json|toml) --config string config file (default is path/config.yaml|json|toml)
--debug debug output
--log enable Logging --log enable Logging
--logFile string log File path (if set, logging enabled automatically) --logFile string log File path (if set, logging enabled automatically)
--quiet build in quiet mode --quiet build in quiet mode
@ -34,4 +35,4 @@ Contains some verification checks
* [hugo](/commands/hugo/) - hugo builds your site * [hugo](/commands/hugo/) - hugo builds your site
* [hugo check ulimit](/commands/hugo_check_ulimit/) - Check system ulimit settings * [hugo check ulimit](/commands/hugo_check_ulimit/) - Check system ulimit settings
###### Auto generated by spf13/cobra on 16-Jul-2017 ###### Auto generated by spf13/cobra on 25-Sep-2017

5
docs/content/commands/hugo_check_ulimit.md
View file

@ -1,5 +1,5 @@
--- ---
date: 2017-07-16T23:23:14+02:00 date: 2017-09-25T08:30:15+02:00
title: "hugo check ulimit" title: "hugo check ulimit"
slug: hugo_check_ulimit slug: hugo_check_ulimit
url: /commands/hugo_check_ulimit/ url: /commands/hugo_check_ulimit/
@ -28,6 +28,7 @@ hugo check ulimit [flags]
``` ```
--config string config file (default is path/config.yaml|json|toml) --config string config file (default is path/config.yaml|json|toml)
--debug debug output
--log enable Logging --log enable Logging
--logFile string log File path (if set, logging enabled automatically) --logFile string log File path (if set, logging enabled automatically)
--quiet build in quiet mode --quiet build in quiet mode
@ -38,4 +39,4 @@ hugo check ulimit [flags]
### SEE ALSO ### SEE ALSO
* [hugo check](/commands/hugo_check/) - Contains some verification checks * [hugo check](/commands/hugo_check/) - Contains some verification checks
###### Auto generated by spf13/cobra on 16-Jul-2017 ###### Auto generated by spf13/cobra on 25-Sep-2017

5
docs/content/commands/hugo_config.md
View file

@ -1,5 +1,5 @@
--- ---
date: 2017-07-16T23:23:14+02:00 date: 2017-09-25T08:30:15+02:00
title: "hugo config" title: "hugo config"
slug: hugo_config slug: hugo_config
url: /commands/hugo_config/ url: /commands/hugo_config/
@ -27,6 +27,7 @@ hugo config [flags]
``` ```
--config string config file (default is path/config.yaml|json|toml) --config string config file (default is path/config.yaml|json|toml)
--debug debug output
--log enable Logging --log enable Logging
--logFile string log File path (if set, logging enabled automatically) --logFile string log File path (if set, logging enabled automatically)
--quiet build in quiet mode --quiet build in quiet mode
@ -37,4 +38,4 @@ hugo config [flags]
### SEE ALSO ### SEE ALSO
* [hugo](/commands/hugo/) - hugo builds your site * [hugo](/commands/hugo/) - hugo builds your site
###### Auto generated by spf13/cobra on 16-Jul-2017 ###### Auto generated by spf13/cobra on 25-Sep-2017

5
docs/content/commands/hugo_convert.md
View file

@ -1,5 +1,5 @@
--- ---
date: 2017-07-16T23:23:14+02:00 date: 2017-09-25T08:30:15+02:00
title: "hugo convert" title: "hugo convert"
slug: hugo_convert slug: hugo_convert
url: /commands/hugo_convert/ url: /commands/hugo_convert/
@ -28,6 +28,7 @@ See convert's subcommands toJSON, toTOML and toYAML for more information.
``` ```
--config string config file (default is path/config.yaml|json|toml) --config string config file (default is path/config.yaml|json|toml)
--debug debug output
--log enable Logging --log enable Logging
--logFile string log File path (if set, logging enabled automatically) --logFile string log File path (if set, logging enabled automatically)
--quiet build in quiet mode --quiet build in quiet mode
@ -41,4 +42,4 @@ See convert's subcommands toJSON, toTOML and toYAML for more information.
* [hugo convert toTOML](/commands/hugo_convert_totoml/) - Convert front matter to TOML * [hugo convert toTOML](/commands/hugo_convert_totoml/) - Convert front matter to TOML
* [hugo convert toYAML](/commands/hugo_convert_toyaml/) - Convert front matter to YAML * [hugo convert toYAML](/commands/hugo_convert_toyaml/) - Convert front matter to YAML
###### Auto generated by spf13/cobra on 16-Jul-2017 ###### Auto generated by spf13/cobra on 25-Sep-2017

5
docs/content/commands/hugo_convert_toJSON.md
View file

@ -1,5 +1,5 @@
--- ---
date: 2017-07-16T23:23:14+02:00 date: 2017-09-25T08:30:15+02:00
title: "hugo convert toJSON" title: "hugo convert toJSON"
slug: hugo_convert_toJSON slug: hugo_convert_toJSON
url: /commands/hugo_convert_tojson/ url: /commands/hugo_convert_tojson/
@ -28,6 +28,7 @@ hugo convert toJSON [flags]
``` ```
--config string config file (default is path/config.yaml|json|toml) --config string config file (default is path/config.yaml|json|toml)
--debug debug output
--log enable Logging --log enable Logging
--logFile string log File path (if set, logging enabled automatically) --logFile string log File path (if set, logging enabled automatically)
-o, --output string filesystem path to write files to -o, --output string filesystem path to write files to
@ -41,4 +42,4 @@ hugo convert toJSON [flags]
### SEE ALSO ### SEE ALSO
* [hugo convert](/commands/hugo_convert/) - Convert your content to different formats * [hugo convert](/commands/hugo_convert/) - Convert your content to different formats
###### Auto generated by spf13/cobra on 16-Jul-2017 ###### Auto generated by spf13/cobra on 25-Sep-2017

5
docs/content/commands/hugo_convert_toTOML.md
View file

@ -1,5 +1,5 @@
--- ---
date: 2017-07-16T23:23:14+02:00 date: 2017-09-25T08:30:15+02:00
title: "hugo convert toTOML" title: "hugo convert toTOML"
slug: hugo_convert_toTOML slug: hugo_convert_toTOML
url: /commands/hugo_convert_totoml/ url: /commands/hugo_convert_totoml/
@ -28,6 +28,7 @@ hugo convert toTOML [flags]
``` ```
--config string config file (default is path/config.yaml|json|toml) --config string config file (default is path/config.yaml|json|toml)
--debug debug output
--log enable Logging --log enable Logging
--logFile string log File path (if set, logging enabled automatically) --logFile string log File path (if set, logging enabled automatically)
-o, --output string filesystem path to write files to -o, --output string filesystem path to write files to
@ -41,4 +42,4 @@ hugo convert toTOML [flags]
### SEE ALSO ### SEE ALSO
* [hugo convert](/commands/hugo_convert/) - Convert your content to different formats * [hugo convert](/commands/hugo_convert/) - Convert your content to different formats
###### Auto generated by spf13/cobra on 16-Jul-2017 ###### Auto generated by spf13/cobra on 25-Sep-2017

5
docs/content/commands/hugo_convert_toYAML.md
View file

@ -1,5 +1,5 @@
--- ---
date: 2017-07-16T23:23:14+02:00 date: 2017-09-25T08:30:15+02:00
title: "hugo convert toYAML" title: "hugo convert toYAML"
slug: hugo_convert_toYAML slug: hugo_convert_toYAML
url: /commands/hugo_convert_toyaml/ url: /commands/hugo_convert_toyaml/
@ -28,6 +28,7 @@ hugo convert toYAML [flags]
``` ```
--config string config file (default is path/config.yaml|json|toml) --config string config file (default is path/config.yaml|json|toml)
--debug debug output
--log enable Logging --log enable Logging
--logFile string log File path (if set, logging enabled automatically) --logFile string log File path (if set, logging enabled automatically)
-o, --output string filesystem path to write files to -o, --output string filesystem path to write files to
@ -41,4 +42,4 @@ hugo convert toYAML [flags]
### SEE ALSO ### SEE ALSO
* [hugo convert](/commands/hugo_convert/) - Convert your content to different formats * [hugo convert](/commands/hugo_convert/) - Convert your content to different formats
###### Auto generated by spf13/cobra on 16-Jul-2017 ###### Auto generated by spf13/cobra on 25-Sep-2017

5
docs/content/commands/hugo_env.md
View file

@ -1,5 +1,5 @@
--- ---
date: 2017-07-16T23:23:14+02:00 date: 2017-09-25T08:30:15+02:00
title: "hugo env" title: "hugo env"
slug: hugo_env slug: hugo_env
url: /commands/hugo_env/ url: /commands/hugo_env/
@ -27,6 +27,7 @@ hugo env [flags]
``` ```
--config string config file (default is path/config.yaml|json|toml) --config string config file (default is path/config.yaml|json|toml)
--debug debug output
--log enable Logging --log enable Logging
--logFile string log File path (if set, logging enabled automatically) --logFile string log File path (if set, logging enabled automatically)
--quiet build in quiet mode --quiet build in quiet mode
@ -37,4 +38,4 @@ hugo env [flags]
### SEE ALSO ### SEE ALSO
* [hugo](/commands/hugo/) - hugo builds your site * [hugo](/commands/hugo/) - hugo builds your site
###### Auto generated by spf13/cobra on 16-Jul-2017 ###### Auto generated by spf13/cobra on 25-Sep-2017

6
docs/content/commands/hugo_gen.md
View file

@ -1,5 +1,5 @@
--- ---
date: 2017-07-16T23:23:14+02:00 date: 2017-09-25T08:30:15+02:00
title: "hugo gen" title: "hugo gen"
slug: hugo_gen slug: hugo_gen
url: /commands/hugo_gen/ url: /commands/hugo_gen/
@ -23,6 +23,7 @@ A collection of several useful generators.
``` ```
--config string config file (default is path/config.yaml|json|toml) --config string config file (default is path/config.yaml|json|toml)
--debug debug output
--log enable Logging --log enable Logging
--logFile string log File path (if set, logging enabled automatically) --logFile string log File path (if set, logging enabled automatically)
--quiet build in quiet mode --quiet build in quiet mode
@ -33,7 +34,8 @@ A collection of several useful generators.
### SEE ALSO ### SEE ALSO
* [hugo](/commands/hugo/) - hugo builds your site * [hugo](/commands/hugo/) - hugo builds your site
* [hugo gen autocomplete](/commands/hugo_gen_autocomplete/) - Generate shell autocompletion script for Hugo * [hugo gen autocomplete](/commands/hugo_gen_autocomplete/) - Generate shell autocompletion script for Hugo
* [hugo gen chromastyles](/commands/hugo_gen_chromastyles/) - Generate CSS stylesheet for the Chroma code highlighter
* [hugo gen doc](/commands/hugo_gen_doc/) - Generate Markdown documentation for the Hugo CLI. * [hugo gen doc](/commands/hugo_gen_doc/) - Generate Markdown documentation for the Hugo CLI.
* [hugo gen man](/commands/hugo_gen_man/) - Generate man pages for the Hugo CLI * [hugo gen man](/commands/hugo_gen_man/) - Generate man pages for the Hugo CLI
###### Auto generated by spf13/cobra on 16-Jul-2017 ###### Auto generated by spf13/cobra on 25-Sep-2017

5
docs/content/commands/hugo_gen_autocomplete.md
View file

@ -1,5 +1,5 @@
--- ---
date: 2017-07-16T23:23:14+02:00 date: 2017-09-25T08:30:15+02:00
title: "hugo gen autocomplete" title: "hugo gen autocomplete"
slug: hugo_gen_autocomplete slug: hugo_gen_autocomplete
url: /commands/hugo_gen_autocomplete/ url: /commands/hugo_gen_autocomplete/
@ -45,6 +45,7 @@ hugo gen autocomplete [flags]
``` ```
--config string config file (default is path/config.yaml|json|toml) --config string config file (default is path/config.yaml|json|toml)
--debug debug output
--log enable Logging --log enable Logging
--logFile string log File path (if set, logging enabled automatically) --logFile string log File path (if set, logging enabled automatically)
--quiet build in quiet mode --quiet build in quiet mode
@ -55,4 +56,4 @@ hugo gen autocomplete [flags]
### SEE ALSO ### SEE ALSO
* [hugo gen](/commands/hugo_gen/) - A collection of several useful generators. * [hugo gen](/commands/hugo_gen/) - A collection of several useful generators.
###### Auto generated by spf13/cobra on 16-Jul-2017 ###### Auto generated by spf13/cobra on 25-Sep-2017

46
docs/content/commands/hugo_gen_chromastyles.md Normal file
View file

@ -0,0 +1,46 @@
---
date: 2017-09-25T08:30:15+02:00
title: "hugo gen chromastyles"
slug: hugo_gen_chromastyles
url: /commands/hugo_gen_chromastyles/
---
## hugo gen chromastyles
Generate CSS stylesheet for the Chroma code highlighter
### Synopsis
Generate CSS stylesheet for the Chroma code highlighter for a given style. This stylesheet is needed if pygmentsUseClasses is enabled in config.
See https://help.farbox.com/pygments.html for preview of available styles
```
hugo gen chromastyles [flags]
```
### Options
```
-h, --help help for chromastyles
--highlightStyle string style used for highlighting lines (see https://github.com/alecthomas/chroma) (default "bg:#ffffcc")
--linesStyle string style used for line numbers (see https://github.com/alecthomas/chroma)
--style string highlighter style (see https://help.farbox.com/pygments.html) (default "friendly")
```
### Options inherited from parent commands
```
--config string config file (default is path/config.yaml|json|toml)
--debug debug output
--log enable Logging
--logFile string log File path (if set, logging enabled automatically)
--quiet build in quiet mode
-v, --verbose verbose output
--verboseLog verbose logging
```
### SEE ALSO
* [hugo gen](/commands/hugo_gen/) - A collection of several useful generators.
###### Auto generated by spf13/cobra on 25-Sep-2017

5
docs/content/commands/hugo_gen_doc.md
View file

@ -1,5 +1,5 @@
--- ---
date: 2017-07-16T23:23:14+02:00 date: 2017-09-25T08:30:15+02:00
title: "hugo gen doc" title: "hugo gen doc"
slug: hugo_gen_doc slug: hugo_gen_doc
url: /commands/hugo_gen_doc/ url: /commands/hugo_gen_doc/
@ -34,6 +34,7 @@ hugo gen doc [flags]
``` ```
--config string config file (default is path/config.yaml|json|toml) --config string config file (default is path/config.yaml|json|toml)
--debug debug output
--log enable Logging --log enable Logging
--logFile string log File path (if set, logging enabled automatically) --logFile string log File path (if set, logging enabled automatically)
--quiet build in quiet mode --quiet build in quiet mode
@ -44,4 +45,4 @@ hugo gen doc [flags]
### SEE ALSO ### SEE ALSO
* [hugo gen](/commands/hugo_gen/) - A collection of several useful generators. * [hugo gen](/commands/hugo_gen/) - A collection of several useful generators.
###### Auto generated by spf13/cobra on 16-Jul-2017 ###### Auto generated by spf13/cobra on 25-Sep-2017

5
docs/content/commands/hugo_gen_man.md
View file

@ -1,5 +1,5 @@
--- ---
date: 2017-07-16T23:23:14+02:00 date: 2017-09-25T08:30:15+02:00
title: "hugo gen man" title: "hugo gen man"
slug: hugo_gen_man slug: hugo_gen_man
url: /commands/hugo_gen_man/ url: /commands/hugo_gen_man/
@ -30,6 +30,7 @@ hugo gen man [flags]
``` ```
--config string config file (default is path/config.yaml|json|toml) --config string config file (default is path/config.yaml|json|toml)
--debug debug output
--log enable Logging --log enable Logging
--logFile string log File path (if set, logging enabled automatically) --logFile string log File path (if set, logging enabled automatically)
--quiet build in quiet mode --quiet build in quiet mode
@ -40,4 +41,4 @@ hugo gen man [flags]
### SEE ALSO ### SEE ALSO
* [hugo gen](/commands/hugo_gen/) - A collection of several useful generators. * [hugo gen](/commands/hugo_gen/) - A collection of several useful generators.
###### Auto generated by spf13/cobra on 16-Jul-2017 ###### Auto generated by spf13/cobra on 25-Sep-2017

5
docs/content/commands/hugo_import.md
View file

@ -1,5 +1,5 @@
--- ---
date: 2017-07-16T23:23:14+02:00 date: 2017-09-25T08:30:15+02:00
title: "hugo import" title: "hugo import"
slug: hugo_import slug: hugo_import
url: /commands/hugo_import/ url: /commands/hugo_import/
@ -25,6 +25,7 @@ Import requires a subcommand, e.g. `hugo import jekyll jekyll_root_path target_p
``` ```
--config string config file (default is path/config.yaml|json|toml) --config string config file (default is path/config.yaml|json|toml)
--debug debug output
--log enable Logging --log enable Logging
--logFile string log File path (if set, logging enabled automatically) --logFile string log File path (if set, logging enabled automatically)
--quiet build in quiet mode --quiet build in quiet mode
@ -36,4 +37,4 @@ Import requires a subcommand, e.g. `hugo import jekyll jekyll_root_path target_p
* [hugo](/commands/hugo/) - hugo builds your site * [hugo](/commands/hugo/) - hugo builds your site
* [hugo import jekyll](/commands/hugo_import_jekyll/) - hugo import from Jekyll * [hugo import jekyll](/commands/hugo_import_jekyll/) - hugo import from Jekyll
###### Auto generated by spf13/cobra on 16-Jul-2017 ###### Auto generated by spf13/cobra on 25-Sep-2017

5
docs/content/commands/hugo_import_jekyll.md
View file

@ -1,5 +1,5 @@
--- ---
date: 2017-07-16T23:23:14+02:00 date: 2017-09-25T08:30:15+02:00
title: "hugo import jekyll" title: "hugo import jekyll"
slug: hugo_import_jekyll slug: hugo_import_jekyll
url: /commands/hugo_import_jekyll/ url: /commands/hugo_import_jekyll/
@ -30,6 +30,7 @@ hugo import jekyll [flags]
``` ```
--config string config file (default is path/config.yaml|json|toml) --config string config file (default is path/config.yaml|json|toml)
--debug debug output
--log enable Logging --log enable Logging
--logFile string log File path (if set, logging enabled automatically) --logFile string log File path (if set, logging enabled automatically)
--quiet build in quiet mode --quiet build in quiet mode
@ -40,4 +41,4 @@ hugo import jekyll [flags]
### SEE ALSO ### SEE ALSO
* [hugo import](/commands/hugo_import/) - Import your site from others. * [hugo import](/commands/hugo_import/) - Import your site from others.
###### Auto generated by spf13/cobra on 16-Jul-2017 ###### Auto generated by spf13/cobra on 25-Sep-2017

5
docs/content/commands/hugo_list.md
View file

@ -1,5 +1,5 @@
--- ---
date: 2017-07-16T23:23:14+02:00 date: 2017-09-25T08:30:15+02:00
title: "hugo list" title: "hugo list"
slug: hugo_list slug: hugo_list
url: /commands/hugo_list/ url: /commands/hugo_list/
@ -26,6 +26,7 @@ List requires a subcommand, e.g. `hugo list drafts`.
``` ```
--config string config file (default is path/config.yaml|json|toml) --config string config file (default is path/config.yaml|json|toml)
--debug debug output
--log enable Logging --log enable Logging
--logFile string log File path (if set, logging enabled automatically) --logFile string log File path (if set, logging enabled automatically)
--quiet build in quiet mode --quiet build in quiet mode
@ -39,4 +40,4 @@ List requires a subcommand, e.g. `hugo list drafts`.
* [hugo list expired](/commands/hugo_list_expired/) - List all posts already expired * [hugo list expired](/commands/hugo_list_expired/) - List all posts already expired
* [hugo list future](/commands/hugo_list_future/) - List all posts dated in the future * [hugo list future](/commands/hugo_list_future/) - List all posts dated in the future
###### Auto generated by spf13/cobra on 16-Jul-2017 ###### Auto generated by spf13/cobra on 25-Sep-2017

5
docs/content/commands/hugo_list_drafts.md
View file

@ -1,5 +1,5 @@
--- ---
date: 2017-07-16T23:23:14+02:00 date: 2017-09-25T08:30:15+02:00
title: "hugo list drafts" title: "hugo list drafts"
slug: hugo_list_drafts slug: hugo_list_drafts
url: /commands/hugo_list_drafts/ url: /commands/hugo_list_drafts/
@ -27,6 +27,7 @@ hugo list drafts [flags]
``` ```
--config string config file (default is path/config.yaml|json|toml) --config string config file (default is path/config.yaml|json|toml)
--debug debug output
--log enable Logging --log enable Logging
--logFile string log File path (if set, logging enabled automatically) --logFile string log File path (if set, logging enabled automatically)
--quiet build in quiet mode --quiet build in quiet mode
@ -38,4 +39,4 @@ hugo list drafts [flags]
### SEE ALSO ### SEE ALSO
* [hugo list](/commands/hugo_list/) - Listing out various types of content * [hugo list](/commands/hugo_list/) - Listing out various types of content
###### Auto generated by spf13/cobra on 16-Jul-2017 ###### Auto generated by spf13/cobra on 25-Sep-2017

5
docs/content/commands/hugo_list_expired.md
View file

@ -1,5 +1,5 @@
--- ---
date: 2017-07-16T23:23:14+02:00 date: 2017-09-25T08:30:15+02:00
title: "hugo list expired" title: "hugo list expired"
slug: hugo_list_expired slug: hugo_list_expired
url: /commands/hugo_list_expired/ url: /commands/hugo_list_expired/
@ -28,6 +28,7 @@ hugo list expired [flags]
``` ```
--config string config file (default is path/config.yaml|json|toml) --config string config file (default is path/config.yaml|json|toml)
--debug debug output
--log enable Logging --log enable Logging
--logFile string log File path (if set, logging enabled automatically) --logFile string log File path (if set, logging enabled automatically)
--quiet build in quiet mode --quiet build in quiet mode
@ -39,4 +40,4 @@ hugo list expired [flags]
### SEE ALSO ### SEE ALSO
* [hugo list](/commands/hugo_list/) - Listing out various types of content * [hugo list](/commands/hugo_list/) - Listing out various types of content
###### Auto generated by spf13/cobra on 16-Jul-2017 ###### Auto generated by spf13/cobra on 25-Sep-2017

5
docs/content/commands/hugo_list_future.md
View file

@ -1,5 +1,5 @@
--- ---
date: 2017-07-16T23:23:14+02:00 date: 2017-09-25T08:30:15+02:00
title: "hugo list future" title: "hugo list future"
slug: hugo_list_future slug: hugo_list_future
url: /commands/hugo_list_future/ url: /commands/hugo_list_future/
@ -28,6 +28,7 @@ hugo list future [flags]
``` ```
--config string config file (default is path/config.yaml|json|toml) --config string config file (default is path/config.yaml|json|toml)
--debug debug output
--log enable Logging --log enable Logging
--logFile string log File path (if set, logging enabled automatically) --logFile string log File path (if set, logging enabled automatically)
--quiet build in quiet mode --quiet build in quiet mode
@ -39,4 +40,4 @@ hugo list future [flags]
### SEE ALSO ### SEE ALSO
* [hugo list](/commands/hugo_list/) - Listing out various types of content * [hugo list](/commands/hugo_list/) - Listing out various types of content
###### Auto generated by spf13/cobra on 16-Jul-2017 ###### Auto generated by spf13/cobra on 25-Sep-2017

5
docs/content/commands/hugo_new.md
View file

@ -1,5 +1,5 @@
--- ---
date: 2017-07-16T23:23:14+02:00 date: 2017-09-25T08:30:15+02:00
title: "hugo new" title: "hugo new"
slug: hugo_new slug: hugo_new
url: /commands/hugo_new/ url: /commands/hugo_new/
@ -35,6 +35,7 @@ hugo new [path] [flags]
``` ```
--config string config file (default is path/config.yaml|json|toml) --config string config file (default is path/config.yaml|json|toml)
--debug debug output
--log enable Logging --log enable Logging
--logFile string log File path (if set, logging enabled automatically) --logFile string log File path (if set, logging enabled automatically)
--quiet build in quiet mode --quiet build in quiet mode
@ -47,4 +48,4 @@ hugo new [path] [flags]
* [hugo new site](/commands/hugo_new_site/) - Create a new site (skeleton) * [hugo new site](/commands/hugo_new_site/) - Create a new site (skeleton)
* [hugo new theme](/commands/hugo_new_theme/) - Create a new theme * [hugo new theme](/commands/hugo_new_theme/) - Create a new theme
###### Auto generated by spf13/cobra on 16-Jul-2017 ###### Auto generated by spf13/cobra on 25-Sep-2017

5
docs/content/commands/hugo_new_site.md
View file

@ -1,5 +1,5 @@
--- ---
date: 2017-07-16T23:23:14+02:00 date: 2017-09-25T08:30:15+02:00
title: "hugo new site" title: "hugo new site"
slug: hugo_new_site slug: hugo_new_site
url: /commands/hugo_new_site/ url: /commands/hugo_new_site/
@ -31,6 +31,7 @@ hugo new site [path] [flags]
``` ```
--config string config file (default is path/config.yaml|json|toml) --config string config file (default is path/config.yaml|json|toml)
--debug debug output
--log enable Logging --log enable Logging
--logFile string log File path (if set, logging enabled automatically) --logFile string log File path (if set, logging enabled automatically)
--quiet build in quiet mode --quiet build in quiet mode
@ -42,4 +43,4 @@ hugo new site [path] [flags]
### SEE ALSO ### SEE ALSO
* [hugo new](/commands/hugo_new/) - Create new content for your site * [hugo new](/commands/hugo_new/) - Create new content for your site
###### Auto generated by spf13/cobra on 16-Jul-2017 ###### Auto generated by spf13/cobra on 25-Sep-2017

5
docs/content/commands/hugo_new_theme.md
View file

@ -1,5 +1,5 @@
--- ---
date: 2017-07-16T23:23:14+02:00 date: 2017-09-25T08:30:15+02:00
title: "hugo new theme" title: "hugo new theme"
slug: hugo_new_theme slug: hugo_new_theme
url: /commands/hugo_new_theme/ url: /commands/hugo_new_theme/
@ -30,6 +30,7 @@ hugo new theme [name] [flags]
``` ```
--config string config file (default is path/config.yaml|json|toml) --config string config file (default is path/config.yaml|json|toml)
--debug debug output
--log enable Logging --log enable Logging
--logFile string log File path (if set, logging enabled automatically) --logFile string log File path (if set, logging enabled automatically)
--quiet build in quiet mode --quiet build in quiet mode
@ -41,4 +42,4 @@ hugo new theme [name] [flags]
### SEE ALSO ### SEE ALSO
* [hugo new](/commands/hugo_new/) - Create new content for your site * [hugo new](/commands/hugo_new/) - Create new content for your site
###### Auto generated by spf13/cobra on 16-Jul-2017 ###### Auto generated by spf13/cobra on 25-Sep-2017

7
docs/content/commands/hugo_server.md
View file

@ -1,5 +1,5 @@
--- ---
date: 2017-07-16T23:23:14+02:00 date: 2017-09-25T08:30:15+02:00
title: "hugo server" title: "hugo server"
slug: hugo_server slug: hugo_server
url: /commands/hugo_server/ url: /commands/hugo_server/
@ -53,10 +53,12 @@ hugo server [flags]
--i18n-warnings print missing translations --i18n-warnings print missing translations
--ignoreCache ignores the cache directory --ignoreCache ignores the cache directory
-l, --layoutDir string filesystem path to layout directory -l, --layoutDir string filesystem path to layout directory
--liveReloadPort int port for live reloading (i.e. 443 in HTTPS proxy situations) (default -1)
--meminterval string interval to poll memory usage (requires --memstats), valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h". (default "100ms") --meminterval string interval to poll memory usage (requires --memstats), valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h". (default "100ms")
--memstats string log memory usage to this file --memstats string log memory usage to this file
--navigateToChanged navigate to changed content file on live browser reload --navigateToChanged navigate to changed content file on live browser reload
--noChmod don't sync permission mode of files --noChmod don't sync permission mode of files
--noHTTPCache prevent HTTP caching (default true)
--noTimes don't sync modification time of files --noTimes don't sync modification time of files
--pluralizeListTitles pluralize titles in lists using inflect (default true) --pluralizeListTitles pluralize titles in lists using inflect (default true)
-p, --port int port on which the server will listen (default 1313) -p, --port int port on which the server will listen (default 1313)
@ -74,6 +76,7 @@ hugo server [flags]
``` ```
--config string config file (default is path/config.yaml|json|toml) --config string config file (default is path/config.yaml|json|toml)
--debug debug output
--log enable Logging --log enable Logging
--logFile string log File path (if set, logging enabled automatically) --logFile string log File path (if set, logging enabled automatically)
--quiet build in quiet mode --quiet build in quiet mode
@ -84,4 +87,4 @@ hugo server [flags]
### SEE ALSO ### SEE ALSO
* [hugo](/commands/hugo/) - hugo builds your site * [hugo](/commands/hugo/) - hugo builds your site
###### Auto generated by spf13/cobra on 16-Jul-2017 ###### Auto generated by spf13/cobra on 25-Sep-2017

5
docs/content/commands/hugo_undraft.md
View file

@ -1,5 +1,5 @@
--- ---
date: 2017-07-16T23:23:14+02:00 date: 2017-09-25T08:30:15+02:00
title: "hugo undraft" title: "hugo undraft"
slug: hugo_undraft slug: hugo_undraft
url: /commands/hugo_undraft/ url: /commands/hugo_undraft/
@ -29,6 +29,7 @@ hugo undraft path/to/content [flags]
``` ```
--config string config file (default is path/config.yaml|json|toml) --config string config file (default is path/config.yaml|json|toml)
--debug debug output
--log enable Logging --log enable Logging
--logFile string log File path (if set, logging enabled automatically) --logFile string log File path (if set, logging enabled automatically)
--quiet build in quiet mode --quiet build in quiet mode
@ -39,4 +40,4 @@ hugo undraft path/to/content [flags]
### SEE ALSO ### SEE ALSO
* [hugo](/commands/hugo/) - hugo builds your site * [hugo](/commands/hugo/) - hugo builds your site
###### Auto generated by spf13/cobra on 16-Jul-2017 ###### Auto generated by spf13/cobra on 25-Sep-2017

5
docs/content/commands/hugo_version.md
View file

@ -1,5 +1,5 @@
--- ---
date: 2017-07-16T23:23:14+02:00 date: 2017-09-25T08:30:15+02:00
title: "hugo version" title: "hugo version"
slug: hugo_version slug: hugo_version
url: /commands/hugo_version/ url: /commands/hugo_version/
@ -27,6 +27,7 @@ hugo version [flags]
``` ```
--config string config file (default is path/config.yaml|json|toml) --config string config file (default is path/config.yaml|json|toml)
--debug debug output
--log enable Logging --log enable Logging
--logFile string log File path (if set, logging enabled automatically) --logFile string log File path (if set, logging enabled automatically)
--quiet build in quiet mode --quiet build in quiet mode
@ -37,4 +38,4 @@ hugo version [flags]
### SEE ALSO ### SEE ALSO
* [hugo](/commands/hugo/) - hugo builds your site * [hugo](/commands/hugo/) - hugo builds your site
###### Auto generated by spf13/cobra on 16-Jul-2017 ###### Auto generated by spf13/cobra on 25-Sep-2017

188
docs/content/content-management/syntax-highlighting.md Normal file
View file

@ -0,0 +1,188 @@
---
title: Syntax Highlighting
description: Hugo comes with reallly fast syntax highlighting from Chroma.
date: 2017-02-01
publishdate: 2017-02-01
keywords: [highlighting,pygments,chroma,code blocks,syntax]
categories: [content management]
menu:
docs:
parent: "content-management"
weight: 300
weight: 20
sections_weight: 20
draft: false
aliases: [/extras/highlighting/,/extras/highlight/,/tools/syntax-highlighting/]
toc: true
---
From Hugo 0.28, the default syntax hightlighter in Hugo is [Chroma](https://github.com/alecthomas/chroma); it is built in Go and is really, really fast -- and for the most important parts compatible with Pygments.
If you want to continue to use Pygments (see below), set `pygmentsUseClassic=true` in your site config.
The example below shows a simple code snippet from the Hugo source highlighted with the `highlight` shortcode. Note that the gohugo.io site is generated with `pygmentsUseClasses=true` (see [Generate Syntax Highlighter CSS](#generate-syntax-highlighter-css)).
* `linenos=inline` turns on line numbers. Note that the `inline` value only has an effect in Pygments.
* `hl_lines` lists a set of line numbers or line number ranges to be highlighted. Note that the hyphen range syntax is only supported for Chroma.
* `linenostart=199` starts the line number count from 199.
With that, this:
```
{{</* highlight go "linenos=inline,hl_lines=8 15-17,linenostart=199" */>}}
// ... code
{{</* / highlight */>}}
```
Gives this:
{{< highlight go "linenos=inline,hl_lines=8 15-17,linenostart=199" >}}
// GetTitleFunc returns a func that can be used to transform a string to
// title case.
//
// The supported styles are
//
// - "Go" (strings.Title)
// - "AP" (see https://www.apstylebook.com/)
// - "Chicago" (see http://www.chicagomanualofstyle.org/home.html)
//
// If an unknown or empty style is provided, AP style is what you get.
func GetTitleFunc(style string) func(s string) string {
switch strings.ToLower(style) {
case "go":
return strings.Title
case "chicago":
tc := transform.NewTitleConverter(transform.ChicagoStyle)
return tc.Title
default:
tc := transform.NewTitleConverter(transform.APStyle)
return tc.Title
}
}
{{< / highlight >}}
## Configure Syntax Hightlighter
To make the transition from Pygments to Chroma seamless, they share a common set of configuration options:
pygmentsOptions
: A comma separated list of options. See below for a full list.
pygmentsCodefences
: Set to true to enable syntax highlighting in code fences with a language tag in markdown (see below for an example).
pygmentsStyle
: The style of code highlighting. See https://help.farbox.com/pygments.html for a gallery. Note that this option is not relevant when `pygmentsUseClasses` is set.
pygmentsUseClasses
: Set to `true` to use CSS classes to format your highlighted code. See [Generate Syntax Highlighter CSS](#generate-syntax-highlighter-css).
pygmentsCodefencesGuessSyntax
: Set to `true` to try to do syntax highlighting on code fenced blocks in markdown without a language tag.
pygmentsUseClassic
: Set to true to use Pygments instead of the much faster Chroma.
### Options
`pygmentsOptions` can be set either in site config or overridden per code block in the Highlight shortcode or template func.
noclasses
: Use inline style.
linenos
: For Chroma, any value in this setting will print line numbers. Pygments has some more fine grained control.
linenostart
: Start the line numbers from this value (default is 1).
hl_lines
: Highlight a space separated list of line numbers. For Chroma, you can provide a list of ranges, i.e. "3-8 10-20".
The full set of supported options for Pygments is: `encoding`, `outencoding`, `nowrap`, `full`, `title`, `style`, `noclasses`, `classprefix`, `cssclass`, `cssstyles`, `prestyles`, `linenos`, `hl_lines`, `linenostart`, `linenostep`, `linenospecial`, `nobackground`, `lineseparator`, `lineanchors`, `linespans`, `anchorlinenos`, `startinline`. See the [Pygments Documentation](http://pygments.org/) for details.
## Generate Syntax Highlighter CSS
If you run with `pygmentsUseClassic=true` in your site config, you need a style sheet.
You can generate one with Hugo:
```bash
hugo gen chromastyles --style=monokai > syntax.css
```
Run `hugo gen chromastyles -h` for more options. See https://help.farbox.com/pygments.html for a gallery of available styles.
## Highlight Shortcode
Highlighting is carried out via the [built-in shortcode](/content-management/shortcodes/) `highlight`. `highlight` takes exactly one required parameter for the programming language to be highlighted and requires a closing shortcode. Note that `highlight` is *not* used for client-side javascript highlighting.
### Example `highlight` Shortcode
{{< code file="example-highlight-shortcode-input.md" >}}
{{</* highlight html */>}}
<section id="main">
<div>
<h1 id="title">{{ .Title }}</h1>
{{ range .Data.Pages }}
{{ .Render "summary"}}
{{ end }}
</div>
</section>
{{</* /highlight */>}}
{{< /code >}}
## Highlight Template Func
See [Highlight](/functions/highlight/).
## Highlight in Code Fences
It is also possible to add syntax highlighting with GitHub flavored code fences. To enable this, set the `pygmentsCodeFences` to `true` in Hugo's [configuration file](/getting-started/configuration/);
````
```html
<section id="main">
<div>
<h1 id="title">{{ .Title }}</h1>
{{ range .Data.Pages }}
{{ .Render "summary"}}
{{ end }}
</div>
</section>
```
````
## Highlight with Pygments Classic
If you for some reason don't want to use the built-in Chroma highlighter, you can set `pygmentsUseClassic=true` in your config and add Pygments to your path.
{{% note "Disclaimers on Pygments" %}}
* Pygments is relatively slow and _causes a performance hit when building your site_, but Hugo has been designed to cache the results to disk.
* The caching can be turned off by setting the `--ignoreCache` flag to `true`.
* The languages available for highlighting depend on your Pygments installation.
{{% /note %}}
If you have never worked with Pygments before, here is a brief primer:
+ Install Python from [python.org](https://www.python.org/downloads/). Version 2.7.x is already sufficient.
+ Run `pip install Pygments` in order to install Pygments. Once installed, Pygments gives you a command `pygmentize`. Make sure it sits in your PATH; otherwise, Hugo will not be able to find and use it.
On Debian and Ubuntu systems, you may also install Pygments by running `sudo apt-get install python3-pygments`.
[Prism]: http://prismjs.com
[prismdownload]: http://prismjs.com/download.html
[Highlight.js]: http://highlightjs.org/
[Rainbow]: http://craig.is/making/rainbows
[Syntax Highlighter]: http://alexgorbatchev.com/SyntaxHighlighter/
[Google Prettify]: https://github.com/google/code-prettify
[Yandex]: http://yandex.ru/

2
docs/content/functions/highlight.md
View file

@ -11,7 +11,7 @@ menu:
docs: docs:
parent: "functions" parent: "functions"
keywords: [highlighting,pygments,code blocks,syntax] keywords: [highlighting,pygments,code blocks,syntax]
signature: ["highlight INPUT"] signature: ["highlight INPUT LANG OPTIONS"]
workson: [] workson: []
hugoversion: hugoversion:
relatedfuncs: [] relatedfuncs: []

2
docs/content/templates/internal.md
View file

@ -129,5 +129,3 @@ You can then render your custom Disqus partial template as follows:
* `_internal/schema.html` * `_internal/schema.html`
* `_internal/twitter_cards.html` * `_internal/twitter_cards.html`
[disqus]: https://disqus.com
[disqussignup]: https://disqus.com/profile/signup/

237
docs/content/tools/syntax-highlighting.md
View file

@ -1,237 +0,0 @@
---
title: Syntax Highlighting
linktitle:
description: Hugo provides server-side syntax highlighting via Pygments and, like most static site generators, works very well with client-side (JavaScript) syntax highlighting libraries as well.
date: 2017-02-01
publishdate: 2017-02-01
lastmod: 2017-02-01
keywords: [highlighting,pygments,code blocks,syntax]
categories: [developer tools]
menu:
docs:
parent: "tools"
weight: 20
weight: 20
sections_weight: 20
draft: false
aliases: [/extras/highlighting/,/extras/highlight/]
toc: true
---
Hugo can highlight source code in _two different ways_&mdash;either pre-processed server side from your content or to defer the processing to the client side, using a JavaScript library.
## Server-side
For the pre-processed approach, highlighting is performed by an external Python-based program called [Pygments](http://pygments.org/) and is triggered via an embedded Hugo shortcode (see [example](#example-highlight-shortcode-input) below). If Pygments is absent from the path, it will silently simply pass the content along without highlighting.
### Server-side Advantages
The advantages of server-side syntax highlighting are that it doesn’t depend on a JavaScript library and, consequently, works very well when read from an RSS feed.
### Pygments
If you have never worked with Pygments before, here is a brief primer:
+ Install Python from [python.org](https://www.python.org/downloads/). Version 2.7.x is already sufficient.
+ Run `pip install Pygments` in order to install Pygments. Once installed, Pygments gives you a command `pygmentize`. Make sure it sits in your PATH; otherwise, Hugo will not be able to find and use it.
On Debian and Ubuntu systems, you may also install Pygments by running `sudo apt-get install python3-pygments`.
Hugo gives you two options that you can set with the variable `pygmentsuseclasses` (default `false`) in your [site configuration](/getting-started/configuration/).
1. Color codes for highlighting keywords are directly inserted if `pygmentsuseclasses = false` (default). The color codes depend on your choice of the `pygmentsstyle` (default = `"monokai"`). You can explore the different color styles on [pygments.org](http://pygments.org/) after inserting some example code.
2. If you choose `pygmentsuseclasses = true`, Hugo includes class names in your code instead of color codes. For class-names to be meaningful, you need to include a `.css` file in your website representing your color scheme. You can either generate this `.css` files according to the [description from the Pygments documentation](http://pygments.org/docs/cmdline/) or download the one of the many pre-built color schemes from [Pygment's GitHub css repository](https://github.com/richleland/pygments-css).
### Server-side Usage
Highlighting is carried out via the [built-in shortcode](/content-management/shortcodes/) `highlight`. `highlight` takes exactly one required parameter for the programming language to be highlighted and requires a closing shortcode. Note that `highlight` is *not* used for client-side javascript highlighting.
### Example `highlight` Shortcode Input
{{< code file="example-highlight-shortcode-input.md" >}}
{{</* highlight html */>}}
<section id="main">
<div>
<h1 id="title">{{ .Title }}</h1>
{{ range .Data.Pages }}
{{ .Render "summary"}}
{{ end }}
</div>
</section>
{{</* /highlight */>}}
{{< /code >}}
### Example `highlight` Shortcode Output
{{< output file="example-highlight-shortcode-output.html" >}}
<span style="color: #f92672">&lt;section</span> <span style="color: #a6e22e">id=</span><span style="color: #e6db74">&quot;main&quot;</span><span style="color: #f92672">&gt;</span>
<span style="color: #f92672">&lt;div&gt;</span>
<span style="color: #f92672">&lt;h1</span> <span style="color: #a6e22e">id=</span><span style="color: #e6db74">&quot;title&quot;</span><span style="color: #f92672">&gt;</span>{{ .Title }}<span style="color: #f92672">&lt;/h1&gt;</span>
{{ range .Data.Pages }}
{{ .Render &quot;summary&quot;}}
{{ end }}
<span style="color: #f92672">&lt;/div&gt;</span>
<span style="color: #f92672">&lt;/section&gt;</span>
{{< /output >}}
### Options
Options for controlling highlighting can be added in the second argument as a quoted, comma-separated key-value list. The example below will syntax highlight in `go` with inline line numbers and line numbers 2 and 3 highlighted.
```
{{</* highlight go "linenos=inline,hl_lines=2 3" */>}}
var a string
var b string
var c string
var d string
{{</* / highlight */>}}
```
The `highlight` shortcode includes the following supported keywords:
* `style`
* `encoding`
* `noclasses`
* `hl_lines`
* `linenos`
Note that `style` and `noclasses` will override the similar setting in the [global config](/getting-started/configuration/).
The keywords in the `highlight` shortcode mirror those of Pygments from the command line. See the [Pygments documentation](http://pygments.org/docs/) for more information.
### Code Fences
It is also possible to add syntax highlighting with GitHub flavored code fences. To enable this, set the `PygmentsCodeFences` to `true` in Hugo's [configuration file](/getting-started/configuration/);
````
```
<section id="main">
<div>
<h1 id="title">{{ .Title }}</h1>
{{ range .Data.Pages }}
{{ .Render "summary"}}
{{ end }}
</div>
</section>
```
````
{{% note "Disclaimers on Pygments" %}}
* Pygments is relatively slow and _causes a performance hit when building your site_, but Hugo has been designed to cache the results to disk.
* The caching can be turned off by setting the `--ignoreCache` flag to `true`.
* The languages available for highlighting depend on your Pygments installation.
{{% /note %}}
## Client-side
Alternatively, code highlighting can be applied to your code blocks in client-side JavaScript.
Client-side syntax highlighting is very simple to add. You'll need to pick
a library and a corresponding theme. Some popular libraries are:
- [Highlight.js]
- [Prism]
- [Rainbow]
- [Syntax Highlighter]
- [Google Prettify]
### Client-side Advantages
The advantages of client-side syntax highlighting are that it doesn’t cost anything when building your site, and some of the highlighting scripts available cover more languages than Pygments does.
### Highlight.js Example
This example uses the popular [Highlight.js] library, hosted by [Yandex], a popular Russian search engine.
In your `./layouts/partials/` (or `./layouts/chrome/`) folder, depending on your specific theme, there will be a snippet that will be included in every generated HTML page, such as `header.html` or `header.includes.html`. Simply add the css and js to initialize [Highlight.js]:
```
<link rel="stylesheet" href="//cdnjs.cloudflare.com/ajax/libs/highlight.js/9.6.0/styles/default.min.css">
<script src="//cdnjs.cloudflare.com/ajax/libs/highlight.js/9.6.0/highlight.min.js"></script>
<script>hljs.initHighlightingOnLoad();</script>
```
### Prism example
Prism is another popular highlighter library and is used on some major sites.
The [download section of the prism.js website][prismdownload] is simple to use and affords you a high degree of customization to pick only the languages you'll be using on your site.
Similar to Highlight.js, you simply load `prism.css` in your `<head>` via whatever Hugo partial template is creating that part of your pages:
```
...
<link href="/css/prism.css" rel="stylesheet" />
...
```
Add `prism.js` near the bottom of your `<body>` tag in whatever Hugo partial template is appropriate for your site or theme.
```
...
<script src="/js/prism.js"></script>
</body>
```
In this example, the local paths indicate that your downloaded copy of these files are being added to the site, typically under `./static/css/` and `./static/js/`, respectively.
### Client-side Usage
To use client-side highlighting, most of these javascript libraries expect your code to be wrapped in semantically correct `<code>` elements with language-specific class attributes. For example, a code block for HTML would have `class="language-html"`.
The client-side highlighting script therefore looks for programming language classes according to this convention: `language-go`, `language-html`, `language-css`, `language-bash`, etc. If you look at the page's source, you might see something like the following:
```
<pre>
<code class="language-css">
body {
font-family: "Noto Sans", sans-serif;
}
</code>
</pre>
```
If you are using markdown, your content pages needs to use the following syntax, with the name of the language to be highlighted entered directly after the first "fence." A fenced code block can be noted by opening and closing triple tilde <kbd>~</kbd> or triple back ticks <kbd>`</kbd>:
{{< nohighlight >}}
~~~css
body {
font-family: "Noto Sans", sans-serif;
}
~~~
{{< /nohighlight >}}
Here is the same example but with triple back ticks to denote the fenced code block:
{{< nohighlight >}}
```css
body {
font-family: "Noto Sans", sans-serif;
}
```
{{< /nohighlight >}}
Passing the above examples through the highlighter script would yield the following markup:
{{< nohighlight >}}
&lt;pre&gt;&lt;code class="language-css hljs"&gt;;&lt;span class="hljs-selector-tag"&gt;body&lt;/span&gt; {
&lt;span class="hljs-attribute"&gt;font-family&lt;/span&gt;: &ltspan class="hljs-string"&gt;"Noto Sans"&lt;/span&gt;, sans-serif;
}
{{< /nohighlight >}}
In the case of the coding color scheme used by the Hugo docs, the resulting output would then look like the following to the website's end users:
```
body {
font-family: "Noto Sans", sans-serif;
}
```
Please see individual libraries' documentation for how to implement each of the JavaScript-based libraries.
[Prism]: http://prismjs.com
[prismdownload]: http://prismjs.com/download.html
[Highlight.js]: http://highlightjs.org/
[Rainbow]: http://craig.is/making/rainbows
[Syntax Highlighter]: http://alexgorbatchev.com/SyntaxHighlighter/
[Google Prettify]: https://github.com/google/code-prettify
[Yandex]: http://yandex.ru/

154
docs/data/docs.json
View file

@ -384,6 +384,23 @@
} }
}, },
"compare": { "compare": {
"Conditional": {
"Description": "Conditional can be used as a ternary operator.\nIt returns a if condition, else b.",
"Args": [
"condition",
"a",
"b"
],
"Aliases": [
"cond"
],
"Examples": [
[
"{{ cond (eq (add 2 2) 4) \"2+2 is 4\" \"what?\" | safeHTML }}",
"2+2 is 4"
]
]
},
"Default": { "Default": {
"Description": "Default checks whether a given value is set and returns a default value if it\nis not. \"Set\" in this context means non-zero for numeric types and times;\nnon-zero length for strings, arrays, slices, and maps;\nany boolean or struct value; or non-nil for any other types.", "Description": "Default checks whether a given value is set and returns a default value if it\nis not. \"Set\" in this context means non-zero for numeric types and times;\nnon-zero length for strings, arrays, slices, and maps;\nany boolean or struct value; or non-nil for any other types.",
"Args": [ "Args": [
@ -604,6 +621,22 @@
], ],
"Examples": [] "Examples": []
}, },
"KeyVals": {
"Description": "KeyVals creates a key and values wrapper.",
"Args": [
"key",
"vals"
],
"Aliases": [
"keyVals"
],
"Examples": [
[
"{{ keyVals \"key\" \"a\" \"b\" }}",
"key: [a b]"
]
]
},
"Last": { "Last": {
"Description": "Last returns the last N items in a rangeable list.", "Description": "Last returns the last N items in a rangeable list.",
"Args": [ "Args": [
@ -856,7 +889,7 @@
}, },
"fmt": { "fmt": {
"Print": { "Print": {
"Description": "", "Description": "Print returns string representation of the passed arguments.",
"Args": [ "Args": [
"a" "a"
], ],
@ -871,7 +904,7 @@
] ]
}, },
"Printf": { "Printf": {
"Description": "", "Description": "Printf returns a formatted string representation of the passed arguments.",
"Args": [ "Args": [
"format", "format",
"a" "a"
@ -887,7 +920,7 @@
] ]
}, },
"Println": { "Println": {
"Description": "", "Description": "Print returns string representation of the passed arguments ending with a newline.",
"Args": [ "Args": [
"a" "a"
], ],
@ -1020,7 +1053,7 @@
}, },
"math": { "math": {
"Add": { "Add": {
"Description": "", "Description": "Add adds two numbers.",
"Args": [ "Args": [
"a", "a",
"b" "b"
@ -1036,7 +1069,7 @@
] ]
}, },
"Div": { "Div": {
"Description": "", "Description": "Div divides two numbers.",
"Args": [ "Args": [
"a", "a",
"b" "b"
@ -1052,7 +1085,7 @@
] ]
}, },
"Log": { "Log": {
"Description": "", "Description": "Log returns the natural logarithm of a number.",
"Args": [ "Args": [
"a" "a"
], ],
@ -1097,7 +1130,7 @@
] ]
}, },
"Mul": { "Mul": {
"Description": "", "Description": "Mul multiplies two numbers.",
"Args": [ "Args": [
"a", "a",
"b" "b"
@ -1113,7 +1146,7 @@
] ]
}, },
"Sub": { "Sub": {
"Description": "", "Description": "Sub subtracts two numbers.",
"Args": [ "Args": [
"a", "a",
"b" "b"
@ -1156,7 +1189,7 @@
] ]
}, },
"ReadFile": { "ReadFile": {
"Description": "ReadFilereads the file named by filename relative to the configured\nWorkingDir. It returns the contents as a string. There is a upper size\nlimit set at 1 megabytes.", "Description": "ReadFile reads the file named by filename relative to the configured WorkingDir.\nIt returns the contents as a string.\nThere is an upper size limit set at 1 megabytes.",
"Args": [ "Args": [
"i" "i"
], ],
@ -1469,6 +1502,10 @@
[ [
"{{title \"Bat man\"}}", "{{title \"Bat man\"}}",
"Bat Man" "Bat Man"
],
[
"{{title \"somewhere over the rainbow\"}}",
"Somewhere Over the Rainbow"
] ]
] ]
}, },
@ -1518,20 +1555,72 @@
] ]
] ]
}, },
"TrimPrefix": { "TrimLeft": {
"Description": "", "Description": "TrimLeft returns a slice of the string s with all leading characters\ncontained in cutset removed.",
"Args": null, "Args": [
"cutset",
"s"
],
"Aliases": null, "Aliases": null,
"Examples": null "Examples": [
[
"{{ \"aabbaa\" | strings.TrimLeft \"a\" }}",
"bbaa"
]
]
},
"TrimPrefix": {
"Description": "TrimPrefix returns s without the provided leading prefix string. If s doesn't\nstart with prefix, s is returned unchanged.",
"Args": [
"prefix",
"s"
],
"Aliases": null,
"Examples": [
[
"{{ \"aabbaa\" | strings.TrimPrefix \"a\" }}",
"abbaa"
],
[
"{{ \"aabbaa\" | strings.TrimPrefix \"aa\" }}",
"bbaa"
]
]
},
"TrimRight": {
"Description": "TrimRight returns a slice of the string s with all trailing characters\ncontained in cutset removed.",
"Args": [
"cutset",
"s"
],
"Aliases": null,
"Examples": [
[
"{{ \"aabbaa\" | strings.TrimRight \"a\" }}",
"aabb"
]
]
}, },
"TrimSuffix": { "TrimSuffix": {
"Description": "", "Description": "TrimSuffix returns s without the provided trailing suffix string. If s\ndoesn't end with suffix, s is returned unchanged.",
"Args": null, "Args": [
"suffix",
"s"
],
"Aliases": null, "Aliases": null,
"Examples": null "Examples": [
[
"{{ \"aabbaa\" | strings.TrimSuffix \"a\" }}",
"aabba"
],
[
"{{ \"aabbaa\" | strings.TrimSuffix \"aa\" }}",
"aabb"
]
]
}, },
"Truncate": { "Truncate": {
"Description": "", "Description": "Truncate truncates a given string to the specified length.",
"Args": [ "Args": [
"a", "a",
"options" "options"
@ -1565,6 +1654,22 @@
] ]
] ]
}, },
"Duration": {
"Description": "Duration converts the given number to a time.Duration.\nUnit is one of nanosecond/ns, microsecond/us/µs, millisecond/ms, second/s, minute/m or hour/h.",
"Args": [
"unit",
"number"
],
"Aliases": [
"duration"
],
"Examples": [
[
"{{ mul 60 60 | duration \"second\" }}",
"1h0m0s"
]
]
},
"Format": { "Format": {
"Description": "Format converts the textual representation of the datetime string into\nthe other form or returns it of the time.Time value. These are formatted\nwith the layout string", "Description": "Format converts the textual representation of the datetime string into\nthe other form or returns it of the time.Time value. These are formatted\nwith the layout string",
"Args": [ "Args": [
@ -1588,6 +1693,19 @@
"now" "now"
], ],
"Examples": [] "Examples": []
},
"ParseDuration": {
"Description": "ParseDuration parses a duration string.\nA duration string is a possibly signed sequence of\ndecimal numbers, each with optional fraction and a unit suffix,\nsuch as \"300ms\", \"-1.5h\" or \"2h45m\".\nValid time units are \"ns\", \"us\" (or \"µs\"), \"ms\", \"s\", \"m\", \"h\".\nSee https://golang.org/pkg/time/#ParseDuration",
"Args": [
"in"
],
"Aliases": null,
"Examples": [
[
"{{ \"1h12m10s\" | time.ParseDuration }}",
"1h12m10s"
]
]
} }
}, },
"transform": { "transform": {
@ -1763,7 +1881,7 @@
"Examples": [] "Examples": []
}, },
"URLize": { "URLize": {
"Description": "", "Description": "URLize returns the given argument formatted as URL.",
"Args": [ "Args": [
"a" "a"
], ],

43
docs/src/css/_chroma.css Normal file
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 }

2
docs/themes/gohugoioTheme/src/css/main.css vendored
View file

@ -25,7 +25,7 @@
@import '_stickyheader'; @import '_stickyheader';
@import '_svg'; @import '_svg';
@import '_chroma';
@import '_variables'; @import '_variables';
.nested-blockquote blockquote { .nested-blockquote blockquote {

10
docs/themes/gohugoioTheme/static/dist/app.bundle.js vendored
View file

File diff suppressed because one or more lines are too long

2
docs/themes/gohugoioTheme/static/dist/main.css vendored
View file

File diff suppressed because one or more lines are too long