From: Bjørn Erik Pedersen Date: Sat, 30 Dec 2017 08:17:23 +0000 (+0100) Subject: Merge commit 'f3cd083961f36dc96d05e98aaf67f650102bc757' X-Git-Tag: v0.32~4 X-Git-Url: http://git.maquefel.me/?a=commitdiff_plain;h=245212a5b792ad33604904556c1f5b95630d3782;p=brevno-suite%2Fhugo Merge commit 'f3cd083961f36dc96d05e98aaf67f650102bc757' --- 245212a5b792ad33604904556c1f5b95630d3782 diff --cc docs/config.toml index 4556c44a,00000000..04010a07 mode 100644,000000..100644 --- a/docs/config.toml +++ b/docs/config.toml @@@ -1,255 -1,0 +1,255 @@@ +baseURL = "https://gohugo.io/" +paginate = 100 +defaultContentLanguage = "en" +enableEmoji = true +# Set the unicode character used for the "return" link in page footnotes. +footnotereturnlinkcontents = "↩" +languageCode = "en-us" +metaDataFormat = "yaml" +title = "Hugo" +theme = "gohugoioTheme" + +googleAnalytics = "UA-7131036-4" + +pluralizeListTitles = false + +# We do redirects via Netlify's _redirects file, generated by Hugo (see "outputs" below). +disableAliases = true + + +# Highlighting config (Pygments) +# It is (currently) not in use, but you can do ```go in a content file if you want to. +pygmentsCodeFences = true + +pygmentsOptions = "" +# Use the Chroma stylesheet +pygmentsUseClasses = true +pygmentsUseClassic = false + +# See https://help.farbox.com/pygments.html +pygmentsStyle = "friendly" + +[outputs] +home = [ "HTML", "RSS", "REDIR", "HEADERS" ] +section = [ "HTML", "RSS"] + +[mediaTypes] +[mediaTypes."text/netlify"] +suffix = "" +delimiter = "" + +[outputFormats] +[outputFormats.REDIR] +mediatype = "text/netlify" +baseName = "_redirects" +isPlainText = true +notAlternative = true +[outputFormats.HEADERS] +mediatype = "text/netlify" +baseName = "_headers" +isPlainText = true +notAlternative = true + +[related] + +threshold = 80 +includeNewer = true +toLower = false + +[[related.indices]] +name = "keywords" +weight = 100 +[[related.indices]] +name = "date" +weight = 10 +pattern = "2006" + +[social] +twitter = "GoHugoIO" + +#CUSTOM PARAMS +[params] + description = "The world’s fastest framework for building websites" + ## Used for views in rendered HTML (i.e., rather than using the .Hugo variable) - release = "0.32-DEV" ++ release = "0.32" + ## Setting this to true will add a "noindex" to *EVERY* page on the site + removefromexternalsearch = false + ## Gh repo for site footer (include trailing slash) + ghrepo = "https://github.com/gohugoio/hugoDocs/" + ## GH Repo for filing a new issue + github_repo = "https://github.com/gohugoio/hugo/issues/new" + ### Edit content repo (set to automatically enter "edit" mode; this is good for "improve this page" links) + ghdocsrepo = "https://github.com/gohugoio/hugoDocs/tree/master/docs" + ## Gitter URL + gitter = "https://gitter.im/spf13/hugo" + ## Discuss Forum URL + forum = "https://discourse.gohugo.io/" + ## Google Tag Manager + gtmid = "" + + # First one is picked as the Twitter card image if not set on page. + images = ["images/gohugoio-card.png"] + + flex_box_interior_classes = "flex-auto w-100 w-40-l mr3 mb3 bg-white ba b--moon-gray nested-copy-line-height" + + #sidebar_direction = "sidebar_left" + +# MARKDOWN +## Configuration for BlackFriday markdown parser: https://github.com/russross/blackfriday +[blackfriday] + plainIDAnchors = true + hrefTargetBlank = true + angledQuotes = false + latexDashes = true + +## As of v0.20, all content files include a default "categories" value that's the same as the section. This was a cheap future-proofing method and should/could be changed accordingly. +[taxonomies] + category = "categories" + +# High level items + +[[menu.docs]] + name = "About Hugo" + weight = 1 + identifier = "about" + url = "/about/" + +[[menu.docs]] + name = "Getting Started" + weight = 5 + identifier = "getting-started" + url = "/getting-started/" + + +[[menu.docs]] + name = "Themes" + weight = 15 + identifier = "themes" + post = "break" + url = "/themes/" + +# Core Menus + +[[menu.docs]] + name = "Content Management" + weight = 20 + identifier = "content-management" + post = "expanded" + url = "/content-management/" + +[[menu.docs]] + name = "Templates" + weight = 25 + identifier = "templates" + + url = "/templates/" + +[[menu.docs]] + name = "Functions" + weight = 30 + identifier = "functions" + url = "/functions/" + +[[menu.docs]] + name = "Variables" + weight = 35 + identifier = "variables" + url = "/variables/" + +[[menu.docs]] + name = "CLI" + weight = 40 + post = "break" + identifier = "commands" + url = "/commands/" + + + +# LOW LEVEL ITEMS + + +[[menu.docs]] + name = "Troubleshooting" + weight = 60 + identifier = "troubleshooting" + url = "/troubleshooting/" + +[[menu.docs]] + name = "Tools" + weight = 70 + identifier = "tools" + url = "/tools/" + +[[menu.docs]] + name = "Hosting & Deployment" + weight = 80 + identifier = "hosting-and-deployment" + url = "/hosting-and-deployment/" + +[[menu.docs]] + name = "Contribute" + weight = 100 + post = "break" + identifier = "contribute" + url = "/contribute/" + +#[[menu.docs]] +# name = "Tags" +# weight = 120 +# identifier = "tags" +# url = "/tags/" + + +# [[menu.docs]] +# name = "Categories" +# weight = 140 +# identifier = "categories" +# url = "/categories/" + +######## QUICKLINKS + + [[menu.quicklinks]] + name = "Fundamentals" + weight = 1 + identifier = "fundamentals" + url = "/tags/fundamentals/" + + + + +######## GLOBAL ITEMS TO BE SHARED WITH THE HUGO SITES + +[[menu.global]] + name = "News" + weight = 1 + identifier = "news" + url = "/news/" + + [[menu.global]] + name = "Docs" + weight = 5 + identifier = "docs" + url = "/documentation/" + + [[menu.global]] + name = "Themes" + weight = 10 + identifier = "themes" + url = "https://themes.gohugo.io/" + + # Anything with a weight > 100 gets an external icon + [[menu.global]] + name = "Community" + weight = 150 + icon = true + identifier = "community" + post = "external" + url = "https://discourse.gohugo.io/" + + + [[menu.global]] + name = "GitHub" + weight = 200 + identifier = "github" + post = "external" + url = "https://github.com/gohugoio/hugo" diff --cc docs/content/about/new-in-032.md index 00000000,00000000..3076b3d3 new file mode 100644 --- /dev/null +++ b/docs/content/about/new-in-032.md @@@ -1,0 -1,0 +1,178 @@@ ++--- ++title: Hugo 0.32 HOWTO ++description: About page bundles, image processing and more. ++date: 2017-12-28 ++keywords: [ssg,static,performance,security] ++menu: ++ docs: ++ parent: "about" ++ weight: 10 ++weight: 10 ++sections_weight: 10 ++draft: false ++aliases: [] ++toc: true ++--- ++ ++ ++{{% note %}} ++This documentation belongs in other places in this documentation site, but is put here first ... to get something up and running fast. ++{{% /note %}} ++ ++ ++Also see this demo project from [bep](https://github.com/bep/), the clever Norwegian behind these new features: ++ ++* http://hugotest.bep.is/ ++* https://github.com/bep/hugotest (source) ++ ++## Page Resources ++ ++### Organize Your Content ++ ++{{< figure src="/images/hugo-content-bundles.png" title="Pages with image resources" >}} ++ ++The content folder above shows a mix of content pages (`md` (i.e. markdown) files) and image resources. ++ ++{{% note %}} ++You can use any file type as a content resource as long as it is a MIME type recognized by Hugo (`json` files will, as one example, work fine). If you want to get exotic, you can define your [own media type](/templates/output-formats/#media-types). ++{{% /note %}} ++ ++The 3 page bundles marked in red explained from top to bottom: ++ ++1. The home page with one image resource (`1-logo.png`) ++2. The blog section with two images resources and two pages resources (`content1.md`, `content2.md`). Note that the `_index.md` represents the URL for this section. ++3. An article (`hugo-is-cool`) with a folder with some images and one content resource (`cats-info.md`). Note that the `index.md` represents the URL for this article. ++ ++The content files below `blog/posts` are just regular standalone pages. ++ ++{{% note %}} ++Note that changes to any resource inside the `content` folder will trigger a reload when running in watch (aka server or live reload mode), it will even work with `--navigateToChanged`. ++{{% /note %}} ++ ++#### Sort Order ++ ++* Pages are sorted according to standard Hugo page sorting rules. ++* Images and other resources are sorted in lexicographical order. ++ ++### Handle Page Resources in Templates ++ ++ ++#### List all Resources ++ ++```html ++{{ range .Resources }} ++
  • {{ .ResourceType | title }}
    • ++{{ end }} ++``` ++ ++For an absolute URL, use `.Permalink`. ++ ++**Note:** The permalink will be relative to the content page, respecting permalink settings. Also, included page resources will not have a value for `RelPermalink`. ++ ++#### List All Resources by Type ++ ++```html ++{{ with .Resources.ByType "image" }} ++{{ end }} ++ ++``` ++ ++Type here is `page` for pages, else the main type in the MIME type, so `image`, `json` etc. ++ ++#### Get a Specific Resource ++ ++```html ++{{ $logo := .Resources.GetByPrefix "logo" }} ++{{ with $logo }} ++{{ end }} ++``` ++ ++#### Include Page Resource Content ++ ++```html ++{{ with .Resources.ByType "page" }} ++{{ range . }} ++

    {{ .Title }}

    ++{{ .Content }} ++{{ end }} ++{{ end }} ++ ++``` ++ ++ ++## Image Processing ++ ++The `image` resource implements the methods `Resize`, `Fit` and `Fill`: ++ ++Resize ++: Resize to the given dimension, `{{ $logo.Resize "200x" }}` will resize to 200 pixels wide and preserve the aspect ratio. Use `{{ $logo.Resize "200x100" }}` to control both height and width. ++ ++Fit ++: Scale down the image to fit the given dimensions, e.g. `{{ $logo.Fit "200x100" }}` will fit the image inside a box that is 200 pixels wide and 100 pixels high. ++ ++Fill ++: Resize and crop the image given dimensions, e.g. `{{ $logo.Fill "200x100" }}` will resize and crop to width 200 and height 100 ++ ++ ++{{% note %}} ++Image operations in Hugo currently **do not preserve EXIF data** as this is not supported by Go's [image package](https://github.com/golang/go/search?q=exif&type=Issues&utf8=%E2%9C%93). This will be improved on in the future. ++{{% /note %}} ++ ++ ++### Image Processing Options ++ ++In addition to the dimensions (e.g. `200x100`) where either height or width can be omitted, Hugo supports a set of additional image options: ++ ++Anchor ++: Only relevant for `Fill`. This is useful for thumbnail generation where the main motive is located in, say, the left corner. Valid are `Center`, `TopLeft`, `Top`, `TopRight`, `Left`, `Right`, `BottomLeft`, `Bottom`, `BottomRight`. Example: `{{ $logo.Fill "200x100 BottomLeft" }}` ++ ++JPEG Quality ++: Only relevant for JPEG images, values 1 to 100 inclusive, higher is better. Default is 75. `{{ $logo.Resize "200x q50" }}` ++ ++Rotate ++: Rotates an image by the given angle counter-clockwise. The rotation will be performed first to get the dimensions correct. `{{ $logo.Resize "200x r90" }}`. The main use of this is to be able to manually correct for [EXIF orientation](https://github.com/golang/go/issues/4341) of JPEG images. ++ ++Resample Filter ++: Filter used in resizing. Default is `Box`, a simple and fast resampling filter appropriate for downscaling. See https://github.com/disintegration/imaging for more. If you want to trade quality for faster processing, this may be a option to test. ++ ++ ++ ++### Performance ++ ++Processed images are stored below `/resources` (can be set with `resourceDir` config setting). This folder is deliberately placed in the project, as it is recommended to check these into source control as part of the project. These images are not "Hugo fast" to generate, but once generated they can be reused. ++ ++If you change your image settings (e.g. size), remove or rename images etc., you will end up with unused images taking up space and cluttering your project. ++ ++To clean up, run: ++ ++```bash ++hugo --gc ++``` ++ ++ ++{{% note %}} ++**GC** is short for **Garbage Collection**. ++{{% /note %}} ++ ++ ++## Configuration ++ ++### Default Image Processing Config ++ ++You can configure an `imaging` section in `config.toml` with default image processing options: ++ ++```toml ++[imaging] ++# Default resample filter used for resizing. Default is Box, ++# a simple and fast averaging filter appropriate for downscaling. ++# See https://github.com/disintegration/imaging ++resampleFilter = "box" ++ ++# Defatult JPEG quality setting. Default is 75. ++quality = 68 ++``` ++ ++ ++ ++ ++ diff --cc docs/content/commands/hugo.md index 83629837,00000000..847c873f mode 100644,000000..100644 --- a/docs/content/commands/hugo.md +++ b/docs/content/commands/hugo.md @@@ -1,83 -1,0 +1,84 @@@ +--- - date: 2017-11-18T10:28:35+01:00 ++date: 2017-12-28T18:49:29+01:00 +title: "hugo" +slug: hugo +url: /commands/hugo/ +--- +## hugo + +hugo builds your site + +### Synopsis + + +hugo is the main command, used to build your Hugo site. + +Hugo is a Fast and Flexible Static Site Generator +built with love by spf13 and friends in Go. + +Complete documentation is available at http://gohugo.io/. + +``` +hugo [flags] +``` + +### Options + +``` + -b, --baseURL string hostname (and path) to the root, e.g. http://spf13.com/ + -D, --buildDrafts include content marked as draft + -E, --buildExpired include expired content + -F, --buildFuture include content with publishdate in the future + --cacheDir string filesystem path to cache directory. Defaults: $TMPDIR/hugo_cache/ + --canonifyURLs if true, all relative URLs will be canonicalized using baseURL + --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.) + --disableRSS do not build RSS files + --disableSitemap do not build Sitemap file + --enableGitInfo add Git revision, date and author info to the pages + --forceSyncStatic copy all files when static is changed. ++ --gc enable to run some cleanup tasks (remove unused cache files) after the build + -h, --help help for hugo + --i18n-warnings print missing translations + --ignoreCache ignores the cache directory + -l, --layoutDir string filesystem path to layout directory + --log enable Logging + --logFile string log File path (if set, logging enabled automatically) + --noChmod don't sync permission mode of files + --noTimes don't sync modification time of files + --pluralizeListTitles pluralize titles in lists using inflect (default true) + --preserveTaxonomyNames preserve taxonomy names as written ("Gérard Depardieu" vs "gerard-depardieu") + --quiet build in quiet mode + --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 + --templateMetricsHints calculate some improvement hints when combined with --templateMetrics + -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 +``` + +### 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 +* [hugo gen](/commands/hugo_gen/) - A collection of several useful generators. +* [hugo import](/commands/hugo_import/) - Import your site from others. +* [hugo list](/commands/hugo_list/) - Listing out various types of content +* [hugo new](/commands/hugo_new/) - Create new content for your site +* [hugo server](/commands/hugo_server/) - A high performance webserver +* [hugo undraft](/commands/hugo_undraft/) - Undraft resets the content's draft status +* [hugo version](/commands/hugo_version/) - Print the version number of Hugo + - ###### Auto generated by spf13/cobra on 18-Nov-2017 ++###### Auto generated by spf13/cobra on 28-Dec-2017 diff --cc docs/content/commands/hugo_benchmark.md index ef3c2423,00000000..3d958b2f mode 100644,000000..100644 --- a/docs/content/commands/hugo_benchmark.md +++ b/docs/content/commands/hugo_benchmark.md @@@ -1,75 -1,0 +1,76 @@@ +--- - date: 2017-11-18T10:28:35+01:00 ++date: 2017-12-28T18:49:29+01:00 +title: "hugo benchmark" +slug: hugo_benchmark +url: /commands/hugo_benchmark/ +--- +## hugo benchmark + +Benchmark Hugo by building a site a number of times. + +### Synopsis + + +Hugo can build a site many times over and analyze the running process +creating a benchmark. + +``` +hugo benchmark [flags] +``` + +### Options + +``` + -b, --baseURL string hostname (and path) to the root, e.g. http://spf13.com/ + -D, --buildDrafts include content marked as draft + -E, --buildExpired include expired content + -F, --buildFuture include content with publishdate in the future + --cacheDir string filesystem path to cache directory. Defaults: $TMPDIR/hugo_cache/ + --canonifyURLs if true, all relative URLs will be canonicalized using baseURL + --cleanDestinationDir remove files from destination not found in static directories + -c, --contentDir string filesystem path to content directory + -n, --count int number of times to build the site (default 13) + --cpuprofile string path/filename for the CPU profile file + -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.) + --disableRSS do not build RSS files + --disableSitemap do not build Sitemap file + --enableGitInfo add Git revision, date and author info to the pages + --forceSyncStatic copy all files when static is changed. ++ --gc enable to run some cleanup tasks (remove unused cache files) after the build + -h, --help help for benchmark + --i18n-warnings print missing translations + --ignoreCache ignores the cache directory + -l, --layoutDir string filesystem path to layout directory + --memprofile string path/filename for the memory profile file + --noChmod don't sync permission mode of files + --noTimes don't sync modification time of files + --pluralizeListTitles pluralize titles in lists using inflect (default true) + --preserveTaxonomyNames preserve taxonomy names as written ("Gérard Depardieu" vs "gerard-depardieu") + --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 + --templateMetricsHints calculate some improvement hints when combined with --templateMetrics + -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/ +``` + +### 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](/commands/hugo/) - hugo builds your site + - ###### Auto generated by spf13/cobra on 18-Nov-2017 ++###### Auto generated by spf13/cobra on 28-Dec-2017 diff --cc docs/content/commands/hugo_check.md index fa8cc9a0,00000000..06f00c10 mode 100644,000000..100644 --- a/docs/content/commands/hugo_check.md +++ b/docs/content/commands/hugo_check.md @@@ -1,38 -1,0 +1,38 @@@ +--- - date: 2017-11-18T10:28:35+01:00 ++date: 2017-12-28T18:49:29+01:00 +title: "hugo check" +slug: hugo_check +url: /commands/hugo_check/ +--- +## hugo check + +Contains some verification checks + +### Synopsis + + +Contains some verification checks + +### Options + +``` + -h, --help help for check +``` + +### 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](/commands/hugo/) - hugo builds your site +* [hugo check ulimit](/commands/hugo_check_ulimit/) - Check system ulimit settings + - ###### Auto generated by spf13/cobra on 18-Nov-2017 ++###### Auto generated by spf13/cobra on 28-Dec-2017 diff --cc docs/content/commands/hugo_check_ulimit.md index 6b2554b4,00000000..ee0d7ecc mode 100644,000000..100644 --- a/docs/content/commands/hugo_check_ulimit.md +++ b/docs/content/commands/hugo_check_ulimit.md @@@ -1,42 -1,0 +1,42 @@@ +--- - date: 2017-11-18T10:28:35+01:00 ++date: 2017-12-28T18:49:29+01:00 +title: "hugo check ulimit" +slug: hugo_check_ulimit +url: /commands/hugo_check_ulimit/ +--- +## hugo check ulimit + +Check system ulimit settings + +### Synopsis + + +Hugo will inspect the current ulimit settings on the system. +This is primarily to ensure that Hugo can watch enough files on some OSs + +``` +hugo check ulimit [flags] +``` + +### Options + +``` + -h, --help help for ulimit +``` + +### 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 check](/commands/hugo_check/) - Contains some verification checks + - ###### Auto generated by spf13/cobra on 18-Nov-2017 ++###### Auto generated by spf13/cobra on 28-Dec-2017 diff --cc docs/content/commands/hugo_config.md index e45926f1,00000000..dc82b0bb mode 100644,000000..100644 --- a/docs/content/commands/hugo_config.md +++ b/docs/content/commands/hugo_config.md @@@ -1,41 -1,0 +1,41 @@@ +--- - date: 2017-11-18T10:28:35+01:00 ++date: 2017-12-28T18:49:29+01:00 +title: "hugo config" +slug: hugo_config +url: /commands/hugo_config/ +--- +## hugo config + +Print the site configuration + +### Synopsis + + +Print the site configuration, both default and custom settings. + +``` +hugo config [flags] +``` + +### Options + +``` + -h, --help help for config +``` + +### 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](/commands/hugo/) - hugo builds your site + - ###### Auto generated by spf13/cobra on 18-Nov-2017 ++###### Auto generated by spf13/cobra on 28-Dec-2017 diff --cc docs/content/commands/hugo_convert.md index 825350ce,00000000..d648ac34 mode 100644,000000..100644 --- a/docs/content/commands/hugo_convert.md +++ b/docs/content/commands/hugo_convert.md @@@ -1,45 -1,0 +1,45 @@@ +--- - date: 2017-11-18T10:28:35+01:00 ++date: 2017-12-28T18:49:29+01:00 +title: "hugo convert" +slug: hugo_convert +url: /commands/hugo_convert/ +--- +## hugo convert + +Convert your content to different formats + +### Synopsis + + +Convert your content (e.g. front matter) to different formats. + +See convert's subcommands toJSON, toTOML and toYAML for more information. + +### Options + +``` + -h, --help help for convert + -o, --output string filesystem path to write files to + -s, --source string filesystem path to read files relative from + --unsafe enable less safe operations, please backup first +``` + +### 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](/commands/hugo/) - hugo builds your site +* [hugo convert toJSON](/commands/hugo_convert_tojson/) - Convert front matter to JSON +* [hugo convert toTOML](/commands/hugo_convert_totoml/) - Convert front matter to TOML +* [hugo convert toYAML](/commands/hugo_convert_toyaml/) - Convert front matter to YAML + - ###### Auto generated by spf13/cobra on 18-Nov-2017 ++###### Auto generated by spf13/cobra on 28-Dec-2017 diff --cc docs/content/commands/hugo_convert_toJSON.md index 42000aa4,00000000..1d2ccb27 mode 100644,000000..100644 --- a/docs/content/commands/hugo_convert_toJSON.md +++ b/docs/content/commands/hugo_convert_toJSON.md @@@ -1,45 -1,0 +1,45 @@@ +--- - date: 2017-11-18T10:28:35+01:00 ++date: 2017-12-28T18:49:29+01:00 +title: "hugo convert toJSON" +slug: hugo_convert_toJSON +url: /commands/hugo_convert_tojson/ +--- +## hugo convert toJSON + +Convert front matter to JSON + +### Synopsis + + +toJSON converts all front matter in the content directory +to use JSON for the front matter. + +``` +hugo convert toJSON [flags] +``` + +### Options + +``` + -h, --help help for toJSON +``` + +### 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) + -o, --output string filesystem path to write files to + --quiet build in quiet mode + -s, --source string filesystem path to read files relative from + --unsafe enable less safe operations, please backup first + -v, --verbose verbose output + --verboseLog verbose logging +``` + +### SEE ALSO +* [hugo convert](/commands/hugo_convert/) - Convert your content to different formats + - ###### Auto generated by spf13/cobra on 18-Nov-2017 ++###### Auto generated by spf13/cobra on 28-Dec-2017 diff --cc docs/content/commands/hugo_convert_toTOML.md index 9d1e30bc,00000000..098f6132 mode 100644,000000..100644 --- a/docs/content/commands/hugo_convert_toTOML.md +++ b/docs/content/commands/hugo_convert_toTOML.md @@@ -1,45 -1,0 +1,45 @@@ +--- - date: 2017-11-18T10:28:35+01:00 ++date: 2017-12-28T18:49:29+01:00 +title: "hugo convert toTOML" +slug: hugo_convert_toTOML +url: /commands/hugo_convert_totoml/ +--- +## hugo convert toTOML + +Convert front matter to TOML + +### Synopsis + + +toTOML converts all front matter in the content directory +to use TOML for the front matter. + +``` +hugo convert toTOML [flags] +``` + +### Options + +``` + -h, --help help for toTOML +``` + +### 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) + -o, --output string filesystem path to write files to + --quiet build in quiet mode + -s, --source string filesystem path to read files relative from + --unsafe enable less safe operations, please backup first + -v, --verbose verbose output + --verboseLog verbose logging +``` + +### SEE ALSO +* [hugo convert](/commands/hugo_convert/) - Convert your content to different formats + - ###### Auto generated by spf13/cobra on 18-Nov-2017 ++###### Auto generated by spf13/cobra on 28-Dec-2017 diff --cc docs/content/commands/hugo_convert_toYAML.md index cb6dac3e,00000000..f9e0e686 mode 100644,000000..100644 --- a/docs/content/commands/hugo_convert_toYAML.md +++ b/docs/content/commands/hugo_convert_toYAML.md @@@ -1,45 -1,0 +1,45 @@@ +--- - date: 2017-11-18T10:28:35+01:00 ++date: 2017-12-28T18:49:29+01:00 +title: "hugo convert toYAML" +slug: hugo_convert_toYAML +url: /commands/hugo_convert_toyaml/ +--- +## hugo convert toYAML + +Convert front matter to YAML + +### Synopsis + + +toYAML converts all front matter in the content directory +to use YAML for the front matter. + +``` +hugo convert toYAML [flags] +``` + +### Options + +``` + -h, --help help for toYAML +``` + +### 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) + -o, --output string filesystem path to write files to + --quiet build in quiet mode + -s, --source string filesystem path to read files relative from + --unsafe enable less safe operations, please backup first + -v, --verbose verbose output + --verboseLog verbose logging +``` + +### SEE ALSO +* [hugo convert](/commands/hugo_convert/) - Convert your content to different formats + - ###### Auto generated by spf13/cobra on 18-Nov-2017 ++###### Auto generated by spf13/cobra on 28-Dec-2017 diff --cc docs/content/commands/hugo_env.md index 38d72686,00000000..90ecf1dc mode 100644,000000..100644 --- a/docs/content/commands/hugo_env.md +++ b/docs/content/commands/hugo_env.md @@@ -1,41 -1,0 +1,41 @@@ +--- - date: 2017-11-18T10:28:35+01:00 ++date: 2017-12-28T18:49:29+01:00 +title: "hugo env" +slug: hugo_env +url: /commands/hugo_env/ +--- +## hugo env + +Print Hugo version and environment info + +### Synopsis + + +Print Hugo version and environment info. This is useful in Hugo bug reports. + +``` +hugo env [flags] +``` + +### Options + +``` + -h, --help help for env +``` + +### 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](/commands/hugo/) - hugo builds your site + - ###### Auto generated by spf13/cobra on 18-Nov-2017 ++###### Auto generated by spf13/cobra on 28-Dec-2017 diff --cc docs/content/commands/hugo_gen.md index 3aafee1e,00000000..fc12e368 mode 100644,000000..100644 --- a/docs/content/commands/hugo_gen.md +++ b/docs/content/commands/hugo_gen.md @@@ -1,41 -1,0 +1,41 @@@ +--- - date: 2017-11-18T10:28:35+01:00 ++date: 2017-12-28T18:49:29+01:00 +title: "hugo gen" +slug: hugo_gen +url: /commands/hugo_gen/ +--- +## hugo gen + +A collection of several useful generators. + +### Synopsis + + +A collection of several useful generators. + +### Options + +``` + -h, --help help for gen +``` + +### 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](/commands/hugo/) - hugo builds your site +* [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 man](/commands/hugo_gen_man/) - Generate man pages for the Hugo CLI + - ###### Auto generated by spf13/cobra on 18-Nov-2017 ++###### Auto generated by spf13/cobra on 28-Dec-2017 diff --cc docs/content/commands/hugo_gen_autocomplete.md index 024d6342,00000000..800c2480 mode 100644,000000..100644 --- a/docs/content/commands/hugo_gen_autocomplete.md +++ b/docs/content/commands/hugo_gen_autocomplete.md @@@ -1,59 -1,0 +1,59 @@@ +--- - date: 2017-11-18T10:28:35+01:00 ++date: 2017-12-28T18:49:29+01:00 +title: "hugo gen autocomplete" +slug: hugo_gen_autocomplete +url: /commands/hugo_gen_autocomplete/ +--- +## hugo gen autocomplete + +Generate shell autocompletion script for Hugo + +### Synopsis + + +Generates a shell autocompletion script for Hugo. + +NOTE: The current version supports Bash only. + This should work for *nix systems with Bash installed. + +By default, the file is written directly to /etc/bash_completion.d +for convenience, and the command may need superuser rights, e.g.: + + $ sudo hugo gen autocomplete + +Add `--completionfile=/path/to/file` flag to set alternative +file-path and name. + +Logout and in again to reload the completion scripts, +or just source them in directly: + + $ . /etc/bash_completion + +``` +hugo gen autocomplete [flags] +``` + +### Options + +``` + --completionfile string autocompletion file (default "/etc/bash_completion.d/hugo.sh") + -h, --help help for autocomplete + --type string autocompletion type (currently only bash supported) (default "bash") +``` + +### 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 18-Nov-2017 ++###### Auto generated by spf13/cobra on 28-Dec-2017 diff --cc docs/content/commands/hugo_gen_chromastyles.md index d042910e,00000000..dd81610c mode 100644,000000..100644 --- a/docs/content/commands/hugo_gen_chromastyles.md +++ b/docs/content/commands/hugo_gen_chromastyles.md @@@ -1,46 -1,0 +1,46 @@@ +--- - date: 2017-11-18T10:28:35+01:00 ++date: 2017-12-28T18:49:29+01: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 18-Nov-2017 ++###### Auto generated by spf13/cobra on 28-Dec-2017 diff --cc docs/content/commands/hugo_gen_doc.md index 7513b515,00000000..908e98ec mode 100644,000000..100644 --- a/docs/content/commands/hugo_gen_doc.md +++ b/docs/content/commands/hugo_gen_doc.md @@@ -1,48 -1,0 +1,48 @@@ +--- - date: 2017-11-18T10:28:35+01:00 ++date: 2017-12-28T18:49:29+01:00 +title: "hugo gen doc" +slug: hugo_gen_doc +url: /commands/hugo_gen_doc/ +--- +## hugo gen doc + +Generate Markdown documentation for the Hugo CLI. + +### Synopsis + + +Generate Markdown documentation for the Hugo CLI. + +This command is, mostly, used to create up-to-date documentation +of Hugo's command-line interface for http://gohugo.io/. + +It creates one Markdown file per command with front matter suitable +for rendering in Hugo. + +``` +hugo gen doc [flags] +``` + +### Options + +``` + --dir string the directory to write the doc. (default "/tmp/hugodoc/") + -h, --help help for doc +``` + +### 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 18-Nov-2017 ++###### Auto generated by spf13/cobra on 28-Dec-2017 diff --cc docs/content/commands/hugo_gen_man.md index e420fec7,00000000..c7b0cf22 mode 100644,000000..100644 --- a/docs/content/commands/hugo_gen_man.md +++ b/docs/content/commands/hugo_gen_man.md @@@ -1,44 -1,0 +1,44 @@@ +--- - date: 2017-11-18T10:28:35+01:00 ++date: 2017-12-28T18:49:29+01:00 +title: "hugo gen man" +slug: hugo_gen_man +url: /commands/hugo_gen_man/ +--- +## hugo gen man + +Generate man pages for the Hugo CLI + +### Synopsis + + +This command automatically generates up-to-date man pages of Hugo's +command-line interface. By default, it creates the man page files +in the "man" directory under the current directory. + +``` +hugo gen man [flags] +``` + +### Options + +``` + --dir string the directory to write the man pages. (default "man/") + -h, --help help for man +``` + +### 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 18-Nov-2017 ++###### Auto generated by spf13/cobra on 28-Dec-2017 diff --cc docs/content/commands/hugo_import.md index 04c0cb9b,00000000..80e22764 mode 100644,000000..100644 --- a/docs/content/commands/hugo_import.md +++ b/docs/content/commands/hugo_import.md @@@ -1,40 -1,0 +1,40 @@@ +--- - date: 2017-11-18T10:28:35+01:00 ++date: 2017-12-28T18:49:29+01:00 +title: "hugo import" +slug: hugo_import +url: /commands/hugo_import/ +--- +## hugo import + +Import your site from others. + +### Synopsis + + +Import your site from other web site generators like Jekyll. + +Import requires a subcommand, e.g. `hugo import jekyll jekyll_root_path target_path`. + +### Options + +``` + -h, --help help for import +``` + +### 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](/commands/hugo/) - hugo builds your site +* [hugo import jekyll](/commands/hugo_import_jekyll/) - hugo import from Jekyll + - ###### Auto generated by spf13/cobra on 18-Nov-2017 ++###### Auto generated by spf13/cobra on 28-Dec-2017 diff --cc docs/content/commands/hugo_import_jekyll.md index f4669843,00000000..d1583ec7 mode 100644,000000..100644 --- a/docs/content/commands/hugo_import_jekyll.md +++ b/docs/content/commands/hugo_import_jekyll.md @@@ -1,44 -1,0 +1,44 @@@ +--- - date: 2017-11-18T10:28:35+01:00 ++date: 2017-12-28T18:49:29+01:00 +title: "hugo import jekyll" +slug: hugo_import_jekyll +url: /commands/hugo_import_jekyll/ +--- +## hugo import jekyll + +hugo import from Jekyll + +### Synopsis + + +hugo import from Jekyll. + +Import from Jekyll requires two paths, e.g. `hugo import jekyll jekyll_root_path target_path`. + +``` +hugo import jekyll [flags] +``` + +### Options + +``` + --force allow import into non-empty target directory + -h, --help help for jekyll +``` + +### 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 import](/commands/hugo_import/) - Import your site from others. + - ###### Auto generated by spf13/cobra on 18-Nov-2017 ++###### Auto generated by spf13/cobra on 28-Dec-2017 diff --cc docs/content/commands/hugo_list.md index df8e8cb8,00000000..7a2665a4 mode 100644,000000..100644 --- a/docs/content/commands/hugo_list.md +++ b/docs/content/commands/hugo_list.md @@@ -1,43 -1,0 +1,43 @@@ +--- - date: 2017-11-18T10:28:35+01:00 ++date: 2017-12-28T18:49:29+01:00 +title: "hugo list" +slug: hugo_list +url: /commands/hugo_list/ +--- +## hugo list + +Listing out various types of content + +### Synopsis + + +Listing out various types of content. + +List requires a subcommand, e.g. `hugo list drafts`. + +### Options + +``` + -h, --help help for list + -s, --source string filesystem path to read files relative from +``` + +### 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](/commands/hugo/) - hugo builds your site +* [hugo list drafts](/commands/hugo_list_drafts/) - List all drafts +* [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 + - ###### Auto generated by spf13/cobra on 18-Nov-2017 ++###### Auto generated by spf13/cobra on 28-Dec-2017 diff --cc docs/content/commands/hugo_list_drafts.md index 893d7105,00000000..f842cb22 mode 100644,000000..100644 --- a/docs/content/commands/hugo_list_drafts.md +++ b/docs/content/commands/hugo_list_drafts.md @@@ -1,42 -1,0 +1,42 @@@ +--- - date: 2017-11-18T10:28:35+01:00 ++date: 2017-12-28T18:49:29+01:00 +title: "hugo list drafts" +slug: hugo_list_drafts +url: /commands/hugo_list_drafts/ +--- +## hugo list drafts + +List all drafts + +### Synopsis + + +List all of the drafts in your content directory. + +``` +hugo list drafts [flags] +``` + +### Options + +``` + -h, --help help for drafts +``` + +### 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 + -s, --source string filesystem path to read files relative from + -v, --verbose verbose output + --verboseLog verbose logging +``` + +### SEE ALSO +* [hugo list](/commands/hugo_list/) - Listing out various types of content + - ###### Auto generated by spf13/cobra on 18-Nov-2017 ++###### Auto generated by spf13/cobra on 28-Dec-2017 diff --cc docs/content/commands/hugo_list_expired.md index 84699005,00000000..bbf08359 mode 100644,000000..100644 --- a/docs/content/commands/hugo_list_expired.md +++ b/docs/content/commands/hugo_list_expired.md @@@ -1,43 -1,0 +1,43 @@@ +--- - date: 2017-11-18T10:28:35+01:00 ++date: 2017-12-28T18:49:29+01:00 +title: "hugo list expired" +slug: hugo_list_expired +url: /commands/hugo_list_expired/ +--- +## hugo list expired + +List all posts already expired + +### Synopsis + + +List all of the posts in your content directory which has already +expired. + +``` +hugo list expired [flags] +``` + +### Options + +``` + -h, --help help for expired +``` + +### 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 + -s, --source string filesystem path to read files relative from + -v, --verbose verbose output + --verboseLog verbose logging +``` + +### SEE ALSO +* [hugo list](/commands/hugo_list/) - Listing out various types of content + - ###### Auto generated by spf13/cobra on 18-Nov-2017 ++###### Auto generated by spf13/cobra on 28-Dec-2017 diff --cc docs/content/commands/hugo_list_future.md index 38755892,00000000..d0c96d0c mode 100644,000000..100644 --- a/docs/content/commands/hugo_list_future.md +++ b/docs/content/commands/hugo_list_future.md @@@ -1,43 -1,0 +1,43 @@@ +--- - date: 2017-11-18T10:28:35+01:00 ++date: 2017-12-28T18:49:29+01:00 +title: "hugo list future" +slug: hugo_list_future +url: /commands/hugo_list_future/ +--- +## hugo list future + +List all posts dated in the future + +### Synopsis + + +List all of the posts in your content directory which will be +posted in the future. + +``` +hugo list future [flags] +``` + +### Options + +``` + -h, --help help for future +``` + +### 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 + -s, --source string filesystem path to read files relative from + -v, --verbose verbose output + --verboseLog verbose logging +``` + +### SEE ALSO +* [hugo list](/commands/hugo_list/) - Listing out various types of content + - ###### Auto generated by spf13/cobra on 18-Nov-2017 ++###### Auto generated by spf13/cobra on 28-Dec-2017 diff --cc docs/content/commands/hugo_new.md index eaa9c3fd,00000000..19eca79c mode 100644,000000..100644 --- a/docs/content/commands/hugo_new.md +++ b/docs/content/commands/hugo_new.md @@@ -1,51 -1,0 +1,51 @@@ +--- - date: 2017-11-18T10:28:35+01:00 ++date: 2017-12-28T18:49:29+01:00 +title: "hugo new" +slug: hugo_new +url: /commands/hugo_new/ +--- +## hugo new + +Create new content for your site + +### Synopsis + + +Create a new content file and automatically set the date and title. +It will guess which kind of file to create based on the path provided. + +You can also specify the kind with `-k KIND`. + +If archetypes are provided in your theme or site, they will be used. + +``` +hugo new [path] [flags] +``` + +### Options + +``` + --editor string edit new content with this editor, if provided + -h, --help help for new + -k, --kind string content type to create + -s, --source string filesystem path to read files relative from +``` + +### 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](/commands/hugo/) - hugo builds your site +* [hugo new site](/commands/hugo_new_site/) - Create a new site (skeleton) +* [hugo new theme](/commands/hugo_new_theme/) - Create a new theme + - ###### Auto generated by spf13/cobra on 18-Nov-2017 ++###### Auto generated by spf13/cobra on 28-Dec-2017 diff --cc docs/content/commands/hugo_new_site.md index f4b5c2a9,00000000..7ac1146e mode 100644,000000..100644 --- a/docs/content/commands/hugo_new_site.md +++ b/docs/content/commands/hugo_new_site.md @@@ -1,46 -1,0 +1,46 @@@ +--- - date: 2017-11-18T10:28:35+01:00 ++date: 2017-12-28T18:49:29+01:00 +title: "hugo new site" +slug: hugo_new_site +url: /commands/hugo_new_site/ +--- +## hugo new site + +Create a new site (skeleton) + +### Synopsis + + +Create a new site in the provided directory. +The new site will have the correct structure, but no content or theme yet. +Use `hugo new [contentPath]` to create new content. + +``` +hugo new site [path] [flags] +``` + +### Options + +``` + --force init inside non-empty directory + -f, --format string config & frontmatter format (default "toml") + -h, --help help for site +``` + +### 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 + -s, --source string filesystem path to read files relative from + -v, --verbose verbose output + --verboseLog verbose logging +``` + +### SEE ALSO +* [hugo new](/commands/hugo_new/) - Create new content for your site + - ###### Auto generated by spf13/cobra on 18-Nov-2017 ++###### Auto generated by spf13/cobra on 28-Dec-2017 diff --cc docs/content/commands/hugo_new_theme.md index 3f3989cd,00000000..8aac5651 mode 100644,000000..100644 --- a/docs/content/commands/hugo_new_theme.md +++ b/docs/content/commands/hugo_new_theme.md @@@ -1,45 -1,0 +1,45 @@@ +--- - date: 2017-11-18T10:28:35+01:00 ++date: 2017-12-28T18:49:29+01:00 +title: "hugo new theme" +slug: hugo_new_theme +url: /commands/hugo_new_theme/ +--- +## hugo new theme + +Create a new theme + +### Synopsis + + +Create a new theme (skeleton) called [name] in the current directory. +New theme is a skeleton. Please add content to the touched files. Add your +name to the copyright line in the license and adjust the theme.toml file +as you see fit. + +``` +hugo new theme [name] [flags] +``` + +### Options + +``` + -h, --help help for theme +``` + +### 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 + -s, --source string filesystem path to read files relative from + -v, --verbose verbose output + --verboseLog verbose logging +``` + +### SEE ALSO +* [hugo new](/commands/hugo_new/) - Create new content for your site + - ###### Auto generated by spf13/cobra on 18-Nov-2017 ++###### Auto generated by spf13/cobra on 28-Dec-2017 diff --cc docs/content/commands/hugo_server.md index 1581ef54,00000000..1157e646 mode 100644,000000..100644 --- a/docs/content/commands/hugo_server.md +++ b/docs/content/commands/hugo_server.md @@@ -1,93 -1,0 +1,94 @@@ +--- - date: 2017-11-18T10:28:35+01:00 ++date: 2017-12-28T18:49:29+01:00 +title: "hugo server" +slug: hugo_server +url: /commands/hugo_server/ +--- +## hugo server + +A high performance webserver + +### Synopsis + + +Hugo provides its own webserver which builds and serves the site. +While hugo server is high performance, it is a webserver with limited options. +Many run it in production, but the standard behavior is for people to use it +in development and use a more full featured server such as Nginx or Caddy. + +'hugo server' will avoid writing the rendered and served content to disk, +preferring to store it in memory. + +By default hugo will also watch your files for any changes you make and +automatically rebuild the site. It will then live reload any open browser pages +and push the latest content to them. As most Hugo sites are built in a fraction +of a second, you will be able to save and see your changes nearly instantly. + +``` +hugo server [flags] +``` + +### Options + +``` + --appendPort append port to baseURL (default true) + -b, --baseURL string hostname (and path) to the root, e.g. http://spf13.com/ + --bind string interface to which the server will bind (default "127.0.0.1") + -D, --buildDrafts include content marked as draft + -E, --buildExpired include expired content + -F, --buildFuture include content with publishdate in the future + --cacheDir string filesystem path to cache directory. Defaults: $TMPDIR/hugo_cache/ + --canonifyURLs if true, all relative URLs will be canonicalized using baseURL + --cleanDestinationDir remove files from destination not found in static directories + -c, --contentDir string filesystem path to content directory + -d, --destination string filesystem path to write files to + --disable404 do not render 404 page + --disableFastRender enables full re-renders on changes + --disableKinds stringSlice disable different kind of pages (home, RSS etc.) + --disableLiveReload watch without enabling live browser reload on rebuild + --disableRSS do not build RSS files + --disableSitemap do not build Sitemap file + --enableGitInfo add Git revision, date and author info to the pages + --forceSyncStatic copy all files when static is changed. ++ --gc enable to run some cleanup tasks (remove unused cache files) after the build + -h, --help help for server + --i18n-warnings print missing translations + --ignoreCache ignores the cache 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") + --memstats string log memory usage to this file + --navigateToChanged navigate to changed content file on live browser reload + --noChmod don't sync permission mode of files + --noHTTPCache prevent HTTP caching + --noTimes don't sync modification time of files + --pluralizeListTitles pluralize titles in lists using inflect (default true) + -p, --port int port on which the server will listen (default 1313) + --preserveTaxonomyNames preserve taxonomy names as written ("Gérard Depardieu" vs "gerard-depardieu") + --renderToDisk render to Destination path (default is render to memory & serve from there) + -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 + --templateMetricsHints calculate some improvement hints when combined with --templateMetrics + -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/ + -w, --watch watch filesystem for changes and recreate as needed (default true) +``` + +### 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](/commands/hugo/) - hugo builds your site + - ###### Auto generated by spf13/cobra on 18-Nov-2017 ++###### Auto generated by spf13/cobra on 28-Dec-2017 diff --cc docs/content/commands/hugo_undraft.md index e8b67071,00000000..102ec454 mode 100644,000000..100644 --- a/docs/content/commands/hugo_undraft.md +++ b/docs/content/commands/hugo_undraft.md @@@ -1,43 -1,0 +1,43 @@@ +--- - date: 2017-11-18T10:28:35+01:00 ++date: 2017-12-28T18:49:29+01:00 +title: "hugo undraft" +slug: hugo_undraft +url: /commands/hugo_undraft/ +--- +## hugo undraft + +Undraft resets the content's draft status + +### Synopsis + + +Undraft resets the content's draft status +and updates the date to the current date and time. +If the content's draft status is 'False', nothing is done. + +``` +hugo undraft path/to/content [flags] +``` + +### Options + +``` + -h, --help help for undraft +``` + +### 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](/commands/hugo/) - hugo builds your site + - ###### Auto generated by spf13/cobra on 18-Nov-2017 ++###### Auto generated by spf13/cobra on 28-Dec-2017 diff --cc docs/content/commands/hugo_version.md index 850be51a,00000000..c4b07d25 mode 100644,000000..100644 --- a/docs/content/commands/hugo_version.md +++ b/docs/content/commands/hugo_version.md @@@ -1,41 -1,0 +1,41 @@@ +--- - date: 2017-11-18T10:28:35+01:00 ++date: 2017-12-28T18:49:29+01:00 +title: "hugo version" +slug: hugo_version +url: /commands/hugo_version/ +--- +## hugo version + +Print the version number of Hugo + +### Synopsis + + +All software has versions. This is Hugo's. + +``` +hugo version [flags] +``` + +### Options + +``` + -h, --help help for version +``` + +### 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](/commands/hugo/) - hugo builds your site + - ###### Auto generated by spf13/cobra on 18-Nov-2017 ++###### Auto generated by spf13/cobra on 28-Dec-2017 diff --cc docs/content/content-management/multilingual.md index 4a646741,00000000..189207ca mode 100644,000000..100644 --- a/docs/content/content-management/multilingual.md +++ b/docs/content/content-management/multilingual.md @@@ -1,353 -1,0 +1,366 @@@ +--- +title: Multilingual Mode +linktitle: Multilingual and i18n +description: Hugo supports the creation of websites with multiple languages side by side. +date: 2017-01-10 +publishdate: 2017-01-10 +lastmod: 2017-01-10 +categories: [content management] +keywords: [multilingual,i18n, internationalization] +menu: + docs: + parent: "content-management" + weight: 150 +weight: 150 #rem +draft: false +aliases: [/content/multilingual/,/content-management/multilingual/] +toc: true +--- + +You should define the available languages in a `Languages` section in your site configuration. + +## Configure Languages + +The following is an example of a TOML site configuration for a multilingual Hugo project: + +{{< code file="config.toml" download="config.toml" >}} +DefaultContentLanguage = "en" +copyright = "Everything is mine" + +[params.navigation] +help = "Help" + +[Languages] +[Languages.en] +title = "My blog" +weight = 1 +[Languages.en.params] +linkedin = "english-link" + +[Languages.fr] +copyright = "Tout est à moi" +title = "Mon blog" +weight = 2 +[Languages.fr.params] +linkedin = "lien-francais" +[Languages.fr.navigation] +help = "Aide" +{{< /code >}} + +Anything not defined in a `[Languages]` block will fall back to the global +value for that key (e.g., `copyright` for the English [`en`] language). + +With the configuration above, all content, sitemap, RSS feeds, paginations, +and taxonomy pages will be rendered below `/` in English (your default content language) and then below `/fr` in French. + +When working with front matter `Params` in [single page templates][singles], omit the `params` in the key for the translation. + +If you want all of the languages to be put below their respective language code, enable `defaultContentLanguageInSubdir: true`. + +Only the obvious non-global options can be overridden per language. Examples of global options are `baseURL`, `buildDrafts`, etc. + +## Configure Multilingual Multihost + +From **Hugo 0.31** we support multiple languages in a multihost configuration. See [this issue](https://github.com/gohugoio/hugo/issues/4027) for details. + - This means that you can now confugre a `baseURL` per `language`: ++This means that you can now configure a `baseURL` per `language`: + + +> If a `baseURL` is set on the `language` level, then all languages must have one and they must all be different. + +Example: + +```bash +[languages] +[languages.no] +baseURL = "https://example.no" +languageName = "Norsk" +weight = 1 +title = "På norsk" + +[languages.en] +baseURL = "https://example.com" +languageName = "English" +weight = 2 +title = "In English" +``` + +With the above, the two sites will be generated into `public` with their own root: + +```bash +public +├── en +└── no +``` + +**All URLs (i.e `.Permalink` etc.) will be generated from that root. So the English home page above will have its `.Permalink` set to `https://example.com/`.** + +When you run `hugo server` we will start multiple HTTP servers. You will typlically see something like this in the console: + +```bash +Web Server is available at 127.0.0.1:1313 (bind address 127.0.0.1) +Web Server is available at 127.0.0.1:1314 (bind address 127.0.0.1) +Press Ctrl+C to stop +``` + +Live reload and `--navigateToChanged` between the servers work as expected. + +## Taxonomies and Blackfriday + +Taxonomies and [Blackfriday configuration][config] can also be set per language: + + +{{< code file="bf-config.toml" >}} +[Taxonomies] +tag = "tags" + +[blackfriday] +angledQuotes = true +hrefTargetBlank = true + +[Languages] +[Languages.en] +weight = 1 +title = "English" +[Languages.en.blackfriday] +angledQuotes = false + +[Languages.fr] +weight = 2 +title = "Français" +[Languages.fr.Taxonomies] +plaque = "plaques" +{{< /code >}} + +## Translate Your Content + +Translated articles are identified by the name of the content file. + +### Examples of Translated Articles + +1. `/content/about.en.md` +2. `/content/about.fr.md` + +In this example, the `about.md` will be assigned the configured `defaultContentLanguage`. + +1. `/content/about.md` +2. `/content/about.fr.md` + +This way, you can slowly start to translate your current content without having to rename everything. If left unspecified, the default value for `defaultContentLanguage` is `en`. + +By having the same **directory and base filename**, the content pieces are linked together as translated pieces. + +You can also set the key used to link the translations explicitly in front matter: + +```yaml +translationKey: "my-story" +``` + + +{{% note %}} +**Before Hugo 0.31**, the file's directory was not considered when looking for translations. This did not work when you named all of your content files, say, `index.md`. Now we use the full content path. +{{% /note %}} + +If you need distinct URLs per language, you can set the slug in the non-default language file. For example, you can define a custom slug for a French translation in the front matter of `content/about.fr.md` as follows: + +```yaml +slug: "a-propos" + +``` + +At render, Hugo will build both `/about/` and `/a-propos/` as properly linked translated pages. + + +## Link to Translated Content + +To create a list of links to translated content, use a template similar to the following: + +{{< code file="layouts/partials/i18nlist.html" >}} +{{ if .IsTranslated }} +

    {{ i18n "translations" }}

    + +{{ end }} +{{< /code >}} + +The above can be put in a `partial` (i.e., inside `layouts/partials/`) and included in any template, be it for a [single content page][contenttemplate] or the [homepage][]. It will not print anything if there are no translations for a given page, or if there are translations---in the case of the homepage, section listing, etc.---a site with only render one language. + +The above also uses the [`i18n` function][i18func] described in the next section. + ++## List All Available Languages ++ ++`.AllTranslations` on a `Page` can be used to list all translations, including itself. Called on the home page it can be used to build a language navigator: ++ ++ ++{{< code file="layouts/partials/allLanguages.html" >}} ++ ++{{< /code >}} ++ +## Translation of Strings + +Hugo uses [go-i18n][] to support string translations. [See the project's source repository][go-i18n-source] to find tools that will help you manage your translation workflows. + +Translations are collected from the `themes//i18n/` folder (built into the theme), as well as translations present in `i18n/` at the root of your project. In the `i18n`, the translations will be merged and take precedence over what is in the theme folder. Language files should be named according to [RFC 5646][] with names such as `en-US.toml`, `fr.toml`, etc. + +{{% note %}} +From **Hugo 0.31** you no longer need to use a valid language code. It _can be_ anything. + +See https://github.com/gohugoio/hugo/issues/3564 + +{{% /note %}} + +From within your templates, use the `i18n` function like this: + +``` +{{ i18n "home" }} +``` + +This uses a definition like this one in `i18n/en-US.toml`: + +``` +[home] +other = "Home" +``` + +Often you will want to use to the page variables in the translations strings. To do that, pass on the "." context when calling `i18n`: + +``` +{{ i18n "wordCount" . }} +``` + +This uses a definition like this one in `i18n/en-US.toml`: + +``` +[wordCount] +other = "This article has {{ .WordCount }} words." +``` +An example of singular and plural form: + +``` +[readingTime] +one = "One minute read" +other = "{{.Count}} minutes read" +``` +And then in the template: + +``` +{{ i18n "readingTime" .ReadingTime }} +``` +To track down missing translation strings, run Hugo with the `--i18n-warnings` flag: + +``` + hugo --i18n-warnings | grep i18n +i18n|MISSING_TRANSLATION|en|wordCount +``` + +## Customize Dates + +At the time of this writing, Golang does not yet have support for internationalized locales, but if you do some work, you can simulate it. For example, if you want to use French month names, you can add a data file like ``data/mois.yaml`` with this content: + +~~~yaml +1: "janvier" +2: "février" +3: "mars" +4: "avril" +5: "mai" +6: "juin" +7: "juillet" +8: "août" +9: "septembre" +10: "octobre" +11: "novembre" +12: "décembre" +~~~ + +... then index the non-English date names in your templates like so: + +~~~html + +~~~ + +This technique extracts the day, month and year by specifying ``.Date.Day``, ``.Date.Month``, and ``.Date.Year``, and uses the month number as a key, when indexing the month name data file. + +## Menus + +You can define your menus for each language independently. The [creation of a menu][menus] works analogous to earlier versions of Hugo, except that they have to be defined in their language-specific block in the configuration file: + +``` +defaultContentLanguage = "en" + +[languages.en] +weight = 0 +languageName = "English" + +[[languages.en.menu.main]] +url = "/" +name = "Home" +weight = 0 + + +[languages.de] +weight = 10 +languageName = "Deutsch" + +[[languages.de.menu.main]] +url = "/" +name = "Startseite" +weight = 0 +``` + +The rendering of the main navigation works as usual. `.Site.Menus` will just contain the menu of the current language. Pay attention to the generation of the menu links. `absLangURL` takes care that you link to the correct locale of your website. Otherwise, both menu entries would link to the English version as the default content language that resides in the root directory. + +``` +
      + {{- $currentPage := . -}} + {{ range .Site.Menus.main -}} +
    • + {{ .Name }} +
      • + {{- end }} +
    + +``` + +## Missing translations + +If a string does not have a translation for the current language, Hugo will use the value from the default language. If no default value is set, an empty string will be shown. + +While translating a Hugo website, it can be handy to have a visual indicator of missing translations. The [`enableMissingTranslationPlaceholders` configuration option][config] will flag all untranslated strings with the placeholder `[i18n] identifier`, where `identifier` is the id of the missing translation. + +{{% note %}} +Hugo will generate your website with these missing translation placeholders. It might not be suited for production environments. +{{% /note %}} + +## Multilingual Themes support + +To support Multilingual mode in your themes, some considerations must be taken for the URLs in the templates. If there is more than one language, URLs must meet the following criteria: + +* Come from the built-in `.Permalink` or `.URL` +* Be constructed with + * The [`relLangURL` template function][rellangurl] or the [`absLangURL` template function][abslangurl] **OR** + * Prefixed with `{{ .LanguagePrefix }}` + +If there is more than one language defined, the `LanguagePrefix` variable will equal `/en` (or whatever your `CurrentLanguage` is). If not enabled, it will be an empty string and is therefore harmless for single-language Hugo websites. + +[abslangurl]: /functions/abslangurl +[config]: /getting-started/configuration/ +[contenttemplate]: /templates/single-page-templates/ +[go-i18n-source]: https://github.com/nicksnyder/go-i18n +[go-i18n]: https://github.com/nicksnyder/go-i18n +[homepage]: /templates/homepage/ +[i18func]: /functions/i18n/ +[menus]: /content-management/menus/ +[rellangurl]: /functions/rellangurl +[RFC 5646]: https://tools.ietf.org/html/rfc5646 +[singles]: /templates/single-page-templates/ diff --cc docs/content/content-management/organization.md index eb884ee4,00000000..a239c562 mode 100644,000000..100644 --- a/docs/content/content-management/organization.md +++ b/docs/content/content-management/organization.md @@@ -1,243 -1,0 +1,225 @@@ +--- +title: Content Organization +linktitle: Organization +description: Hugo assumes that the same structure that works to organize your source content is used to organize the rendered site. +date: 2017-02-01 +publishdate: 2017-02-01 +lastmod: 2017-02-01 +categories: [content management,fundamentals] +keywords: [sections,content,organization] +menu: + docs: + parent: "content-management" + weight: 10 +weight: 10 #rem +draft: false +aliases: [/content/sections/] +toc: true +--- + - {{% note %}} - This section is not updated with the new nested sections support in Hugo 0.24, see https://github.com/gohugoio/hugoDocs/issues/36 - {{% /note %}} - {{% todo %}} - See above - {{% /todo %}} - +{{< youtube 0GZxidrlaRM >}} + +## Organization of Content Source + +In Hugo, your content should be organized in a manner that reflects the rendered website. + - While Hugo supports content nested at any level, the top levels (i.e. `content/`) are special in Hugo and are considered the content [sections][]. Without any additional configuration, the following will just work: ++While Hugo supports content nested at any level, the top levels (i.e. `content/`) are special in Hugo and are considered the content type used to determine layouts etc. To read more about sections, including how to nest them, see [sections][]. ++ ++Without any additional configuration, the following will just work: + +``` +. +└── content + └── about + | └── _index.md // <- https://example.com/about/ + ├── post + | ├── firstpost.md // <- https://example.com/post/firstpost/ + | ├── happy + | | └── ness.md // <- https://example.com/post/happy/ness/ + | └── secondpost.md // <- https://example.com/post/secondpost/ + └── quote + ├── first.md // <- https://example.com/quote/first/ + └── second.md // <- https://example.com/quote/second/ +``` + +## Path Breakdown in Hugo + ++ +The following demonstrates the relationships between your content organization and the output URL structure for your Hugo website when it renders. These examples assume you are [using pretty URLs][pretty], which is the default behavior for Hugo. The examples also assume a key-value of `baseurl = "https://example.com"` in your [site's configuration file][config]. + +### Index Pages: `_index.md` + - `_index.md` has a special role in Hugo. It allows you to add front matter and content to your [list templates][lists] as of v0.18. These templates include those for [section templates][], [taxonomy templates][], [taxonomy terms templates][], and your [homepage template][]. In your templates, you can grab information from `_index.md` using the [`.Site.GetPage` function][getpage]. ++`_index.md` has a special role in Hugo. It allows you to add front matter and content to your [list templates][lists]. These templates include those for [section templates][], [taxonomy templates][], [taxonomy terms templates][], and your [homepage template][]. ++ ++{{% note %}} ++**Tip:** You can get a reference to the content and metadata in `_index.md` using the [`.Site.GetPage` function](/functions/getpage/). ++{{% /note %}} + +You can keep one `_index.md` for your homepage and one in each of your content sections, taxonomies, and taxonomy terms. The following shows typical placement of an `_index.md` that would contain content and front matter for a `posts` section list page on a Hugo website: + + +``` +. url +. ⊢--^-⊣ +. path slug +. ⊢--^-⊣⊢---^---⊣ +. filepath +. ⊢------^------⊣ +content/posts/_index.md +``` + +At build, this will output to the following destination with the associated values: + +``` + + url ("/posts/") + ⊢-^-⊣ + baseurl section ("posts") +⊢--------^---------⊣⊢-^-⊣ + permalink +⊢----------^-------------⊣ +https://example.com/posts/index.html +``` + ++The [sections][] can be nested as deeply as you need. The important part to understand is, that to make the section tree fully navigational, at least the lower-most section needs a content file. (i.e. `_index.md`). ++ ++ +### Single Pages in Sections + +Single content files in each of your sections are going to be rendered as [single page templates][singles]. Here is an example of a single `post` within `posts`: + + +``` + path ("posts/my-first-hugo-post.md") +. ⊢-----------^------------⊣ +. section slug +. ⊢-^-⊣⊢--------^----------⊣ +content/posts/my-first-hugo-post.md +``` + +At the time Hugo builds your site, the content will be output to the following destination: + +``` + + url ("/posts/my-first-hugo-post/") + ⊢------------^----------⊣ + baseurl section slug +⊢--------^--------⊣⊢-^--⊣⊢-------^---------⊣ + permalink +⊢--------------------^---------------------⊣ +https://example.com/posts/my-first-hugo-post/index.html +``` + - ### Section with Nested Directories - - To continue the example, the following demonstrates destination paths for a file located at `content/events/chicago/lollapalooza.md` in the same site: - - - ``` - section - ⊢--^--⊣ - url - ⊢-------------^------------⊣ - - baseURL path slug - ⊢--------^--------⊣ ⊢------^-----⊣⊢----^------⊣ - permalink - ⊢----------------------^-----------------------⊣ - https://example.com/events/chicago/lollapalooza/ - ``` - - {{% note %}} - As of v0.20, Hugo does not recognize nested sections. While you can nest as many content *directories* as you'd like, any child directory of a section will still be considered the same section as that of its parents. Therefore, in the above example, `{{.Section}}` for `lollapalooza.md` is `events` and *not* `chicago`. See the [related issue on GitHub](https://github.com/gohugoio/hugo/issues/465). - {{% /note %}} + +## Paths Explained + +The following concepts will provide more insight into the relationship between your project's organization and the default behaviors of Hugo when building the output website. + +### `section` + +A default content type is determined by a piece of content's section. `section` is determined by the location within the project's `content` directory. `section` *cannot* be specified or overridden in front matter. + +### `slug` + +A content's `slug` is either `name.extension` or `name/`. The value for `slug` is determined by + +* the name of the content file (e.g., `lollapalooza.md`) OR +* front matter overrides + +### `path` + +A content's `path` is determined by the section's path to the file. The file `path` + +* is based on the path to the content's location AND +* does not include the slug + +### `url` + +The `url` is the relative URL for the piece of content. The `url` + +* is based on the content's location within the directory structure OR +* is defined in front matter and *overrides all the above* + +## Override Destination Paths via Front Matter + +Hugo believes that you organize your content with a purpose. The same structure that works to organize your source content is used to organize the rendered site. As displayed above, the organization of the source content will be mirrored in the destination. + +There are times where you may need more control over your content. In these cases, there are fields that can be specified in the front matter to determine the destination of a specific piece of content. + +The following items are defined in this order for a specific reason: items explained further down in the list will override earlier items, and not all of these items can be defined in front matter: + +### `filename` + +This isn't in the front matter, but is the actual name of the file minus the extension. This will be the name of the file in the destination (e.g., `content/posts/my-post.md` becomes `example.com/posts/my-post/`). + +### `slug` + +When defined in the front matter, the `slug` can take the place of the filename for the destination. + +{{< code file="content/posts/old-post.md" >}} +--- +title: New Post +slug: "new-post" +--- +{{< /code >}} + +This will render to the following destination according to Hugo's default behavior: + +``` +example.com/posts/new-post/ +``` + +### `section` + +`section` is determined by a content's location on disk and *cannot* be specified in the front matter. See [sections][] for more information. + +### `type` + +A content's `type` is also determined by its location on disk but, unlike `section`, it *can* be specified in the front matter. See [types][]. This can come in especially handy when you want a piece of content to render using a different layout. In the following example, you can create a layout at `layouts/new/mylayout.html` that Hugo will use to render this piece of content, even in the midst of many other posts. + +{{< code file="content/posts/my-post.md" >}} +--- +title: My Post +type: new +layout: mylayout +--- +{{< /code >}} + + + + + +### `url` + +A complete URL can be provided. This will override all the above as it pertains to the end destination. This must be the path from the baseURL (starting with a `/`). `url` will be used exactly as it provided in the front matter and will ignore the `--uglyURLs` setting in your site configuration: + +{{< code file="content/posts/old-url.md" >}} +--- +title: Old URL +url: /blog/new-url/ +--- +{{< /code >}} + +Assuming your `baseURL` is [configured][config] to `https://example.com`, the addition of `url` to the front matter will make `old-url.md` render to the following destination: + +``` +https://example.com/blog/new-url/ +``` + +You can see more information on how to control output paths in [URL Management][urls]. + +[config]: /getting-started/configuration/ +[formats]: /content-management/formats/ +[front matter]: /content-management/front-matter/ +[getpage]: /functions/getpage/ +[homepage template]: /templates/homepage/ +[homepage]: /templates/homepage/ +[lists]: /templates/lists/ +[pretty]: /content-management/urls/#pretty-urls +[section templates]: /templates/section-templates/ +[sections]: /content-management/sections/ +[singles]: /templates/single-page-templates/ +[taxonomy templates]: /templates/taxonomy-templates/ +[taxonomy terms templates]: /templates/taxonomy-templates/ +[types]: /content-management/types/ +[urls]: /content-management/urls/ diff --cc docs/content/content-management/sections.md index 41137922,00000000..def5cac8 mode 100644,000000..100644 --- a/docs/content/content-management/sections.md +++ b/docs/content/content-management/sections.md @@@ -1,73 -1,0 +1,85 @@@ +--- +title: Content Sections +linktitle: Sections - description: Hugo supports content sections, which according to Hugo's default behavior, will reflect the structure of the rendered website. ++description: "Hugo generates a **section tree** that matches your content." +date: 2017-02-01 +publishdate: 2017-02-01 +lastmod: 2017-02-01 +categories: [content management] +keywords: [lists,sections,content types,organization] +menu: + docs: + parent: "content-management" + weight: 50 +weight: 50 #rem +draft: false +aliases: [/content/sections/] +toc: true +--- + ++ ++## Nested Sections ++ ++The sections can be nested as deeply as you need. ++ ++```bash ++blog ++├── funny-cats ++│   └── kittens ++│   └── _index.md ++└── tech ++ └── _index.md ++``` ++ ++ ++**The important part to understand is, that to make the section tree fully navigational, at least the lower-most section needs a content file. (e.g. `_index.md`).** ++ ++ +{{% note %}} - This section is not updated with the new nested sections support in Hugo 0.24, see https://github.com/gohugoio/hugoDocs/issues/36 ++When we talk about a **section** in correlation with template selection, it is currently always the root section only (`/blog/funny/mypost/ => blog`). ++ ++It is currently not possible to add a specific layout for one of the sub-sections. +{{% /note %}} - {{% todo %}} - See above - {{% /todo %}} + - Hugo believes that you organize your content with a purpose. The same structure that works to organize your source content is used to organize the rendered site (see [directory structure][]). + - Following this pattern, Hugo uses the top level of your content organization as the content **section**. ++## Example: Breadcrumb Navigation + - The following example shows a content directory structure for a website that has three sections: "authors," "events," and "posts": ++With the available [section variables and methods](#section-page-variables-and-methods) you can build powerful navigation. One common example would be a partial to show Breadcrumb navigation: + - ``` - . - └── content - ├── authors - | ├── _index.md // <- example.com/authors/ - | ├── john-doe.md // <- example.com/authors/john-doe/ - | └── jane-doe.md // <- example.com/authors/jane-doe/ - └── events - | ├── _index.md // <- example.com/events/ - | ├── event-1.md // <- example.com/events/event-1/ - | ├── event-2.md // <- example.com/events/event-2/ - | └── event-3.md // <- example.com/events/event-3/ - └── posts - | ├── _index.md // <- example.com/posts/ - | ├── post-1.md // <- example.com/posts/post-1/ - | ├── post-2.md // <- example.com/posts/post-2/ - | ├── post-3.md // <- example.com/posts/post-3/ - | ├── post-4.md // <- example.com/posts/post-4/ - | └── post-5.md // <- example.com/posts/post-5/ - ``` + - ## Content Section Lists ++{{< code file="layouts/partials/breadcrumb.html" download="breadcrumb.html" >}} ++
      ++ {{ template "breadcrumbnav" (dict "p1" . "p2" .) }} ++
    ++{{ define "breadcrumbnav" }} ++{{ if .p1.Parent }} ++{{ template "breadcrumbnav" (dict "p1" .p1.Parent "p2" .p2 ) }} ++{{ else if not .p1.IsHome }} ++{{ template "breadcrumbnav" (dict "p1" .p1.Site.Home "p2" .p2 ) }} ++{{ end }} ++ ++ {{ .p1.Title }} ++ ++{{ end }} ++{{< /code >}} + - Hugo will automatically create pages for each section root that list all of the content in that section. See the documentation on [section templates][] for details on customizing the way these pages are rendered. ++## Section Page Variables and Methods + - As of Hugo v0.18, section pages can also have a content file and front matter. These section content files must be placed in their corresponding section folder and named `_index.md` in order for Hugo to correctly render the front matter and content. ++Also see [Page Variables](/variables/page/). + - {{% warning "`index.md` vs `_index.md`" %}} - Hugo themes developed before v0.18 often used an `index.md`(i.e., without the leading underscore [`_`]) in a content section as a hack to emulate the behavior of `_index.md`. The hack may work...*sometimes*; however, the order of page rendering can be unpredictable in Hugo. What works now may fail to render appropriately as your site grows. It is **strongly advised** to use `_index.md` as content for your section index pages. **Note:** `_index.md`'s layout, as representative of a section, is a [list page template](/templates/section-templates/) and *not* a [single page template](/templates/single-page-templates/). If you want to alter the new default behavior for `_index.md`, configure `disableKinds` accordingly in your [site's configuration](/getting-started/configuration/). - {{% /warning %}} ++{{< readfile file="/content/readfiles/sectionvars.md" markdown="true" >}} ++ ++## Content Section Lists ++ ++Hugo will automatically create pages for each section root that list all of the content in that section. See the documentation on [section templates][] for details on customizing the way these pages are rendered. + +## Content *Section* vs Content *Type* + - By default, everything created within a section will use the [content type][] that matches the section name. For example, Hugo will assume that `posts/post-1.md` has a `posts` content type. If you are using an [archetype][] for your posts section, Hugo will generate front matter according to what it finds in `archetypes/posts.md`. ++By default, everything created within a section will use the [content type][] that matches the root section name. For example, Hugo will assume that `posts/post-1.md` has a `posts` content type. If you are using an [archetype][] for your posts section, Hugo will generate front matter according to what it finds in `archetypes/posts.md`. + +[archetype]: /content-management/archetypes/ +[content type]: /content-management/types/ +[directory structure]: /getting-started/directory-structure/ +[section templates]: /templates/section-templates/ + + diff --cc docs/content/content-management/static-files.md index c8ad75de,00000000..12d27ccf mode 100644,000000..100644 --- a/docs/content/content-management/static-files.md +++ b/docs/content/content-management/static-files.md @@@ -1,45 -1,0 +1,48 @@@ +--- +title: Static Files +description: "The `static` folder is where you place all your **static files**." +date: 2017-11-18 +categories: [content management] +keywords: [source, directories] +menu: + docs: + parent: "content-management" + weight: 130 +weight: 130 #rem +aliases: [/static-files] +toc: true +--- + +The `static` folder is where you place all your **static files**, e.g. stylesheets, JavaScript, images etc. + +You can set the name of the static folder to use in your configuration file, for example `config.toml`. From **Hugo 0.31** you can configure as many static directories as you need. All the files in all the static directories will form a union filesystem. + +Example: + +```toml +staticDir = ["static1", "static2"] +[languages] +[languages.no] +staticDir = ["staticDir_override", "static_no"] +baseURL = "https://example.no" +languageName = "Norsk" +weight = 1 +title = "PÃ¥ norsk" + +[languages.en] +staticDir2 = "static_en" +baseURL = "https://example.com" +languageName = "English" +weight = 2 +title = "In English" +``` + +In the above, with no theme used: + +* The English site will get its static files as a union of "static1", "static2" and "static_en". On file duplicates, the right-most version will win. +* The Norwegian site will get its static files as a union of "staticDir_override" and "static_no". + ++**Note:** The `2` `static2` (can be a number between 0 and 10) is added to tell Hugo that you want to **add** this directory to the global set of static directories. Using `staticDir` on the language level would replace the global value. ++ ++ +**Note:** The example above is a [multihost setup](/content-management/multilingual/#configure-multilingual-multihost). In a regular setup, all the static directories will be available to all sites. diff --cc docs/content/functions/ref.md index ac35cc8b,00000000..d63c0a89 mode 100644,000000..100644 --- a/docs/content/functions/ref.md +++ b/docs/content/functions/ref.md @@@ -1,30 -1,0 +1,34 @@@ +--- +title: ref +linktitle: ref +description: Looks up a content page by logical name. +godocref: +date: 2017-02-01 +publishdate: 2017-02-01 +lastmod: 2017-02-01 +categories: [functions] +menu: + docs: + parent: "functions" +keywords: [cross references, anchors] - signature: ["ref CONTENT"] ++signature: ["ref . CONTENT"] +workson: [] +hugoversion: +relatedfuncs: [relref] +deprecated: false +aliases: [] +--- + - `ref` and `relRef` look up a content page by relative path (`relref`) or logical name (`ref`) to return the permalink: ++`ref` and `relref` look up a content page by logical name (`ref`) or relative path (`relref`) to return the permalink: + +``` - {{ ref "about.md" }} ++{{ ref . "about.md" }} +``` + ++{{% note "Usage Note" %}} ++`ref` looks up Hugo "Regular Pages" only. It can't be used for the homepage, section pages, etc. ++{{% /note %}} ++ +These functions are used in two of Hugo's built-in shortcodes. You can see basic usage examples of both `ref` and `relref` in the [shortcode documentation](/content-management/shortcodes/#ref-and-relref). + +For an extensive explanation of how to leverage `ref` and `relref` for content management, see [Cross References](/content-management/cross-references/). diff --cc docs/content/functions/relref.md index 32d7075c,00000000..ea992af2 mode 100644,000000..100644 --- a/docs/content/functions/relref.md +++ b/docs/content/functions/relref.md @@@ -1,30 -1,0 +1,34 @@@ +--- +title: relref +# linktitle: relref +description: Looks up a content page by relative path. +godocref: +date: 2017-02-01 +publishdate: 2017-02-01 +lastmod: 2017-02-01 +categories: [functions] +menu: + docs: + parent: "functions" +keywords: [cross references, anchors] - signature: ["relref CONTENT"] ++signature: ["relref . CONTENT"] +workson: [] +hugoversion: - relatedfuncs: [relref] ++relatedfuncs: [ref] +deprecated: false +aliases: [] +--- + - `ref` and `relRef` look up a content page by relative path (`relref`) or logical name (`ref`) to return the permalink: ++`ref` and `relref` look up a content page by logical name (`ref`) or relative path (`relref`) to return the permalink: + +``` - {{ relref "about.md" }} ++{{ relref . "about.md" }} +``` + ++{{% note "Usage Note" %}} ++`relref` looks up Hugo "Regular Pages" only. It can't be used for the homepage, section pages, etc. ++{{% /note %}} ++ +These functions are used in two of Hugo's built-in shortcodes. You can see basic usage examples of both `ref` and `relref` in the [shortcode documentation](/content-management/shortcodes/#ref-and-relref). + +For an extensive explanation of how to leverage `ref` and `relref` for content management, see [Cross References](/content-management/cross-references/). diff --cc docs/content/getting-started/configuration.md index 27d959e8,00000000..d4fb5a17 mode 100644,000000..100644 --- a/docs/content/getting-started/configuration.md +++ b/docs/content/getting-started/configuration.md @@@ -1,400 -1,0 +1,399 @@@ +--- +title: Configure Hugo +linktitle: Configuration +description: Often the default settings are good enough, but the config file can provide highly granular control over how your site is rendered. +date: 2013-07-01 +publishdate: 2017-01-02 +lastmod: 2017-03-05 +categories: [getting started,fundamentals] +keywords: [configuration,toml,yaml,json] +menu: + docs: + parent: "getting-started" + weight: 60 +weight: 60 +sections_weight: 60 +draft: false +aliases: [/overview/source-directory/,/overview/configuration/] +toc: true +--- + +The [directory structure][] of a Hugo website—or more precisely, the source organization of files containing the website's content and templates—provides most of the configuration information that Hugo needs in order to generate a finished website. + +Because of Hugo's sensible defaults, many websites may not need a configuration file. Hugo is designed to recognize certain typical usage patterns. + +## Configuration Lookup Order + +Similar to the template [lookup order][], Hugo has a default set of rules for searching for a configuration file in the root of your website's source directory as a default behavior: + +1. `./config.toml` +2. `./config.yaml` +3. `./config.json` + +In your `config` file, you can direct Hugo as to how you want your website rendered, control your website's menus, and arbitrarily define site-wide parameters specific to your project. + +## YAML Configuration + +The following is a typical example of a YAML configuration file. The values nested under `params:` will populate the [`.Site.Params`][] variable for use in [templates][]: + +{{< code file="config.yml">}} +baseURL: "https://yoursite.example.com/" +title: "My Hugo Site" +footnoteReturnLinkContents: "↩" +permalinks: + post: /:year/:month/:title/ +params: + Subtitle: "Hugo is Absurdly Fast!" + AuthorName: "Jon Doe" + GitHubUser: "spf13" + ListOfFoo: + - "foo1" + - "foo2" + SidebarRecentLimit: 5 +{{< /code >}} + +### All Variables, YAML + +The following is the full list of Hugo-defined variables in an example YAML file. The values provided in this example represent the default values used by Hugo. + +{{< code file="config.yml" download="config.yml" >}} +archetypeDir: "archetypes" +# hostname (and path) to the root, e.g. http://spf13.com/ +baseURL: "" +# include content marked as draft +buildDrafts: false +# include content with publishdate in the future +buildFuture: false +# include content already expired +buildExpired: false +# enable this to make all relative URLs relative to content root. Note that this does not affect absolute URLs. See the "URL Management" page +relativeURLs: false +canonifyURLs: false +# config file (default is path/config.yaml|json|toml) +config: "config.toml" +contentDir: "content" +dataDir: "data" +defaultExtension: "html" +defaultLayout: "post" +# Missing translations will default to this content language +defaultContentLanguage: "en" +# Renders the default content language in subdir, e.g. /en/. The root directory / will redirect to /en/ +defaultContentLanguageInSubdir: false +disableLiveReload: false +# Do not build RSS files +disableRSS: false +# Do not build Sitemap file +disableSitemap: false +# Enable GitInfo feature +enableGitInfo: false +# Build robots.txt file +enableRobotsTXT: false +# Do not render 404 page +disable404: false +# Do not inject generator meta tag on homepage +disableHugoGeneratorInject: false +# Allows you to disable all page types and will render nothing related to 'kind'; +# values = "page", "home", "section", "taxonomy", "taxonomyTerm", "RSS", "sitemap", "robotsTXT", "404" +disableKinds: [] +# Do not make the url/path to lowercase +disablePathToLower: false "" +# Enable Emoji emoticons support for page content; see emoji-cheat-sheet.com +enableEmoji: false +# Show a placeholder instead of the default value or an empty string if a translation is missing +enableMissingTranslationPlaceholders: false +footnoteAnchorPrefix: "" +footnoteReturnLinkContents: "" +# google analytics tracking id +googleAnalytics: "" +# if true, auto-detect Chinese/Japanese/Korean Languages in the content. (.Summary and .WordCount can work properly in CJKLanguage) +hasCJKLanguage: false +languageCode: "" +# the length of text to show in a .Summary +summaryLength: 70 +layoutDir: "layouts" +# Enable Logging +log: false +# Log File path (if set, logging enabled automatically) +logFile: "" +# "toml","yaml", or "json" +metaDataFormat: "toml" +newContentEditor: "" +# Don't sync permission mode of files +noChmod: false +# Don't sync modification time of files +noTimes: false +# Pagination +paginate: 10 +paginatePath: "page" +# See "content-management/permalinks" +permalinks: +# Pluralize titles in lists using inflect +pluralizeListTitles: true +# Preserve special characters in taxonomy names ("Gérard Depardieu" vs "Gerard Depardieu") +preserveTaxonomyNames: false +# filesystem path to write files to +publishDir: "public" +# enables syntax guessing for code fences without specified language +pygmentsCodeFencesGuessSyntax: false +# color-codes for highlighting derived from this style +pygmentsStyle: "monokai" +# true use pygments-css or false will color code directly +pygmentsUseClasses: false +# maximum number of items in the RSS feed +rssLimit: 15 +# see "Section Menu for Lazy Bloggers", /templates/menu-templates for more info +SectionPagesMenu: "" +# default sitemap configuration map +sitemap: +# filesystem path to read files relative from +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: "" +title: "" +# Title Case style guide for the title func and other automatic title casing in Hugo. +// Valid values are "AP" (default), "Chicago" and "Go" (which was what you had in Hugo <= 0.25.1). +// See https://www.apstylebook.com/ and http://www.chicagomanualofstyle.org/home.html +titleCaseStyle: "AP" +# if true, use /filename.html instead of /filename/ +uglyURLs: false +# verbose output +verbose: false +# verbose logging +verboseLog: false +# watch filesystem for changes and recreate as needed +watch: true +taxonomies: + - category: "categories" + - tag: "tags" +{{< /code >}} + +## TOML Configuration + +The following is an example of a TOML configuration file. The values under `[params]` will populate the `.Site.Params` variable for use in [templates][]: + +{{< code file="config.toml">}} +contentDir = "content" +layoutDir = "layouts" +publishDir = "public" +buildDrafts = false +baseURL = "https://yoursite.example.com/" +canonifyURLs = true +title = "My Hugo Site" + +[taxonomies] + category = "categories" + tag = "tags" + +[params] + subtitle = "Hugo is Absurdly Fast!" + author = "John Doe" +{{< /code >}} + +### All Variables, TOML + +The following is the full list of Hugo-defined variables in an example TOML file. The values provided in this example represent the default values used by Hugo. + +{{< code file="config.toml" download="config.toml">}} +archetypeDir = "archetypes" +# hostname (and path) to the root, e.g. http://spf13.com/ +baseURL = "" +# include content marked as draft +buildDrafts = false +# include content with publishdate in the future +buildFuture = false +# include content already expired +buildExpired = false +# enable this to make all relative URLs relative to content root. Note that this does not affect absolute URLs. +relativeURLs = false +canonifyURLs = false +# config file (default is path/config.yaml|json|toml) +config = "config.toml" +contentDir = "content" +dataDir = "data" +defaultExtension = "html" +defaultLayout = "post" +# Missing translations will default to this content language +defaultContentLanguage = "en" +# Renders the default content language in subdir, e.g. /en/. The root directory / will redirect to /en/ +defaultContentLanguageInSubdir = false +disableLiveReload = false +# Do not build RSS files +disableRSS = false +# Do not build Sitemap file +disableSitemap = false +# Enable GitInfo feature +enableGitInfo = false +# Build robots.txt file +enableRobotsTXT = false +# Do not render 404 page +disable404 = false +# Do not inject generator meta tag on homepage +disableHugoGeneratorInject = false +# Allows you to disable all page types and will render nothing related to 'kind'; +# values = "page", "home", "section", "taxonomy", "taxonomyTerm", "RSS", "sitemap", "robotsTXT", "404" +disableKinds = [] +# Do not make the url/path to lowercase +disablePathToLower = false +# Enable Emoji emoticons support for page content; see emoji-cheat-sheet.com +enableEmoji = false +# Show a placeholder instead of the default value or an empty string if a translation is missing +enableMissingTranslationPlaceholders = false +footnoteAnchorPrefix = "" +footnoteReturnLinkContents = "" +# google analytics tracking id +googleAnalytics = "" +# if true, auto-detect Chinese/Japanese/Korean Languages in the content. (.Summary and .WordCount can work properly in CJKLanguage) +hasCJKLanguage = false +languageCode = "" +# the length of text to show in a .Summary +summaryLength = 70 +layoutDir = "layouts" +# Enable Logging +log = false +# Log File path (if set, logging enabled automatically) +logFile = +# maximum number of items in the RSS feed +rssLimit = 15 +# "toml","yaml", or "json" +metaDataFormat = "toml" +newContentEditor = "" +# Don't sync permission mode of files +noChmod = false +# Don't sync modification time of files +noTimes = false +# Pagination +paginate = 10 +paginatePath = "page" +# See "content-management/permalinks" +permalinks = +# Pluralize titles in lists using inflect +pluralizeListTitles = true +# Preserve special characters in taxonomy names ("Gérard Depardieu" vs "Gerard Depardieu") +preserveTaxonomyNames = false +# filesystem path to write files to +publishDir = "public" +# enables syntax guessing for code fences without specified language +pygmentsCodeFencesGuessSyntax = false +# color-codes for highlighting derived from this style +pygmentsStyle = "monokai" +# true: use pygments-css or false: color-codes directly +pygmentsUseClasses = false +# see "Section Menu for Lazy Bloggers", /templates/menu-templates for more info +SectionPagesMenu = +# default sitemap configuration map +sitemap = - # filesystem path to read files relative from - source = "" ++# filesystem path to read static files relative from +staticDir = "static" +# display memory and timing of different steps of the program +stepAnalysis = false +# theme to use (located by default in /themes/THEMENAME/) +themesDir = "themes" +theme = "" +title = "" +# if true, use /filename.html instead of /filename/ +uglyURLs = false +# verbose output +verbose = false +# verbose logging +verboseLog = false +# watch filesystem for changes and recreate as needed +watch = true +[taxonomies] + category = "categories" + tag = "tags" +{{< /code >}} + +{{% note %}} +If you are developing your site on a \*nix machine, here is a handy shortcut for finding a configuration option from the command line: +``` +cd ~/sites/yourhugosite +hugo config | grep emoji +``` + +which shows output like + +``` +enableemoji: true +``` +{{% /note %}} + +## Environmental Variables + +In addition to the 3 config options already mentioned, configuration key-values can be defined through operating system environment variables. + +For example, the following command will effectively set a website's title on Unix-like systems: + +``` +$ env HUGO_TITLE="Some Title" hugo +``` + +{{% note "Setting Environment Variables" %}} +Names must be prefixed with `HUGO_` and the configuration key must be set in uppercase when setting operating system environment variables. +{{% /note %}} + +## Ignore Files When Rendering + +The following statement inside `./config.toml` will cause Hugo to ignore files ending with `.foo` and `.boo` when rendering: + +``` +ignoreFiles = [ "\\.foo$", "\\.boo$" ] +``` + +The above is a list of regular expressions. Note that the backslash (`\`) character is escaped in this example to keep TOML happy. + +## Configure Blackfriday + +[Blackfriday](https://github.com/russross/blackfriday) is Hugo's built-in Markdown rendering engine. + +Hugo typically configures Blackfriday with sane default values that should fit most use cases reasonably well. + +However, if you have specific needs with respect to Markdown, Hugo exposes some of its Blackfriday behavior options for you to alter. The following table lists these Hugo options, paired with the corresponding flags from Blackfriday's source code ( [html.go](https://github.com/russross/blackfriday/blob/master/html.go) and [markdown.go](https://github.com/russross/blackfriday/blob/master/markdown.go)). + +{{< readfile file="/content/readfiles/bfconfig.md" markdown="true" >}} + +{{% note %}} +1. Blackfriday flags are *case sensitive* as of Hugo v0.15. +2. Blackfriday flags must be grouped under the `blackfriday` key and can be set on both the site level *and* the page level. Any setting on a page will override its respective site setting. +{{% /note %}} + +{{< code file="bf-config.toml" >}} +[blackfriday] + angledQuotes = true + fractions = false + plainIDAnchors = true + extensions = ["hardLineBreak"] +{{< /code >}} + +{{< code file="bf-config.yml" >}} +blackfriday: + angledQuotes: true + fractions: false + plainIDAnchors: true + extensions: + - hardLineBreak +{{< /code >}} + +## Configure Additional Output Formats + +Hugo v0.20 introduced the ability to render your content to multiple output formats (e.g., to JSON, AMP html, or CSV). See [Output Formats][] for information on how to add these values to your Hugo project's configuration file. + +## Configuration Format Specs + +* [TOML Spec][toml] +* [YAML Spec][yaml] +* [JSON Spec][json] + +[`.Site.Params`]: /variables/site/ +[directory structure]: /getting-started/directory-structure +[json]: https://www.ecma-international.org/publications/files/ECMA-ST/ECMA-404.pdf "Specification for JSON, JavaScript Object Notation" +[lookup order]: /templates/lookup-order/ +[Output Formats]: /templates/output-formats/ +[templates]: /templates/ +[toml]: https://github.com/toml-lang/toml +[yaml]: http://yaml.org/spec/ diff --cc docs/content/getting-started/installing.md index 9745cbee,00000000..0375ceea mode 100644,000000..100644 --- a/docs/content/getting-started/installing.md +++ b/docs/content/getting-started/installing.md @@@ -1,492 -1,0 +1,492 @@@ +--- +title: Install Hugo +linktitle: Install Hugo +description: Install Hugo on macOS, Windows, Linux, FreeBSD, and on any machine where the Go compiler tool chain can run. +date: 2016-11-01 +publishdate: 2016-11-01 +lastmod: 2017-02-20 +categories: [getting started,fundamentals] +authors: ["Michael Henderson"] +keywords: [install,pc,windows,linux,macos,binary,tarball] +menu: + docs: + parent: "getting-started" + weight: 30 +weight: 30 +sections_weight: 30 +draft: false +aliases: [/tutorials/installing-on-windows/,/tutorials/installing-on-mac/,/overview/installing/,/getting-started/install,/install/] +toc: true +--- + + +{{% note %}} +There is lots of talk about "Hugo being written in Go", but you don't need to install Go to enjoy Hugo. Just grab a precompiled binary! +{{% /note %}} + +Hugo is written in [Go](https://golang.org/) with support for multiple platforms. The latest release can be found at [Hugo Releases][releases]. + +Hugo currently provides pre-built binaries for the following: + +* macOS (Darwin) for x64, i386, and ARM architectures +* Windows +* Linux +* FreeBSD + +Hugo may also be compiled from source wherever the Go compiler tool chain can run; e.g., on other operating systems such as DragonFly BSD, OpenBSD, Plan 9, Solaris, and others. See for the full set of supported combinations of target operating systems and compilation architectures. + +## Quick Install + +### Binary (Cross-platform) + +Download the appropriate version for your platform from [Hugo Releases][releases]. Once downloaded, the binary can be run from anywhere. You don't need to install it into a global location. This works well for shared hosts and other systems where you don't have a privileged account. + +Ideally, you should install it somewhere in your `PATH` for easy use. `/usr/local/bin` is the most probable location. + +### Homebrew (macOS) + +If you are on macOS and using [Homebrew][brew], you can install Hugo with the following one-liner: + +{{< code file="install-with-homebrew.sh" >}} +brew install hugo +{{< /code >}} + +For more detailed explanations, read the installation guides that follow for installing on macOS and Windows. + +### Chocolatey (Windows) + +If you are on a Windows machine and use [Chocolatey][] for package management, you can install Hugo with the following one-liner: + +{{< code file="install-with-chocolatey.ps1" >}} +choco install hugo -confirm +{{< /code >}} + +### Source + +#### Prerequisite Tools + +* [Git][installgit] +* [Go 1.5+][installgo] +* [govendor][] + +#### Vendored Dependencies + +Hugo uses [govendor][] to vendor dependencies, but we don't commit the vendored packages themselves to the Hugo git repository. Therefore, a simple `go get` is *not* supported because the command is not vendor aware. *You must use `govendor` to fetch Hugo's dependencies.* + +#### Fetch from GitHub + +{{< code file="from-gh.sh" >}} +go get github.com/kardianos/govendor +govendor get github.com/gohugoio/hugo +go install github.com/gohugoio/hugo +{{< /code >}} + +`govendor get` will fetch Hugo and all its dependent libraries to `$GOPATH/src/github.com/gohugoio/hugo`, and `go install` compiles everything into a final `hugo` (or `hugo.exe`) executable inside `$GOPATH/bin/`. + +{{% note %}} +If you are a Windows user, substitute the `$HOME` environment variable above with `%USERPROFILE%`. +{{% /note %}} + +## macOS + +### Assumptions + +1. You know how to open the macOS terminal. +2. You're running a modern 64-bit Mac. +3. You will use `~/Sites` as the starting point for your site. (`~/Sites` is used for example purposes. If you are familiar enough with the command line and file system, you should have no issues following along with the instructions.) + +### Pick Your Method + +There are three ways to install Hugo on your Mac + +1. The [Homebrew][brew] `brew` utility +2. Distribution (i.e., tarball) +3. Building from Source + +There is no "best" way to install Hugo on your Mac. You should use the method that works best for your use case. + +#### Pros and Cons + +There are pros and cons to each of the aforementioned methods: + +1. **Homebrew.** Homebrew is the simplest method and will require the least amount of work to maintain. The drawbacks aren't severe. The default package will be for the most recent release, so it will not have bug fixes until the next release (i.e., unless you install it with the `--HEAD` option). Hugo `brew` releases may lag a few days behind because it has to be coordinated with another team. Nevertheless, `brew` is the recommended installation method if you want to work from a stable, widely used source. Brew works well and is easy to update. + +2. **Tarball.** Downloading and installing from the tarball is also easy, although it requires a few more command line skills than does Homebrew. Updates are easy as well: you just repeat the process with the new binary. This gives you the flexibility to have multiple versions on your computer. If you don't want to use `brew`, then the tarball/binary is a good choice. + +3. **Building from Source.** Building from source is the most work. The advantage of building from source is that you don't have to wait for a release to add features or bug fixes. The disadvantage is that you need to spend more time managing the setup, which is manageable but requires more time than the preceding two options. + +{{% note %}} +Since building from source is appealing to more seasoned command line users, this guide will focus more on installing Hugo via Homebrew and Tarball. +{{% /note %}} + +### Install Hugo with Brew + +{{< youtube WvhCGlLcrF8 >}} + +#### Step 1: Install `brew` if you haven't already + +Go to the `brew` website, , and follow the directions there. The most important step is the installation from the command line: + +{{< code file="install-brew.sh" >}} +ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)" +{{< /code >}} + +#### Step 2: Run the `brew` Command to Install `hugo` + +Installing Hugo using `brew` is as easy as the following: + +{{< code file="install-brew.sh" >}} +brew install hugo +{{< /code >}} + +If Homebrew is working properly, you should see something similar to the following: + +``` +==> Downloading https://homebrew.bintray.com/bottles/hugo-0.21.sierra.bottle.tar.gz +######################################################################### 100.0% +==> Pouring hugo-0.21.sierra.bottle.tar.gz +🍺 /usr/local/Cellar/hugo/0.21: 32 files, 17.4MB +``` + +{{% note "Installing the Latest Hugo with Brew" %}} +Replace `brew install hugo` with `brew install hugo --HEAD` if you want the absolute latest in-development version. +{{% /note %}} + +`brew` should have updated your path to include Hugo. You can confirm by opening a new terminal window and running a few commands: + +``` +$ # show the location of the hugo executable +which hugo +/usr/local/bin/hugo + +# show the installed version +ls -l $( which hugo ) +lrwxr-xr-x 1 mdhender admin 30 Mar 28 22:19 /usr/local/bin/hugo -> ../Cellar/hugo/0.13_1/bin/hugo + +# verify that hugo runs correctly +hugo version +Hugo Static Site Generator v0.13 BuildDate: 2015-03-09T21:34:47-05:00 +``` + +### Install Hugo from Tarball + +#### Step 1: Decide on the location + +When installing from the tarball, you have to decide if you're going to install the binary in `/usr/local/bin` or in your home directory. There are three camps on this: + +1. Install it in `/usr/local/bin` so that all the users on your system have access to it. This is a good idea because it's a fairly standard place for executables. The downside is that you may need elevated privileges to put software into that location. Also, if there are multiple users on your system, they will all run the same version. Sometimes this can be an issue if you want to try out a new release. + +2. Install it in `~/bin` so that only you can execute it. This is a good idea because it's easy to do, easy to maintain, and doesn't require elevated privileges. The downside is that only you can run Hugo. If there are other users on your site, they have to maintain their own copies. That can lead to people running different versions. Of course, this does make it easier for you to experiment with different releases. + +3. Install it in your `Sites` directory. This is not a bad idea if you have only one site that you're building. It keeps every thing in a single place. If you want to try out new releases, you can make a copy of the entire site and update the Hugo executable. + +All three locations will work for you. In the interest of brevity, this guide focuses on option #2. + +#### Step 2: Download the Tarball + +1. Open in your browser. + +2. Find the current release by scrolling down and looking for the green tag that reads "Latest Release." + +3. Download the current tarball for the Mac. The name will be something like `hugo_X.Y_osx-64bit.tgz`, where `X.YY` is the release number. + +4. By default, the tarball will be saved to your `~/Downloads` directory. If you choose to use a different location, you'll need to change that in the following steps. + +#### Step 3: Confirm your download + +Verify that the tarball wasn't corrupted during the download: + +``` +tar tvf ~/Downloads/hugo_X.Y_osx-64bit.tgz +-rwxrwxrwx 0 0 0 0 Feb 22 04:02 hugo_X.Y_osx-64bit/hugo_X.Y_osx-64bit.tgz +-rwxrwxrwx 0 0 0 0 Feb 22 03:24 hugo_X.Y_osx-64bit/README.md +-rwxrwxrwx 0 0 0 0 Jan 30 18:48 hugo_X.Y_osx-64bit/LICENSE.md +``` + +The `.md` files are documentation for Hugo. The other file is the executable. + +#### Step 4: Install Into Your `bin` Directory + +``` +# create the directory if needed +mkdir -p ~/bin + +# make it the working directory +cd ~/bin + +# extract the tarball +tar -xvzf ~/Downloads/hugo_X.Y_osx-64bit.tgz +Archive: hugo_X.Y_osx-64bit.tgz + x ./ + x ./hugo + x ./LICENSE.md + x ./README.md + +# verify that it runs +./hugo version +Hugo Static Site Generator v0.13 BuildDate: 2015-02-22T04:02:30-06:00 +``` + +You may need to add your bin directory to your `PATH` variable. The `which` command will check for us. If it can find `hugo`, it will print the full path to it. Otherwise, it will not print anything. + +``` +# check if hugo is in the path +which hugo +/Users/USERNAME/bin/hugo +``` + +If `hugo` is not in your `PATH`, add it by updating your `~/.bash_profile` file. First, start up an editor: + +``` +nano ~/.bash_profile +``` + +Add a line to update your `PATH` variable: + +``` +export PATH=$PATH:$HOME/bin +``` + +Then save the file by pressing Control-X, then Y to save the file and return to the prompt. + +Close the terminal and open a new terminal to pick up the changes to your profile. Verify your success by running the `which hugo` command again. + +You've successfully installed Hugo. + +### Build from Source on Mac + +If you want to compile Hugo yourself, you'll need to install Go (aka Golang). You can [install Go directly from the Go website](https://golang.org/dl/) or via Homebrew using the following command: + +``` +brew install go +``` + +#### Step 1: Get the Source + +If you want to compile a specific version of Hugo, go to and download the source code for the version of your choice. If you want to compile Hugo with all the latest changes (which might include bugs), clone the Hugo repository: + +``` +git clone https://github.com/gohugoio/hugo +``` + +{{% warning "Sometimes \"Latest\" = \"Bugs\""%}} +Cloning the Hugo repository directly means taking the good with the bad. By using the bleeding-edge version of Hugo, you make your development susceptible to the latest features, as well as the latest bugs. Your feedback is appreciated. If you find a bug in the latest release, [please create an issue on GitHub](https://github.com/gohugoio/hugo/issues/new). +{{% /warning %}} + +#### Step 2: Compiling + +Make the directory containing the source your working directory and then fetch Hugo's dependencies: + +``` +mkdir -p src/github.com/gohugoio +ln -sf $(pwd) src/github.com/gohugoio/hugo + +# set the build path for Go +export GOPATH=$(pwd) + +go get +``` + +This will fetch the absolute latest version of the dependencies. If Hugo fails to build, it may be the result of a dependency's author introducing a breaking change. + +Once you have properly configured your directory, you can compile Hugo using the following command: + +``` +go build -o hugo main.go +``` + +Then place the `hugo` executable somewhere in your `$PATH`. You're now ready to start using Hugo. + +## Windows + +The following aims to be a complete guide to installing Hugo on your Windows PC. + +{{< youtube G7umPCU-8xc >}} + +### Assumptions + +1. You will use `C:\Hugo\Sites` as the starting point for your new project. +2. You will use `C:\Hugo\bin` to store executable files. + +### Set up Your Directories + +You'll need a place to store the Hugo executable, your [content][], and the generated Hugo website: + +1. Open Windows Explorer. +2. Create a new folder: `C:\Hugo`, assuming you want Hugo on your C drive, although this can go anywhere +3. Create a subfolder in the Hugo folder: `C:\Hugo\bin` +4. Create another subfolder in Hugo: `C:\Hugo\Sites` + +### Technical Users + +1. Download the latest zipped Hugo executable from [Hugo Releases][releases]. +2. Extract all contents to your `..\Hugo\bin` folder. +3. The `hugo` executable will be named as `hugo_hugo-version_platform_arch.exe`. Rename the executable to `hugo.exe` for ease of use. +4. In PowerShell or your preferred CLI, add the `hugo.exe` executable to your PATH by navigating to `C:\Hugo\bin` (or the location of your hugo.exe file) and use the command `set PATH=%PATH%;C:\Hugo\bin`. If the `hugo` command does not work after a reboot, you may have to run the command prompt as administrator. + +### Less-technical Users + +1. Go to the [Hugo Releases][releases] page. +2. The latest release is announced on top. Scroll to the bottom of the release announcement to see the downloads. They're all ZIP files. +3. Find the Windows files near the bottom (they're in alphabetical order, so Windows is last) – download either the 32-bit or 64-bit file depending on whether you have 32-bit or 64-bit Windows. (If you don't know, [see here](https://esupport.trendmicro.com/en-us/home/pages/technical-support/1038680.aspx).) +4. Move the ZIP file into your `C:\Hugo\bin` folder. +5. Double-click on the ZIP file and extract its contents. Be sure to extract the contents into the same `C:\Hugo\bin` folder – Windows will do this by default unless you tell it to extract somewhere else. +6. You should now have three new files: hugo executable (e.g. `hugo_0.18_windows_amd64.exe`), `license.md`, and `readme.md`. (You can delete the ZIP download now.) Rename that hugo executable (`hugo_hugo-version_platform_arch.exe`) to `hugo.exe` for ease of use. + +Now you need to add Hugo to your Windows PATH settings: + +#### For Windows 10 Users: + +* Right click on the **Start** button. +* Click on **System**. +* Click on **Advanced System Settings** on the left. +* Click on the **Environment Variables...** button on the bottom. +* In the User variables section, find the row that starts with PATH (PATH will be all caps). +* Double-click on **PATH**. +* Click the **New...** button. +* Type in the folder where `hugo.exe` was extracted, which is `C:\Hugo\bin` if you went by the instructions above. *The PATH entry should be the folder where Hugo lives and not the binary.* Press Enter when you're done typing. +* Click OK at every window to exit. + +{{% note "Path Editor in Windows 10"%}} +The path editor in Windows 10 was added in the large [November 2015 Update](https://blogs.windows.com/windowsexperience/2015/11/12/first-major-update-for-windows-10-available-today/). You'll need to have that or a later update installed for the above steps to work. You can see what Windows 10 build you have by clicking on the  Start button → Settings → System → About. See [here](https://www.howtogeek.com/236195/how-to-find-out-which-build-and-version-of-windows-10-you-have/) for more.) +{{% /note %}} + +#### For Windows 7 and 8.x users: + +Windows 7 and 8.1 do not include the easy path editor included in Windows 10, so non-technical users on those platforms are advised to install a free third-party path editor like [Windows Environment Variables Editor][Windows Environment Variables Editor] or [Path Editor](https://patheditor2.codeplex.com/). + +### Verify the Executable + +Run a few commands to verify that the executable is ready to run, and then build a sample site to get started. + +#### 1. Open a Command Prompt + +At the prompt, type `hugo help` and press the Enter key. You should see output that starts with: + +``` +hugo is the main command, used to build your Hugo site. + +Hugo is a Fast and Flexible Static Site Generator +built with love by spf13 and friends in Go. + +Complete documentation is available at https://gohugo.io/. +``` + +If you do, then the installation is complete. If you don't, double-check the path that you placed the `hugo.exe` file in and that you typed that path correctly when you added it to your `PATH` variable. If you're still not getting the output, search the [Hugo discussion forum][forum] to see if others have already figured out our problem. If not, add a note---in the "Support" category---and be sure to include your command and the output. + +At the prompt, change your directory to the `Sites` directory. + +``` +C:\Program Files> cd C:\Hugo\Sites +C:\Hugo\Sites> +``` + +#### 2. Run the Command + +Run the command to generate a new site. I'm using `example.com` as the name of the site. + +``` +C:\Hugo\Sites> hugo new site example.com +``` + +You should now have a directory at `C:\Hugo\Sites\example.com`. Change into that directory and list the contents. You should get output similar to the following: + +``` +C:\Hugo\Sites> cd example.com +C:\Hugo\Sites\example.com> dir +Directory of C:\hugo\sites\example.com + +04/13/2015 10:44 PM . +04/13/2015 10:44 PM .. +04/13/2015 10:44 PM archetypes +04/13/2015 10:44 PM 83 config.toml +04/13/2015 10:44 PM content +04/13/2015 10:44 PM data +04/13/2015 10:44 PM layouts +04/13/2015 10:44 PM static + 1 File(s) 83 bytes + 7 Dir(s) 6,273,331,200 bytes free +``` + +### Troubleshoot Windows Installation + +[@dhersam][] has created a nice video on common issues: + +{{< youtube c8fJIRNChmU >}} + +## Linux + +### Snap Package + +In any of the [Linux distributions that support snaps][snaps]: + +``` +snap install hugo +``` + - {{% note %}} - Hugo-as-a-snap can write only inside the user’s `$HOME` directory---and gvfs-mounted directories owned by the user---because of Snaps’ confinement and security model. More information is also available [in this related GitHub issue](https://github.com/gohugoio/hugo/issues/3143). - {{% /note %}} - +### Debian and Ubuntu + +Debian and Ubuntu provide a `hugo` version via `apt-get`: + +``` +sudo apt-get install hugo +``` + +#### Pros + +* Native Debian/Ubuntu package maintained by Debian Developers +* Pre-installed bash completion script and `man` pages + +#### Cons + +* Might not be the latest version, especially if you are using an older, stable version (e.g., Ubuntu 16.04 LTS). Until backports and PPA are available, you may consider installing the Hugo snap package to get the latest version of Hugo. + ++{{% note %}} ++Hugo-as-a-snap can write only inside the user’s `$HOME` directory---and gvfs-mounted directories owned by the user---because of Snaps’ confinement and security model. More information is also available [in this related GitHub issue](https://github.com/gohugoio/hugo/issues/3143). Use ```sudo apt-get install hugo --classic``` to disable the default security model if you want hugo to be able to have write access in other paths besides the user’s `$HOME` directory. ++{{% /note %}} ++ +### Arch Linux + +You can also install Hugo from the Arch Linux [community](https://www.archlinux.org/packages/community/x86_64/hugo/) repository. Applies also for derivatives such as Manjaro. + +``` +sudo pacman -Sy hugo +``` + +### Fedora, CentOS, and Red Hat + +* + +See the [related discussion in the Hugo forums][redhatforum]. + +## Upgrade Hugo + +Upgrading Hugo is as easy as downloading and replacing the executable you’ve placed in your `PATH` or run `brew upgrade hugo` if using Homebrew. + +## Install Pygments (Optional) + +The Hugo executable has one *optional* external dependency for source code highlighting ([Pygments][pygments]). + +If you want to have source code highlighting using the [highlight shortcode][], you need to install the Python-based Pygments program. The procedure is outlined on the [Pygments homepage][pygments]. + +## Next Steps + +Now that you've installed Hugo, read the [Quick Start guide][quickstart] and explore the rest of the documentation. If you have questions, ask the Hugo community directly by visiting the [Hugo Discussion Forum][forum]. + +[brew]: https://brew.sh/ +[Chocolatey]: https://chocolatey.org/ +[content]: /content-management/ +[@dhersam]: https://github.com/dhersam +[forum]: https://discourse.gohugo.io +[govendor]: https://github.com/kardianos/govendor +[highlight shortcode]: /content-management/shortcodes/#highlight +[installgit]: http://git-scm.com/ +[installgo]: https://golang.org/dl/ +[Path Editor]: https://patheditor2.codeplex.com/ +[pygments]: http://pygments.org +[quickstart]: /getting-started/quick-start/ +[redhatforum]: https://discourse.gohugo.io/t/solved-fedora-copr-repository-out-of-service/2491 +[releases]: https://github.com/gohugoio/hugo/releases +[snaps]: http://snapcraft.io/docs/core/install +[windowsarch]: https://esupport.trendmicro.com/en-us/home/pages/technical-support/1038680.aspx +[Windows Environment Variables Editor]: http://eveditor.com/ diff --cc docs/content/hosting-and-deployment/hosting-on-gitlab.md index 05a9a2d5,00000000..c38908ca mode 100644,000000..100644 --- a/docs/content/hosting-and-deployment/hosting-on-gitlab.md +++ b/docs/content/hosting-and-deployment/hosting-on-gitlab.md @@@ -1,85 -1,0 +1,84 @@@ +--- +title: Host on GitLab +linktitle: Host on GitLab +description: GitLab makes it incredibly easy to build, deploy, and host your Hugo website via their free GitLab Pages service, which provides native support for Hugo. +date: 2016-06-23 +publishdate: 2016-06-23 - lastmod: 2016-06-23 ++lastmod: 2017-11-16 +categories: [hosting and deployment] +keywords: [hosting,deployment,git,gitlab] +authors: [Riku-Pekka Silvola] +menu: + docs: + parent: "hosting-and-deployment" + weight: 40 +weight: 40 +sections_weight: 40 +draft: false +toc: true +wip: false +aliases: [/tutorials/hosting-on-gitlab/] +--- + +[GitLab](https://gitlab.com/) makes it incredibly easy to build, deploy, and host your Hugo website via their free GitLab Pages service, which provides [native support for Hugo, as well as numerous other static site generators](https://gitlab.com/pages/hugo). + +## Assumptions + +* Working familiarity with Git for version control +* Completion of the Hugo [Quick Start][] +* A [GitLab account](https://gitlab.com/users/sign_in) +* A Hugo website on your local machine that you are ready to publish + +## Create .gitlab-ci.yml + +``` +cd your-hugo-site +``` + +In the root directory of your Hugo site, create a `.gitlab-ci.yml` file. The `.gitlab-ci.yml` configures the GitLab CI on how to build your page. Simply add the content below. + +{{< code file="gitlab-ci.yml" >}} +image: monachus/hugo + - before_script: - - git submodule init - - git submodule update --force ++variables: ++ GIT_SUBMODULE_STRATEGY: recursive + +pages: + script: + - hugo + artifacts: + paths: + - public + only: + - master +{{< /code >}} + +## Push Your Hugo Website to GitLab + +Next, create a new repository on GitLab. It is *not* necessary to make the repository public. In addition, you might want to add `/public` to your .gitignore file, as there is no need to push compiled assets to GitLab or keep your output website in version control. + +``` +# initialize new git repository +git init + +# add /public directory to our .gitignore file +echo "/public" >> .gitignore + +# commit and push code to master branch +git add . +git commit -m "Initial commit" +git remote add origin https://gitlab.com/YourUsername/your-hugo-site.git +git push -u origin master +``` + +## Wait for Your Page to Build + +That's it! You can now follow the CI agent building your page at `https://gitlab.com///pipelines`. + +After the build has passed, your new website is available at `https://.gitlab.io//`. + +## Next Steps + +GitLab supports using custom CNAME's and TLS certificates. For more details on GitLab Pages, see the [GitLab Pages setup documentation](https://about.gitlab.com/2016/04/07/gitlab-pages-setup/). + +[Quick Start]: /getting-started/quick-start/ diff --cc docs/content/hosting-and-deployment/hosting-on-keycdn.md index 748796a3,00000000..78337c13 mode 100644,000000..100644 --- a/docs/content/hosting-and-deployment/hosting-on-keycdn.md +++ b/docs/content/hosting-and-deployment/hosting-on-keycdn.md @@@ -1,90 -1,0 +1,94 @@@ +--- +title: "Hosting on KeyCDN" +date: 2017-09-12 +description: "Accelerate your Hugo site globally with a KeyCDN integration. This tutorial shows you how to setup your static site as a GitLab page behind a KeyCDN pull zone." +categories: [hosting and deployment] +keywords: [keycdn,hosting,deployment,cdn] ++menu: ++ docs: ++ parent: "hosting-and-deployment" ++ weight: 40 +slug: "" +aliases: [] +toc: false +draft: false +--- + +[KeyCDN](https://www.keycdn.com/) provides a multitude of features to help accelerate and secure your Hugo site globally including Brotli compression, Let's Encrypt support, Origin Shield, and more. + +## Assumptions + +- You already have a Hugo page configured +- You have a GitLab account +- You have a KeyCDN account + +## Create a KeyCDN Pull Zone + +The first step will be to login to your KeyCDN account and create a new zone. Name this whatever you like and select the [Pull Zone](https://www.keycdn.com/support/create-a-pull-zone/) option. As for the the origin URL, your site will be running on [GitLab Pages](https://docs.gitlab.com/ee/user/project/pages/getting_started_part_one.html) with a URL of `https://youruser.gitlab.io/reponame/`. Use this as the Origin URL. + +![Screenshot of KeyCDN's pull zone creation page](/images/hosting-and-deployment/hosting-on-keycdn/keycdn-pull-zone.png) + +While the origin location doesn’t exist yet, you will need to use your new Zone URL address (or [Zonealias](https://www.keycdn.com/support/create-a-zonealias/)) in the `.gitlab-ci.yml` file that will be uploaded to your GitLab project. + +Ensure that you use your Zone URL or Zonealias as the `BASEURL` variable in the example below. This will be the user-visible website address. + +## Configure Your .gitlab-ci.yml File + +Your `.gitlab-ci.yml` file should look similar to the example below. Be sure to modify any variables that are specific to your setup. + +``` +image: alpine:latest + +variables: + BASEURL: "https://cipull-7bb7.kxcdn.com/" + HUGO_VERSION: "0.26" + HUGO_CHECKSUM: "67e4ba5ec2a02c8164b6846e30a17cc765b0165a5b183d5e480149baf54e1a50" + KEYCDN_ZONE_ID: "75544" + +before_script: + - apk update + - apk add curl + +pages: + stage: deploy + script: + - apk add git + - git submodule update --init + - curl -sSL https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_${HUGO_VERSION}_Linux-64bit.tar.gz -o /tmp/hugo.tar.gz + - echo "${HUGO_CHECKSUM} /tmp/hugo.tar.gz" | sha256sum -c + - tar xf /tmp/hugo.tar.gz hugo -C /tmp/ && cp /tmp/hugo /usr/bin + - hugo --baseURL ${BASEURL} + - curl "https://api.keycdn.com/zones/purge/${KEYCDN_ZONE_ID}.json" -u "${KEYCDN_API_KEY}:" + artifacts: + paths: + - public + only: + - master + +``` +Using this integration method, you will have to specify the Zone ID and your [KeyCDN API](https://www.keycdn.com/api) key as secret variables. To do this, navigate to the top-left menu bar in GitLab and select Projects. Then, select your project and click on the Settings page. Finally, select Pipelines from the sub-menu and scroll down to the Secret Variable section. + +The Secret Variable for your Zone ID should look similar to: + +![Screenshot of setting the Zone ID secret variable](/images/hosting-and-deployment/hosting-on-keycdn/secret-zone-id.png) + +While the Secret Variable for your API Key will look similar to: + +![Screenshot of setting the API Key secret variable](/images/hosting-and-deployment/hosting-on-keycdn/secret-api-key.png) + +The Zone ID and API key are used to purge your zone – it’s not strictly needed but otherwise, the CDN might deliver older versions of your assets for quite a while. + +## Push Your Changes to GitLab + +Now it’s time to push the newly created repository to GitLab: + +``` +git remote add origin git@gitlab.com:youruser/ciexample.git +git push -u origin master +``` + +You can watch the progress and CI job output in your Gitlab project under “Pipelines”. + +After verifying your CI job ran without issues, first check that your GitLab page shows up under `https://youruser.gitlab.io/reponame/` (it might look broken depending on your browser settings as all links point to your KeyCDN zone – don’t worry about that) and then by heading to whatever Zonealias / Zone URL you defined. + +To learn more about Hugo hosting options with KeyCDN, check out the complete [Hugo hosting with KeyCDN integration guide](https://www.keycdn.com/support/hugo-hosting/). diff --cc docs/content/news/0.31-relnotes-ready.md index ee412c04,00000000..138ecc08 mode 100644,000000..100644 --- a/docs/content/news/0.31-relnotes-ready.md +++ b/docs/content/news/0.31-relnotes-ready.md @@@ -1,78 -1,0 +1,80 @@@ + +--- +date: 2017-11-20 - title: "0.31" - description: "0.31" - slug: "0.31" ++title: "Hugo 0.31: Language Multihost Edition!" ++description: "Hugo 0.31: Multihost, smart union static dirs, and more ..." ++slug: "0.31-relnotes" +categories: ["Releases"] ++images: ++- images/blog/hugo-31-poster.png +--- + + Hugo `0.31` is the **Language Multihost Edition!** + - > eSoliaThe Multihost feature is sponsored by [eSolia](https://esolia.com/), [@rickcogley](https://github.com/rickcogley)'s company. ++> eSoliaThe Multihost feature is sponsored by [eSolia](https://esolia.com/), [@rickcogley](https://github.com/rickcogley)'s company. + +[Multihost](https://gohugo.io/content-management/multilingual/#configure-multilingual-multihost) means that you can have a **`baseURL` per language**, for example, `https://no.example.com` and `https://en.example.com`. This is seamlessly integrated, and the built-in web server with live reload and `navigateToChanged` etc. just works. A related enhancement in this release is the support for **as many static dirs as you need**, with intelligent language overrides, forming a big union file system. Add to that several other language related fixes and enhancements, it is safe to say that this is the version you want for multilingual Hugo sites! + +This release represents **44 contributions by 7 contributors** to the main Hugo code base. +[@bep](https://github.com/bep) leads the Hugo development with a significant amount of contributions, but also a big shoutout to [@kaushalmodi](https://github.com/kaushalmodi), [@natefinch](https://github.com/natefinch), and [@betaveros](https://github.com/betaveros) for their ongoing contributions. +And as always a big thanks to [@digitalcraftsman](https://github.com/digitalcraftsman) for his relentless work on keeping the documentation and the themes site in pristine condition. + +Many have also been busy writing and fixing the documentation in [hugoDocs](https://github.com/gohugoio/hugoDocs), +which has received **13 contributions by 9 contributors**. A special thanks to [@oncletom](https://github.com/oncletom), [@kaushalmodi](https://github.com/kaushalmodi), [@XhmikosR](https://github.com/XhmikosR), and [@digitalcraftsman](https://github.com/digitalcraftsman) for their work on the documentation site. + + +Hugo now has: + +* 21105+ [stars](https://github.com/gohugoio/hugo/stargazers) +* 455+ [contributors](https://github.com/gohugoio/hugo/graphs/contributors) +* 184+ [themes](http://themes.gohugo.io/) + +## Notes + +* For mapping of translated content, Hugo now considers the full path of the content file, which makes it possible with translation of duplicate content filenames such as `index.md`. A specific translation key can be specified with the new `translationKey` front matter variable. See [#2699](https://github.com/gohugoio/hugo/issues/2699). + + +## Enhancements + +### Language related + +* Support unknown language codes [23ba779f](https://github.com/gohugoio/hugo/commit/23ba779fab90ce45cddd68b4f49a2515ce6d4878) [@bep](https://github.com/bep) [#3564](https://github.com/gohugoio/hugo/issues/3564) +* Fix `.IsTranslated` with identical filenames [b3daa1f4](https://github.com/gohugoio/hugo/commit/b3daa1f4bf1b84bcc5da028257ba609be74e3ecc) [@bep](https://github.com/bep) [#2699](https://github.com/gohugoio/hugo/issues/2699) +* Fall back to unstranslated base template [0a81a6b4](https://github.com/gohugoio/hugo/commit/0a81a6b4bae3de53aa9c179b855c671a2d30eec7) [@bep](https://github.com/bep) [#3893](https://github.com/gohugoio/hugo/issues/3893) +* Add support for multiple static dirs [60dfb9a6](https://github.com/gohugoio/hugo/commit/60dfb9a6e076200ab3ca3fd30e34bb3c14e0a893) [@bep](https://github.com/bep) [#36](https://github.com/gohugoio/hugo/issues/36)[#4027](https://github.com/gohugoio/hugo/issues/4027) +* Add multilingual multihost support [2e046576](https://github.com/gohugoio/hugo/commit/2e0465764b5dacc511b977b1c9aa07324ad0ee9c) [@bep](https://github.com/bep) [#4027](https://github.com/gohugoio/hugo/issues/4027) + +### Templates + +* Refactor `Mod` with `cast` [76dc811c](https://github.com/gohugoio/hugo/commit/76dc811c6539b2ed8b4d3b22693e5088b9f6ecfe) [@artem-sidorenko](https://github.com/artem-sidorenko) +* Add support for height argument to figure shortcode [488631fe](https://github.com/gohugoio/hugo/commit/488631fe0abc3667355345c7eb98ba7a2204deb5) [@kaushalmodi](https://github.com/kaushalmodi) [#4014](https://github.com/gohugoio/hugo/issues/4014) + +### Core + +* Use ms precision for static change logging [bb048d81](https://github.com/gohugoio/hugo/commit/bb048d811d3977adb10656335cd339cd8c945a25) [@bep](https://github.com/bep) +* Update Chroma to get the latest SASS lexer [b32ffed6](https://github.com/gohugoio/hugo/commit/b32ffed6abc67646cad89e163846f3ffef29cec8) [@bep](https://github.com/bep) [#4069](https://github.com/gohugoio/hugo/issues/4069) +* Bump to Go 1.9.2 [9299a16c](https://github.com/gohugoio/hugo/commit/9299a16c9952a284d3ac3f31d2662f1812f77768) [@bep](https://github.com/bep) [#4064](https://github.com/gohugoio/hugo/issues/4064) +* Update Travis and snapcraft to Go 1.9.2 [77cbd001](https://github.com/gohugoio/hugo/commit/77cbd001ff6b2e0aaa48566ef2af49ca68e19af9) [@bep](https://github.com/bep) [#4064](https://github.com/gohugoio/hugo/issues/4064) +* Handle Taxonomy permalinks [d9a78b61](https://github.com/gohugoio/hugo/commit/d9a78b61adefe8e1803529f4774185874af85148) [@betaveros](https://github.com/betaveros) [#1208](https://github.com/gohugoio/hugo/issues/1208) + + +### Other + +* Support Fast Render mode with sub-path in baseURL [31641033](https://github.com/gohugoio/hugo/commit/3164103310fbca1211cfa9ce4a5eb7437854b6ad) [@bep](https://github.com/bep) [#3981](https://github.com/gohugoio/hugo/issues/3981) +* Simplify Site benchmarks [c3c10f2c](https://github.com/gohugoio/hugo/commit/c3c10f2c7ce4ee11186f51161943efc8b37a28c9) [@bep](https://github.com/bep) +* Replace `make` with `mage` to build Hugo [#3969](https://github.com/gohugoio/hugo/issues/3969) +* Convert to `dep` as dependency/vendor manager for Hugo [#3988](https://github.com/gohugoio/hugo/issues/3988) +* Pre-allocate some slices [a9be687b](https://github.com/gohugoio/hugo/commit/a9be687b81df01c7343f78f0d3760042f467baa4) [@bep](https://github.com/bep) + +## Fixes + +### Templates + +* Make sure only one instance of a cached partial is rendered [#4086](https://github.com/gohugoio/hugo/issues/4086) + +### Other + +* Fix broken shortcodes for `Ace` and `Amber` [503ca6de](https://github.com/gohugoio/hugo/commit/503ca6de6ceb0b4af533f9efeff917d6f3871278) [@bep](https://github.com/bep) [#4051](https://github.com/gohugoio/hugo/issues/4051) +* Fix error handling in `mage` build [c9c19d79](https://github.com/gohugoio/hugo/commit/c9c19d794537cf76ff281788c3d6cf5f2beac54d) [@natefinch](https://github.com/natefinch) +* Fix `hugo -w` [fa53b13c](https://github.com/gohugoio/hugo/commit/fa53b13ca0ffb1db6ed20f5353661d3f8a5fd455) [@bep](https://github.com/bep) [#3980](https://github.com/gohugoio/hugo/issues/3980) + diff --cc docs/content/news/0.31.1-relnotes-ready.md index 3095a066,00000000..9c6be628 mode 100644,000000..100644 --- a/docs/content/news/0.31.1-relnotes-ready.md +++ b/docs/content/news/0.31.1-relnotes-ready.md @@@ -1,22 -1,0 +1,20 @@@ + +--- +date: 2017-11-27 - title: "0.31.1" - description: "0.31.1" ++title: "Hugo 0.31.1: One Bugfix!" ++description: "Fixes broken `--appendPort=false`." +slug: "0.31.1" +categories: ["Releases"] +images: +- images/blog/hugo-bug-poster.png + +--- - + - +This is a bug-fix release with one important bug fix: + +* Fix broken `--appendPort=false` [8afd7d9c](https://github.com/gohugoio/hugo/commit/8afd7d9ceb0d168300e3399c6e87a355a88c9a28) [@bep](https://github.com/bep) [#4111](https://github.com/gohugoio/hugo/issues/4111) + + + + + diff --cc docs/content/readfiles/bfconfig.md index 97176095,00000000..5388694d mode 100644,000000..100644 --- a/docs/content/readfiles/bfconfig.md +++ b/docs/content/readfiles/bfconfig.md @@@ -1,182 -1,0 +1,182 @@@ +## Blackfriday Options + +`taskLists` +: default: **`true`**
    + Blackfriday flag:
    + Purpose: `false` turns off GitHub-style automatic task/TODO list generation. + +`smartypants` +: default: **`true`**
    + Blackfriday flag: **`HTML_USE_SMARTYPANTS`**
    + Purpose: `false` disables smart punctuation substitutions, including smart quotes, smart dashes, smart fractions, etc. If `true`, it may be fine-tuned with the `angledQuotes`, `fractions`, `smartDashes`, and `latexDashes` flags (see below). + +`smartypantsQuotesNBSP` +: default: **`false`**
    + Blackfriday flag: **`HTML_SMARTYPANTS_QUOTES_NBSP`**
    + Purpose: `true` enables French style Guillemets with non-breaking space inside the quotes. + +`angledQuotes` +: default: **`false`**
    + Blackfriday flag: **`HTML_SMARTYPANTS_ANGLED_QUOTES`**
    + Purpose: `true` enables smart, angled double quotes. Example: "Hugo" renders to «Hugo» instead of “Hugo”. + +`fractions` +: default: **`true`**
    + Blackfriday flag: **`HTML_SMARTYPANTS_FRACTIONS`**
    + Purpose: false disables smart fractions.
    + Example: `5/12` renders to 5⁄12(<sup>5</sup>&frasl;<sub>12</sub>).
    Caveat: Even with fractions = false, Blackfriday still converts `1/2`, `1/4`, and `3/4` respectively to ½ (&frac12;), ¼ (&frac14;) and ¾ (&frac34;), but only these three. + +`smartDashes` +: default: **`true`**
    + Blackfriday flag: **`HTML_SMARTY_DASHES`**
    + Purpose: `false` disables smart dashes; i.e., the conversion of multiple hyphens into an en-dash or em-dash. If `true`, its behavior can be modified with the `latexDashes` flag below. + +`latexDashes` +: default: **`true`**
    + Blackfriday flag: **`HTML_SMARTYPANTS_LATEX_DASHES`**
    + Purpose: `false` disables LaTeX-style smart dashes and selects conventional smart dashes. Assuming `smartDashes`:
    + If `true`, `--` is translated into – (`–`), whereas `---` is translated into — (`—`).
    + However, *spaced* single hyphen between two words is translated into an en dash— e.g., "`12 June - 3 July`" becomes `12 June – 3 July` upon rendering. + +`hrefTargetBlank` +: default: **`false`**
    + Blackfriday flag: **`HTML_HREF_TARGET_BLANK`**
    + Purpose: `true` opens external links in a new window or tab. + +`plainIDAnchors` +: default **`true`**
    + Blackfriday flag: **`FootnoteAnchorPrefix` and `HeaderIDSuffix`**
    + Purpose: `true` renders any heading and footnote IDs without the document ID.
    + Example: renders `#my-heading` instead of `#my-heading:bec3ed8ba720b970` + +`extensions` +: default: **`[]`**
    + Purpose: Enable one or more Blackfriday's Markdown extensions (**`EXTENSION_*`**).
    - Example: Include `hardLineBreak` in the list to enable Blackfriday's `EXTENSION_HARD_LINK_BREAK`.
    ++ Example: Include `hardLineBreak` in the list to enable Blackfriday's `EXTENSION_HARD_LINE_BREAK`.
    + *See [Blackfriday extensions](#blackfriday-extensions) section for information on all extensions.* + +`extensionsmask` +: default: **`[]`**
    + Purpose: Disable one or more of Blackfriday's Markdown extensions (**`EXTENSION_*`**).
    + Example: Include `autoHeaderIds` as `false` in the list to disable Blackfriday's `EXTENSION_AUTO_HEADER_IDS`.
    + *See [Blackfriday extensions](#blackfriday-extensions) section for information on all extensions.* + +## Blackfriday extensions + +`noIntraEmphasis` +: default: *enabled*
    + Purpose: The "\_" character is commonly used inside words when discussing + code, so having Markdown interpret it as an emphasis command is usually the + wrong thing. When enabled, Blackfriday lets you treat all emphasis markers + as normal characters when they occur inside a word. + +`tables` +: default: *enabled*
    + Purpose: When enabled, tables can be created by drawing them in the input + using the below syntax: + Example: + + Name | Age + --------|------ + Bob | 27 + Alice | 23 + +`fencedCode` +: default: *enabled*
    + Purpose: When enabled, in addition to the normal 4-space indentation to mark + code blocks, you can explicitly mark them and supply a language (to make + syntax highlighting simple). + + You can use 3 or more backticks to mark the beginning of the block, and the + same number to mark the end of the block. + + Example: + + ```md + # Heading Level 1 + Some test + ## Heading Level 2 + Some more test + ``` + +`autolink` +: default: *enabled*
    + Purpose: When enabled, URLs that have not been explicitly marked as links + will be converted into links. + +`strikethrough` +: default: *enabled*
    + Purpose: When enabled, text wrapped with two tildes will be crossed out.
    + Example: `~~crossed-out~~` + +`laxHtmlBlocks` +: default: *disabled*
    + Purpose: When enabled, loosen up HTML block parsing rules. + +`spaceHeaders` +: default: *enabled*
    + Purpose: When enabled, be strict about prefix header rules. + +`hardLineBreak` +: default: *disabled*
    + Purpose: When enabled, newlines in the input translate into line breaks in + the output. + + +`tabSizeEight` +: default: *disabled*
    + Purpose: When enabled, expand tabs to eight spaces instead of four. + +`footnotes` +: default: *enabled*
    + Purpose: When enabled, Pandoc-style footnotes will be supported. The + footnote marker in the text that will become a superscript text; the + footnote definition will be placed in a list of footnotes at the end of the + document.
    + Example: + + This is a footnote.[^1] + + [^1]: the footnote text. + +`noEmptyLineBeforeBlock` +: default: *disabled*
    + Purpose: When enabled, no need to insert an empty line to start a (code, + quote, ordered list, unordered list) block. + + +`headerIds` +: default: *enabled*
    + Purpose: When enabled, allow specifying header IDs with `{#id}`. + +`titleblock` +: default: *disabled*
    + Purpose: When enabled, support [Pandoc-style title blocks][1]. + +`autoHeaderIds` +: default: *enabled*
    + Purpose: When enabled, auto-create the header ID's from the headline text. + +`backslashLineBreak` +: default: *enabled*
    + Purpose: When enabled, translate trailing backslashes into line breaks. + +`definitionLists` +: default: *enabled*
    + Purpose: When enabled, a simple definition list is made of a single-line + term followed by a colon and the definition for that term.
    + Example: + + Cat + : Fluffy animal everyone likes + + Internet + : Vector of transmission for pictures of cats + + Terms must be separated from the previous definition by a blank line. + +`joinLines` +: default: *enabled*
    + Purpose: When enabled, delete newlines and join the lines. + +[1]: http://pandoc.org/MANUAL.html#extension-pandoc_title_block diff --cc docs/content/readfiles/sectionvars.md index 00000000,00000000..c0756e7d new file mode 100644 --- /dev/null +++ b/docs/content/readfiles/sectionvars.md @@@ -1,0 -1,0 +1,20 @@@ ++.CurrentSection ++: the page's current section. The value can be the page itself if it is a section or the homepage. ++ ++.InSection $anotherPage ++: whether the given page is in the current section. Note that this will always return false for pages that are not either regular, home or section pages. ++ ++.IsAncestor $anotherPage ++: whether the current page is an ancestor of the given page. Note that this method is not relevant for taxonomy lists and taxonomy terms pages. ++ ++.IsDescendant $anotherPage ++: whether the current page is a descendant of the given page. Note that this method is not relevant for taxonomy lists and taxonomy terms pages. ++ ++.Parent ++: a section's parent section or a page's section. ++ ++.Section ++: the [section](/content-management/sections/) this content belongs to. **Note:** For nested sections, this is the first path element in the directory, for example, `/blog/funny/mypost/ => blog`. ++ ++.Sections ++: the [sections](/content-management/sections/) below this content. diff --cc docs/content/templates/introduction.md index 26802a7f,00000000..0f4e8e3d mode 100644,000000..100644 --- a/docs/content/templates/introduction.md +++ b/docs/content/templates/introduction.md @@@ -1,488 -1,0 +1,488 @@@ +--- +title: Introduction to Hugo Templating +linktitle: Introduction +description: Hugo uses Go's `html/template` and `text/template` libraries as the basis for the templating. +godocref: https://golang.org/pkg/html/template/ +date: 2017-02-01 +publishdate: 2017-02-01 +lastmod: 2017-02-25 +categories: [templates,fundamentals] +keywords: [go] +menu: + docs: + parent: "templates" + weight: 10 +weight: 10 +sections_weight: 10 +draft: false +aliases: [/templates/introduction/,/layouts/introduction/,/layout/introduction/, /templates/go-templates/] +toc: true +--- + +{{% note %}} +The following is only a primer on Go templates. For an in-depth look into Go templates, check the official [Go docs](http://golang.org/pkg/html/template/). +{{% /note %}} + +Go templates provide an extremely simple template language that adheres to the belief that only the most basic of logic belongs in the template or view layer. + +{{< youtube gnJbPO-GFIw >}} + +## Basic Syntax + +Golang templates are HTML files with the addition of [variables][variables] and [functions][functions]. Golang template variables and functions are accessible within `{{ }}`. + +### Access a Predefined Variable + +``` +{{ foo }} +``` + +Parameters for functions are separated using spaces. The following example calls the `add` function with inputs of `1` and `2`: + +``` +{{ add 1 2 }} +``` + +#### Methods and Fields are Accessed via dot Notation + +Accessing the Page Parameter `bar` defined in a piece of content's [front matter][]. + +``` +{{ .Params.bar }} +``` + +#### Parentheses Can be Used to Group Items Together + +``` +{{ if or (isset .Params "alt") (isset .Params "caption") }} Caption {{ end }} +``` + +## Variables + +Each Go template gets a data object. In Hugo, each template is passed a `Page`. See [variables][] for more information. + +This is how you access a `Page` variable from a template: + +``` +{{ .Title }} +``` + +Values can also be stored in custom variables and referenced later: + +``` +{{ $address := "123 Main St."}} +{{ $address }} +``` + +{{% warning %}} +Variables defined inside `if` conditionals and similar are not visible on the outside. See [https://github.com/golang/go/issues/10608](https://github.com/golang/go/issues/10608). + +Hugo has created a workaround for this issue in [Scratch](/functions/scratch). + +{{% /warning %}} + +## Functions + +Go templates only ship with a few basic functions but also provide a mechanism for applications to extend the original set. + +[Hugo template functions][functions] provide additional functionality specific to building websites. Functions are called by using their name followed by the required parameters separated by spaces. Template functions cannot be added without recompiling Hugo. + +### Example 1: Adding Numbers + +``` +{{ add 1 2 }} +=> 3 +``` + +### Example 2: Comparing Numbers + +``` +{{ lt 1 2 }} +=> true (i.e., since 1 is less than 2) +``` + - Note that both examples make us of Go template's [math functions][]. ++Note that both examples make use of Go template's [math functions][]. + +{{% note "Additional Boolean Operators" %}} +There are more boolean operators than those listed in the Hugo docs in the [Golang template documentation](http://golang.org/pkg/text/template/#hdr-Functions). +{{% /note %}} + +## Includes + +When including another template, you will pass to it the data it will be +able to access. To pass along the current context, please remember to +include a trailing dot. The templates location will always be starting at +the `/layouts/` directory within Hugo. + +### Template and Partial Examples + +``` +{{ template "partials/header.html" . }} +``` + +Starting with Hugo v0.12, you may also use the `partial` call +for [partial templates][partials]: + +``` +{{ partial "header.html" . }} +``` + +## Logic + +Go templates provide the most basic iteration and conditional logic. + +### Iteration + +Just like in Go, the Go templates make heavy use of `range` to iterate over +a map, array, or slice. The following are different examples of how to use +range. + +#### Example 1: Using Context + +``` +{{ range array }} + {{ . }} +{{ end }} +``` + +#### Example 2: Declaring Value => Variable name + +``` +{{range $element := array}} + {{ $element }} +{{ end }} +``` + +#### Example 3: Declaring Key-Value Variable Name + +``` +{{range $index, $element := array}} + {{ $index }} + {{ $element }} +{{ end }} +``` + +### Conditionals + +`if`, `else`, `with`, `or`, and `and` provide the framework for handling conditional logic in Go Templates. Like `range`, each statement is closed with an `{{end}}`. + +Go Templates treat the following values as false: + +* false +* 0 +* any zero-length array, slice, map, or string + +#### Example 1: `if` + +``` +{{ if isset .Params "title" }}

    {{ index .Params "title" }}

    {{ end }} +``` + +#### Example 2: `if` … `else` + +``` +{{ if isset .Params "alt" }} + {{ index .Params "alt" }} +{{else}} + {{ index .Params "caption" }} +{{ end }} +``` + +#### Example 3: `and` & `or` + +``` +{{ if and (or (isset .Params "title") (isset .Params "caption")) (isset .Params "attr")}} +``` + +#### Example 4: `with` + +An alternative way of writing "`if`" and then referencing the same value +is to use "`with`" instead. `with` rebinds the context `.` within its scope +and skips the block if the variable is absent. + +The first example above could be simplified as: + +``` +{{ with .Params.title }}

    {{ . }}

    {{ end }} +``` + +#### Example 5: `if` … `else if` + +``` +{{ if isset .Params "alt" }} + {{ index .Params "alt" }} +{{ else if isset .Params "caption" }} + {{ index .Params "caption" }} +{{ end }} +``` + +## Pipes + +One of the most powerful components of Go templates is the ability to stack actions one after another. This is done by using pipes. Borrowed from Unix pipes, the concept is simple: each pipeline's output becomes the input of the following pipe. + +Because of the very simple syntax of Go templates, the pipe is essential to being able to chain together function calls. One limitation of the pipes is that they can only work with a single value and that value becomes the last parameter of the next pipeline. + +A few simple examples should help convey how to use the pipe. + +### Example 1: `shuffle` + +The following two examples are functionally the same: + +``` +{{ shuffle (seq 1 5) }} +``` + + +``` +{{ (seq 1 5) | shuffle }} +``` + +### Example 2: `index` + +The following accesses the page parameter called "disqus_url" and escapes the HTML. This example also uses the [`index` function][index], which is built into Go templates: + +``` +{{ index .Params "disqus_url" | html }} +``` + +### Example 3: `or` with `isset` + +``` +{{ if or (or (isset .Params "title") (isset .Params "caption")) (isset .Params "attr") }} +Stuff Here +{{ end }} +``` + +Could be rewritten as + +``` +{{ if isset .Params "caption" | or isset .Params "title" | or isset .Params "attr" }} +Stuff Here +{{ end }} +``` + +### Example 4: Internet Explorer Conditional Comments + +By default, Go Templates remove HTML comments from output. This has the unfortunate side effect of removing Internet Explorer conditional comments. As a workaround, use something like this: + +``` +{{ "" | safeHTML }} +``` + +Alternatively, you can use the backtick (`` ` ``) to quote the IE conditional comments, avoiding the tedious task of escaping every double quotes (`"`) inside, as demonstrated in the [examples](http://golang.org/pkg/text/template/#hdr-Examples) in the Go text/template documentation: + +``` +{{ `` | safeHTML }} +``` + +## Context (aka "the dot") + +The most easily overlooked concept to understand about Go templates is that `{{ . }}` always refers to the current context. In the top level of your template, this will be the data set made available to it. Inside of an iteration, however, it will have the value of the current item in the loop; i.e., `{{ . }}` will no longer refer to the data available to the entire page. If you need to access page-level data (e.g., page params set in front matter) from within the loop, you will likely want to do one of the following: + +### 1. Define a Variable Independent of Context + +The following shows how to define a variable independent of the context. + +{{< code file="tags-range-with-page-variable.html" >}} +{{ $title := .Site.Title }} +
      +{{ range .Params.tags }} +
    • + {{ . }} + - {{ $title }} +
      • +{{ end }} +
    +{{< /code >}} + +{{% note %}} +Notice how once we have entered the loop (i.e. `range`), the value of `{{ . }}` has changed. We have defined a variable outside of the loop (`{{$title}}`) that we've assigned a value so that we have access to the value from within the loop as well. +{{% /note %}} + +### 2. Use `$.` to Access the Global Context + +`$` has special significance in your templates. `$` is set to the starting value of `.` ("the dot") by default. This is a [documented feature of Go text/template][dotdoc]. This means you have access to the global context from anywhere. Here is an equivalent example of the preceding code block but now using `$` to grab `.Site.Title` from the global context: + +{{< code file="range-through-tags-w-global.html" >}} +
      +{{ range .Params.tags }} +
    • + {{ . }} + - {{ $.Site.Title }} +
      • +{{ end }} +
    +{{< /code >}} + +{{% warning "Don't Redefine the Dot" %}} +The built-in magic of `$` would cease to work if someone were to mischievously redefine the special character; e.g. `{{ $ := .Site }}`. *Don't do it.* You may, of course, recover from this mischief by using `{{ $ := . }}` in a global context to reset `$` to its default value. +{{% /warning %}} + +## Whitespace + +Go 1.6 includes the ability to trim the whitespace from either side of a Go tag by including a hyphen (`-`) and space immediately beside the corresponding `{{` or `}}` delimiter. + +For instance, the following Go template will include the newlines and horizontal tab in its HTML output: + +``` +
    + {{ .Title }} +
    +``` + +Which will output: + +``` +
    + Hello, World! +
    +``` + +Leveraging the `-` in the following example will remove the extra white space surrounding the `.Title` variable and remove the newline: + +``` +
    + {{- .Title -}} +
    +``` + +Which then outputs: + +``` +
    Hello, World!
    +``` + +Go considers the following characters whitespace: + +* space +* horizontal tab +* carriage return +* newline + +## Hugo Parameters + +Hugo provides the option of passing values to your template layer through your [site configuration][config] (i.e. for site-wide values) or through the metadata of each specific piece of content (i.e. the [front matter][]). You can define any values of any type and use them however you want in your templates, as long as the values are supported by the front matter format specified via `metaDataFormat` in your configuration file. + +## Use Content (`Page`) Parameters + +You can provide variables to be used by templates in individual content's [front matter][]. + +An example of this is used in the Hugo docs. Most of the pages benefit from having the table of contents provided, but sometimes the table of contents doesn't make a lot of sense. We've defined a `notoc` variable in our front matter that will prevent a table of contents from rendering when specifically set to `true`. + +Here is the example front matter: + +``` +--- +title: Roadmap +lastmod: 2017-03-05 +date: 2013-11-18 +notoc: true +--- +``` + +Here is an example of corresponding code that could be used inside a `toc.html` [partial template][partials]: + +{{< code file="layouts/partials/toc.html" download="toc.html" >}} +{{ if not .Params.notoc }} + + +{{end}} +{{< /code >}} + +We want the *default* behavior to be for pages to include a TOC unless otherwise specified. This template checks to make sure that the `notoc:` field in this page's front matter is not `true`. + +## Use Site Configuration Parameters + +You can arbitrarily define as many site-level parameters as you want in your [site's configuration file][config]. These parameters are globally available in your templates. + +For instance, you might declare the following: + +{{< code file="config.yaml" >}} +params: + copyrighthtml: "Copyright © 2017 John Doe. All Rights Reserved." + twitteruser: "spf13" + sidebarrecentlimit: 5 +{{< /code >}} + +Within a footer layout, you might then declare a `