From: Bjørn Erik Pedersen Date: Mon, 7 Sep 2020 19:37:51 +0000 (+0200) Subject: Merge commit '7d7771b673e5949f554515a2c236b23192c765c8' X-Git-Tag: v0.75.0~52 X-Git-Url: http://git.maquefel.me/?a=commitdiff_plain;h=b9e4f5898b1f8c5cb3b5e6525d1381ed3c9c5904;p=brevno-suite%2Fhugo Merge commit '7d7771b673e5949f554515a2c236b23192c765c8' --- b9e4f5898b1f8c5cb3b5e6525d1381ed3c9c5904 diff --cc docs/content/en/about/features.md index 9c8fac4f,00000000..11f9f65b mode 100644,000000..100644 --- a/docs/content/en/about/features.md +++ b/docs/content/en/about/features.md @@@ -1,87 -1,0 +1,85 @@@ +--- +title: Hugo Features +linktitle: Hugo Features +description: Hugo boasts blistering speed, robust content management, and a powerful templating language making it a great fit for all kinds of static websites. +date: 2017-02-01 +publishdate: 2017-02-01 +lastmod: 2017-02-01 +menu: + docs: + parent: "about" + weight: 20 +weight: 20 +sections_weight: 20 +draft: false +toc: true +--- + +## General + +* [Extremely fast][] build times (< 1 ms per page) +* Completely cross platform, with [easy installation][install] on macOS, Linux, Windows, and more +* Renders changes on the fly with [LiveReload][] as you develop +* [Powerful theming][] +* [Host your site anywhere][hostanywhere] + +## Organization + +* Straightforward [organization for your projects][], including website sections +* Customizable [URLs][] +* Support for configurable [taxonomies][], including categories and tags +* [Sort content][] as you desire through powerful template [functions][] +* Automatic [table of contents][] generation +* [Dynamic menu][] creation +* [Pretty URLs][] support +* [Permalink][] pattern support +* Redirects via [aliases][] + +## Content + +* Native Markdown and Emacs Org-Mode support, as well as other languages via *external helpers* (see [supported formats][]) +* TOML, YAML, and JSON metadata support in [front matter][] +* Customizable [homepage][] +* Multiple [content types][] +* Automatic and user defined [content summaries][] +* [Shortcodes][] to enable rich content inside of Markdown +* ["Minutes to Read"][pagevars] functionality +* ["WordCount"][pagevars] functionality + +## Additional Features + +* Integrated [Disqus][] comment support +* Integrated [Google Analytics][] support +* Automatic [RSS][] creation - * Support for [Go][], [Amber], and [Ace][] HTML templates ++* Support for [Go][] HTML templates +* [Syntax highlighting][] powered by [Chroma][] + + - [Ace]: /templates/alternatives/ +[aliases]: /content-management/urls/#aliases - [Amber]: https://github.com/eknkc/amber +[Chroma]: https://github.com/alecthomas/chroma +[content summaries]: /content-management/summaries/ +[content types]: /content-management/types/ +[Disqus]: https://disqus.com/ +[Dynamic menu]: /templates/menus/ +[Extremely fast]: https://github.com/bep/hugo-benchmark +[front matter]: /content-management/front-matter/ +[functions]: /functions/ +[Go]: https://golang.org/pkg/html/template/ +[Google Analytics]: https://google-analytics.com/ +[homepage]: /templates/homepage/ +[hostanywhere]: /hosting-and-deployment/ +[install]: /getting-started/installing/ +[LiveReload]: /getting-started/usage/ +[organization for your projects]: /getting-started/directory-structure/ +[pagevars]: /variables/page/ +[Permalink]: /content-management/urls/#permalinks +[Powerful theming]: /themes/ +[Pretty URLs]: /content-management/urls/ +[RSS]: /templates/rss/ +[Shortcodes]: /content-management/shortcodes/ +[sort content]: /templates/ +[supported formats]: /content-management/formats/ +[Syntax highlighting]: /tools/syntax-highlighting/ +[table of contents]: /content-management/toc/ +[taxonomies]: /content-management/taxonomies/ +[URLs]: /content-management/urls/ diff --cc docs/content/en/content-management/cross-references.md index 21a73b86,00000000..9570a8fa mode 100644,000000..100644 --- a/docs/content/en/content-management/cross-references.md +++ b/docs/content/en/content-management/cross-references.md @@@ -1,100 -1,0 +1,129 @@@ +--- +title: Links and Cross References +description: Shortcodes for creating links to documents. +date: 2017-02-01 +publishdate: 2017-02-01 +lastmod: 2017-03-31 +categories: [content management] +keywords: ["cross references","references", "anchors", "urls"] +menu: + docs: + parent: "content-management" + weight: 100 +weight: 100 #rem +aliases: [/extras/crossreferences/] +toc: true +--- + - - The `ref` and `relref` shortcode resolves the absolute or relative permalink given a path to a document. ++The `ref` and `relref` shortcodes display the absolute and relative permalinks to a document, respectively. + +## Use `ref` and `relref` + +```go-html-template ++{{}} ++{{}} +{{}} - {{}} +{{}} ++{{}} +{{}} +{{}} ++{{}} +{{}} +{{}} - {{}} ++{{}} ++``` ++ ++To generate a hyperlink using `ref` or `relref` in markdown: ++ ++```md ++[About]({{}} "About Us") +``` + - The single parameter to `ref` is a string with a content `documentname` (e.g., `about.md`) with or without an appended in-document `anchor` (`#who`) without spaces. Hugo is flexible in how we search for documents, so the file suffix may be omitted. ++The `ref` and `relref` shortcodes require a single parameter: the path to a content document, with or without a file extension, with or without an anchor. + - **Paths without a leading `/` will first be tried resolved relative to the current page.** ++**Paths without a leading `/` are first resolved relative to the current page, then to the remainder of the site. + - You will get an error if your document could not be uniquely resolved. The error behaviour can be configured, see below. ++Hugo emits an error or warning if a document cannot be uniquely resolved. The error behavior is configurable; see below. + +### Link to another language version + - Link to another language version of a document, you need to use this syntax: ++To link to another language version of a document, use this syntax: + +```go-html-template +{{}} +``` + +### Get another Output Format + - To link to a given Output Format of a document, you can use this syntax: ++To link to another Output Format of a document, use this syntax: + +```go-html-template +{{}} +``` + - ### Anchors ++### Heading IDs + - When an `anchor` is provided by itself, the current page’s unique identifier will be appended; when an `anchor` is provided appended to `documentname`, the found page's unique identifier will be appended: ++When using Markdown document types, Hugo generates element IDs for every heading on a page. For example: + - ```go-html-template - {{}} => #anchors:9decaf7 ++```md ++## Reference +``` + - The above examples render as follows for this very page as well as a reference to the "Content" heading in the Hugo docs features pageyoursite ++produces this HTML: + - ```go-html-template - {{}} => #who:9decaf7 - {{}} => /blog/post/#who:badcafe ++```html ++

Reference

+``` + - More information about document unique identifiers and headings can be found [below]({{< ref "#hugo-heading-anchors" >}}). ++Get the permalink to a heading by appending the ID to the path when using the `ref` or `relref` shortcodes: + - ## Hugo Heading Anchors ++```md ++{{}} ++{{}} ++``` + - When using Markdown document types, Hugo generates heading anchors automatically. The generated anchor for this section is `hugo-heading-anchors`. Because the heading anchors are generated automatically, Hugo takes some effort to ensure that heading anchors are unique both inside a document and across the entire site. ++Generate a custom heading ID by including an attribute. For example: + - Ensuring heading uniqueness across the site is accomplished with a unique identifier for each document based on its path. Unless a document is renamed or moved between sections *in the filesystem*, the unique identifier for the document will not change: `blog/post.md` will always have a unique identifier of `81df004c333b392d34a49fd3a91ba720`. ++```md ++## Reference A {#foo} ++## Reference B {id="bar"} ++``` + - `ref` and `relref` were added so you can make these reference links without having to know the document’s unique identifier. (The links in document tables of contents are automatically up-to-date with this value.) ++produces this HTML: + ++```html ++

Reference A

++

Reference B

+``` - {{}} - /content-management/cross-references/#hugo-heading-anchors:77cd9ea530577debf4ce0f28c8dca242 ++ ++Hugo will generate unique element IDs if the same heading appears more than once on a page. For example: ++ ++```md ++## Reference ++## Reference ++## Reference ++``` ++ ++produces this HTML: ++ ++```html ++

Reference

++

Reference

++

Reference

+``` + +## Ref and RelRef Configuration + - The behaviour can, since Hugo 0.45, be configured in `config.toml`: ++The behavior can, since Hugo 0.45, be configured in `config.toml`: + +refLinksErrorLevel ("ERROR") +: When using `ref` or `relref` to resolve page links and a link cannot resolved, it will be logged with this log level. Valid values are `ERROR` (default) or `WARNING`. Any `ERROR` will fail the build (`exit -1`). + +refLinksNotFoundURL +: URL to be used as a placeholder when a page reference cannot be found in `ref` or `relref`. Is used as-is. + + +[lists]: /templates/lists/ +[output formats]: /templates/output-formats/ +[shortcode]: /content-management/shortcodes/ +[bfext]: /content-management/formats/#blackfriday-extensions diff --cc docs/content/en/content-management/multilingual.md index ccf794b2,00000000..224f38d7 mode 100644,000000..100644 --- a/docs/content/en/content-management/multilingual.md +++ b/docs/content/en/content-management/multilingual.md @@@ -1,465 -1,0 +1,504 @@@ +--- +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/,/tutorials/create-a-multilingual-site/] +toc: true +--- + +You should define the available languages in a `languages` section in your site configuration. + +> Also See [Hugo Multilingual Part 1: Content translation](https://regisphilibert.com/blog/2018/08/hugo-multilingual-part-1-managing-content-translation/) + +## Configure Languages + +The following is an example of a site configuration for a multilingual Hugo project: + +{{< code-toggle file="config" >}} +DefaultContentLanguage = "en" +copyright = "Everything is mine" + +[params] +[params.navigation] +help = "Help" + +[languages] +[languages.en] +title = "My blog" +weight = 1 +[languages.en.params] +linkedin = "https://linkedin.com/whoever" + +[languages.fr] +title = "Mon blogue" +weight = 2 +[languages.fr.params] +linkedin = "https://linkedin.com/fr/whoever" +[languages.fr.params.navigation] +help = "Aide" + +[languages.ar] +title = "مدونتي" +weight = 2 +languagedirection = "rtl" +{{< /code-toggle >}} + +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). This also works for `params`, as demonstrated with `help` above: You will get the value `Aide` in French and `Help` in all the languages without this parameter set. + +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. + +`defaultContentLanguage` sets the project's default language. If not set, the default language will be `en`. + +If the default language needs to be rendered below its own language code (`/en`) like the others, set `defaultContentLanguageInSubdir: true`. + +Only the obvious non-global options can be overridden per language. Examples of global options are `baseURL`, `buildDrafts`, etc. + +### Disable a Language + +You can disable one or more languages. This can be useful when working on a new translation. + +```toml +disableLanguages = ["fr", "ja"] +``` + +Note that you cannot disable the default content language. + +We kept this as a standalone setting to make it easier to set via [OS environment](/getting-started/configuration/#configure-with-environment-variables): + +```bash +HUGO_DISABLELANGUAGES="fr ja" hugo +``` +If you have already a list of disabled languages in `config.toml`, you can enable them in development like this: + +```bash +HUGO_DISABLELANGUAGES=" " hugo server +``` + + +### 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 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: + +{{< code-toggle file="config" >}} +[languages] +[languages.fr] +baseURL = "https://example.fr" +languageName = "Français" +weight = 1 +title = "En Français" + +[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 +└── fr +``` + +**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 typically 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-toggle file="config" >}} +[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" +{{}} + +## Translate Your Content + +There are two ways to manage your content translations. Both ensure each page is assigned a language and is linked to its counterpart translations. + +### Translation by filename + +Considering the following example: + +1. `/content/about.en.md` +2. `/content/about.fr.md` + +The first file is assigned the English language and is linked to the second. +The second file is assigned the French language and is linked to the first. + +Their language is __assigned__ according to the language code added as a __suffix to the filename__. + +By having the same **path and base filename**, the content pieces are __linked__ together as translated pages. + +{{< note >}} +If a file has no language code, it will be assigned the default language. +{{}} + +### Translation by content directory + +This system uses different content directories for each of the languages. Each language's content directory is set using the `contentDir` param. + +{{< code-toggle file="config" >}} + +languages: + en: + weight: 10 + languageName: "English" + contentDir: "content/english" + fr: + weight: 20 + languageName: "Français" + contentDir: "content/french" + +{{< /code-toggle >}} + +The value of `contentDir` can be any valid path -- even absolute path references. The only restriction is that the content directories cannot overlap. + +Considering the following example in conjunction with the configuration above: + +1. `/content/english/about.md` +2. `/content/french/about.md` + +The first file is assigned the English language and is linked to the second. +The second file is assigned the French language and is linked to the first. + +Their language is __assigned__ according to the content directory they are __placed__ in. + +By having the same **path and basename** (relative to their language content directory), the content pieces are __linked__ together as translated pages. + +### Bypassing default linking. + +Any pages sharing the same `translationKey` set in front matter will be linked as translated pages regardless of basename or location. + +Considering the following example: + +1. `/content/about-us.en.md` +2. `/content/om.nn.md` +3. `/content/presentation/a-propos.fr.md` + +```yaml +# set in all three pages +translationKey: "about" +``` + +By setting the `translationKey` front matter param to `about` in all three pages, they will be __linked__ as translated pages. + + +### Localizing permalinks + +Because paths and filenames are used to handle linking, all translated pages will share the same URL (apart from the language subdirectory). + +To localize the URLs, the [`slug`]({{< ref "/content-management/organization/index.md#slug" >}}) or [`url`]({{< ref "/content-management/organization/index.md#url" >}}) front matter param can be set in any of the non-default language file. + +For example, a French translation (`content/about.fr.md`) can have its own localized slug. + +{{< code-toggle >}} +Title: A Propos +slug: "a-propos" +{{< /code-toggle >}} + + +At render, Hugo will build both `/about/` and `/fr/a-propos/` while maintaining their translation linking. + +{{% note %}} +If using `url`, remember to include the language part as well: `/fr/compagnie/a-propos/`. +{{%/ note %}} + +### Page Bundles + +To avoid the burden of having to duplicate files, each Page Bundle inherits the resources of its linked translated pages' bundles except for the content files (markdown files, html files etc...). + +Therefore, from within a template, the page will have access to the files from all linked pages' bundles. + +If, across the linked bundles, two or more files share the same basename, only one will be included and chosen as follows: + +* File from current language bundle, if present. +* First file found across bundles by order of language `Weight`. + +{{% note %}} +Page Bundle resources follow the same language assignment logic as content files, both by filename (`image.jpg`, `image.fr.jpg`) and by directory (`english/about/header.jpg`, `french/about/header.jpg`). +{{%/ note %}} + +## Reference the 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, whether a [single content page][contenttemplate] or the [homepage][]. It will not print anything if there are no translations for a given page. + +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 the page itself. 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 %}} + ++### Query basic translation ++ +From within your templates, use the `i18n` function like this: + +``` +{{ i18n "home" }} +``` + - This uses a definition like this one in `i18n/en-US.toml`: ++The function will search for the `"home"` id from `i18n/en-US.toml` file: + +``` +[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`: ++The result will be ++ ++``` ++Home ++``` ++ ++### Query a flexible translation with variables ++ ++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`: ++The function will pass the `.` context to the `"wordCount"` id in `i18n/en-US.toml` file: + +``` +[wordCount] +other = "This article has {{ .WordCount }} words." +``` - An example of singular and plural form: ++ ++Assume `.WordCount` in the context has value is 101. The result will be: ++ ++``` ++This article has 101 words. ++``` ++ ++### Query a singular/plural translation ++ ++In other to meet singular/plural requirement, you must pass a dictionary (map) data with a numeric `.Count` property to the `i18n` function. The below example uses `.ReadingTime` variable which has a built-in `.Count` property. ++ ++``` ++{{ i18n "readingTime" .ReadingTime }} ++``` ++ ++The function will read `.Count` from `.ReadingTime` and evaluate where the number is singular (`one`) or plural (`other`). After that, it will pass to `readingTime` id in `i18n/en-US.toml` file: + +``` +[readingTime] +one = "One minute to read" +other = "{{.Count}} minutes to read" +``` - And then in the template: ++ ++Assume `.ReadingTime.Count` in the context has value is 525600. The result will be: + +``` - {{ i18n "readingTime" .ReadingTime }} ++525600 minutes to read ++``` ++ ++If `.ReadingTime.Count` in the context has value is 1. The result is: ++ ++``` ++One minutes to read +``` + ++In case you need to pass a custom data: (`"(dict Count" 25)` is minimum requirment) ++ ++``` ++{{ i18n "readingTime" (dict "Count" 25 "FirstArgument" true "SecondArgument" false "Etc" "so on, so far") }} ++``` ++ ++ +## Customize Dates + +At the time of this writing, Go does not yet have support for internationalized locales for dates, 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. Creating multilingual menus works just like [creating regular menus][menus], except they're defined in language-specific blocks 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 in the current language. Note that `absLangURL` below will link to the correct locale of your website. Without it, menu entries in all languages would link to the English version, since it's the default content language that resides in the root directory. + +``` + + +``` + +## 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 suitable for production environments. +{{% /note %}} + +For merging of content from other languages (i.e. missing content translations), see [lang.Merge](/functions/lang.merge/). + +To track down missing translation strings, run Hugo with the `--i18n-warnings` flag: + +``` + hugo --i18n-warnings | grep i18n +i18n|MISSING_TRANSLATION|en|wordCount +``` + +## 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 `.RelPermalink` +* Be constructed with the [`relLangURL` template function][rellangurl] or the [`absLangURL` template function][abslangurl] **OR** be 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/en/functions/ref.md index feac06c9,00000000..0ec249c6 mode 100644,000000..100644 --- a/docs/content/en/functions/ref.md +++ b/docs/content/en/functions/ref.md @@@ -1,40 -1,0 +1,51 @@@ +--- +title: ref +linktitle: ref - description: Looks up a content page by logical name. ++description: Returns the absolute permalink to a page. +godocref: +date: 2017-02-01 +publishdate: 2017-02-01 - lastmod: 2019-12-28 ++lastmod: 2020-09-05 +categories: [functions] +menu: + docs: + parent: "functions" +keywords: [cross references, anchors] - signature: ["ref . CONTENT"] ++signature: ["ref . PAGE"] +workson: [] +hugoversion: +relatedfuncs: [relref] +deprecated: false +aliases: [] +--- + - `ref` and `relref` look up a content page by logical name (`ref`) or relative path (`relref`) to return the permalink: ++This function takes two parameters: + - ``` ++- The context of the page from which to resolve relative paths, typically the current page (`.`) ++- The path to a page, with or without a file extension, with or without an anchor. A path without a leading `/` is first resolved relative to the given context, then to the remainder of the site. ++ ++```go-html-template ++{{ ref . "about" }} ++{{ ref . "about#anchor" }} +{{ ref . "about.md" }} ++{{ ref . "about.md#anchor" }} ++{{ ref . "#anchor" }} ++{{ ref . "/blog/my-post" }} ++{{ ref . "/blog/my-post.md" }} +``` + - {{% note "Usage Note" %}} - `ref` looks up Hugo "Regular Pages" only. It can't be used for the homepage, section pages, etc. - {{% /note %}} ++To return the absolute permalink to another language version of a page: ++ ++```go-html-template ++{{ ref . (dict "path" "about.md" "lang" "fr") }} ++``` + - It is also possible to pass additional arguments to link to another language or an alternative output format. Therefore, pass a map of arguments instead of just the path. ++To return the absolute permalink to another Output Format of a page: + - ``` - {{ ref . (dict "path" "about.md" "lang" "ja" "outputFormat" "rss") }} ++```go-html-template ++{{ ref . (dict "path" "about.md" "outputFormat" "rss") }} +``` + - 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). ++Hugo emits an error or warning if the page cannot be uniquely resolved. The error behavior is configurable; see [Ref and RelRef Configuration](/content-management/cross-references/#ref-and-relref-configuration). + - For an extensive explanation of how to leverage `ref` and `relref` for content management, see [Cross References](/content-management/cross-references/). ++This function is used by Hugo's built-in [`ref`](/content-management/shortcodes/#ref-and-relref) shortcode. For a detailed explanation of how to leverage this shortcode for content management, see [Links and Cross References](/content-management/cross-references/). diff --cc docs/content/en/functions/relref.md index fe569905,00000000..18f65f1f mode 100644,000000..100644 --- a/docs/content/en/functions/relref.md +++ b/docs/content/en/functions/relref.md @@@ -1,40 -1,0 +1,58 @@@ +--- +title: relref - # linktitle: relref - description: Looks up a content page by relative path. ++linktitle: relref ++description: Returns the relative permalink to a page. +godocref: +date: 2017-02-01 +publishdate: 2017-02-01 - lastmod: 2019-12-28 ++lastmod: 2020-09-05 +categories: [functions] +menu: + docs: + parent: "functions" +keywords: [cross references, anchors] - signature: ["relref . CONTENT"] ++signature: ["relref . PAGE"] +workson: [] +hugoversion: +relatedfuncs: [ref] +deprecated: false +aliases: [] +--- + - `ref` and `relref` look up a content page by logical name (`ref`) or relative path (`relref`) to return the permalink: ++This function takes two parameters: + - ``` ++- The context of the page from which to resolve relative paths, typically the current page (`.`) ++- The path to a page, with or without a file extension, with or without an anchor. A path without a leading `/` is first resolved relative to the given context, then to the remainder of the site. ++ ++```go-html-template ++{{ relref . "about" }} ++{{ relref . "about#anchor" }} +{{ relref . "about.md" }} ++{{ relref . "about.md#anchor" }} ++{{ relref . "#anchor" }} ++{{ relref . "/blog/my-post" }} ++{{ relref . "/blog/my-post.md" }} +``` + - {{% note "Usage Note" %}} - `relref` looks up Hugo "Regular Pages" only. It can't be used for the homepage, section pages, etc. - {{% /note %}} ++The permalink returned is relative to the protocol+host portion of the baseURL specified in the site configuration. For example: ++ ++Code|baseURL|Permalink ++:--|:--|:-- ++`{{ relref . "/about" }}`|`http://example.org/`|`/about/` ++`{{ relref . "/about" }}`|`http://example.org/x/`|`/x/about/` ++ ++To return the relative permalink to another language version of a page: ++ ++```go-html-template ++{{ relref . (dict "path" "about.md" "lang" "fr") }} ++``` + - It is also possible to pass additional arguments to link to another language or an alternative output format. Therefore, pass a map of arguments instead of just the path. ++To return the relative permalink to another Output Format of a page: + - ``` - {{ relref . (dict "path" "about.md" "lang" "ja" "outputFormat" "rss") }} ++```go-html-template ++{{ relref . (dict "path" "about.md" "outputFormat" "rss") }} +``` + - 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). ++Hugo emits an error or warning if the page cannot be uniquely resolved. The error behavior is configurable; see [Ref and RelRef Configuration](/content-management/cross-references/#ref-and-relref-configuration). + - For an extensive explanation of how to leverage `ref` and `relref` for content management, see [Cross References](/content-management/cross-references/). ++This function is used by Hugo's built-in [`relref`](/content-management/shortcodes/#ref-and-relref) shortcode. For a detailed explanation of how to leverage this shortcode for content management, see [Links and Cross References](/content-management/cross-references/). diff --cc docs/content/en/functions/urlize.md index 0fd7c229,00000000..0742dd02 mode 100644,000000..100644 --- a/docs/content/en/functions/urlize.md +++ b/docs/content/en/functions/urlize.md @@@ -1,73 -1,0 +1,74 @@@ +--- +title: urlize +# linktitle: urlize +description: Takes a string, sanitizes it for usage in URLs, and converts spaces to hyphens. +date: 2017-02-01 +publishdate: 2017-02-01 +lastmod: 2017-02-01 +categories: [functions] +menu: + docs: + parent: "functions" +keywords: [urls,strings] +godocref: +signature: ["urlize INPUT"] +hugoversion: +deprecated: false +workson: [] +relatedfuncs: [] +--- + +The following examples pull from a content file with the following front matter: + +{{< code file="content/blog/greatest-city.md" copy="false">}} ++++ +title = "The World's Greatest City" +location = "Chicago IL" +tags = ["pizza","beer","hot dogs"] ++++ +{{< /code >}} + +The following might be used as a partial within a [single page template][singletemplate]: + +{{< code file="layouts/partials/content-header.html" download="content-header.html" >}} +
+

{{.Title}}

+ {{ with .Params.location }} +
{{.}}
+ {{ end }} + + {{ with .Params.tags }} +
    + {{range .}} +
  • + {{ . }} +
    • + {{end}} +
+ {{ end }} +
+{{< /code >}} + +The preceding partial would then output to the rendered page as follows, assuming the page is being built with Hugo's default pretty URLs. + +{{< output file="/blog/greatest-city/index.html" >}} +
-

The World's Greatest City

-
Chicago IL
++

The World's Greatest City

++
Chicago IL
+ +
+{{< /output >}} + + ++ +[singletemplate]: /templates/single-page-templates/ diff --cc docs/content/en/getting-started/configuration-markup.md index 99d1e989,00000000..8b2011f8 mode 100644,000000..100644 --- a/docs/content/en/getting-started/configuration-markup.md +++ b/docs/content/en/getting-started/configuration-markup.md @@@ -1,198 -1,0 +1,196 @@@ +--- +title: Configure Markup +description: How to handle Markdown and other markup related configuration. +date: 2019-11-15 +categories: [getting started,fundamentals] +keywords: [configuration,highlighting] +weight: 65 +sections_weight: 65 +slug: configuration-markup +toc: true +--- + +## Configure Markup + +{{< new-in "0.60.0" >}} + +See [Goldmark](#goldmark) for settings related to the default Markdown handler in Hugo. + +Below are all markup related configuration in Hugo with their default settings: + +{{< code-toggle config="markup" />}} + +**See each section below for details.** + +### Goldmark + +[Goldmark](https://github.com/yuin/goldmark/) is from Hugo 0.60 the default library used for Markdown. It's fast, it's [CommonMark](https://spec.commonmark.org/0.29/) compliant and it's very flexible. Note that the feature set of Goldmark vs Blackfriday isn't the same; you gain a lot but also lose some, but we will work to bridge any gap in the upcoming Hugo versions. + +This is the default configuration: + +{{< code-toggle config="markup.goldmark" />}} + +Some settings explained: + +unsafe +: By default, Goldmark does not render raw HTMLs and potentially dangerous links. If you have lots of inline HTML and/or JavaScript, you may need to turn this on. + +typographer +: This extension substitutes punctuations with typographic entities like [smartypants](https://daringfireball.net/projects/smartypants/). + +autoHeadingIDType ("github") {{< new-in "0.62.2" >}} +: The strategy used for creating auto IDs (anchor names). Available types are `github`, `github-ascii` and `blackfriday`. `github` produces GitHub-compatible IDs, `github-ascii` will drop any non-Ascii characters after accent normalization, and `blackfriday` will make the IDs work as with [Blackfriday](#blackfriday), the default Markdown engine before Hugo 0.60. Note that if Goldmark is your default Markdown engine, this is also the strategy used in the [anchorize](/functions/anchorize/) template func. + +### Blackfriday + + +[Blackfriday](https://github.com/russross/blackfriday) was Hugo's default Markdown rendering engine, now replaced with Goldmark. But you can still use it: Just set `defaultMarkdownHandler` to `blackfriday` in your top level `markup` config. + +This is the default config: + +{{< code-toggle config="markup.blackFriday" />}} + +### Highlight + +This is the default `highlight` configuration. Note that some of these settings can be set per code block, see [Syntax Highlighting](/content-management/syntax-highlighting/). + +{{< code-toggle config="markup.highlight" />}} + +For `style`, see these galleries: + +* [Short snippets](https://xyproto.github.io/splash/docs/all.html) +* [Long snippets](https://xyproto.github.io/splash/docs/longer/all.html) + +For CSS, see [Generate Syntax Highlighter CSS](/content-management/syntax-highlighting/#generate-syntax-highlighter-css). + +### Table Of Contents + +{{< code-toggle config="markup.tableOfContents" />}} + +These settings only works for the Goldmark renderer: + +startLevel +: The heading level, values starting at 1 (`h1`), to start render the table of contents. + +endLevel +: The heading level, inclusive, to stop render the table of contents. + +ordered +: Whether or not to generate an ordered list instead of an unordered list. + + +## Markdown Render Hooks + +{{< new-in "0.62.0" >}} + +Note that this is only supported with the [Goldmark](#goldmark) renderer. + +Render Hooks allow custom templates to override markdown rendering functionality. You can do this by creating templates with base names `render-{feature}` in `layouts/_default/_markup`. + +You can also create type/section specific hooks in `layouts/[type/section]/_markup`, e.g.: `layouts/blog/_markup`.{{< new-in "0.71.0" >}} + +The features currently supported are: + +* `image` +* `link` +* `heading` {{< new-in "0.71.0" >}} + - You can define [Output-Format-](/templates/output-formats) and [language-](/content-management/multilingual/)specific templates if needed.[^hooktemplate] Your `layouts` folder may look like this: ++You can define [Output-Format-](/templates/output-formats) and [language-](/content-management/multilingual/)specific templates if needed. Your `layouts` folder may look like this: + +```bash +layouts +└── _default + └── _markup + ├── render-image.html + ├── render-image.rss.xml + └── render-link.html +``` + +Some use cases for the above: + +* Resolve link references using `.GetPage`. This would make links portable as you could translate `./my-post.md` (and similar constructs that would work on GitHub) into `/blog/2019/01/01/my-post/` etc. +* Add `target=_blank` to external links. +* Resolve and [process](/content-management/image-processing/) images. +* Add [header links](https://remysharp.com/2014/08/08/automatic-permalinks-for-blog-posts). + +### Render Hook Templates + +The `render-link` and `render-image` templates will receive this context: + +Page +: The [Page](/variables/page/) being rendered. + +Destination +: The URL. + +Title +: The title attribute. + +Text +: The rendered (HTML) link text. + +PlainText +: The plain variant of the above. + +The `render-heading` template will receive this context: + +Page +: The [Page](/variables/page/) being rendered. + +Level +: The header level (1--6) + +Anchor +: An auto-generated html id unique to the header within the page + +Text +: The rendered (HTML) text. + +PlainText +: The plain variant of the above. + +#### Link with title Markdown example: + +```md +[Text](https://www.gohugo.io "Title") +``` + +Here is a code example for how the render-link.html template could look: + +{{< code file="layouts/_default/_markup/render-link.html" >}} +{{ .Text | safeHTML }} +{{< /code >}} + +#### Image Markdown example: + +```md +![Text](https://d33wubrfki0l68.cloudfront.net/c38c7334cc3f23585738e40334284fddcaf03d5e/2e17c/images/hugo-logo-wide.svg "Title") +``` + +Here is a code example for how the render-image.html template could look: + +{{< code file="layouts/_default/_markup/render-image.html" >}} +

+ {{ .Text }} +

+{{< /code >}} + +#### Heading link example + +Given this template file + +{{< code file="layouts/_default/_markup/render-heading.html" >}} +{{ .Text | safeHTML }} ¶ +{{< /code >}} + +And this markdown + +```md +### Section A +``` + +The rendered html will be + +```html +

Section A ¶

+``` - - [^hooktemplate]: It's currently only possible to have one set of render hook templates, e.g. not per `Type` or `Section`. We may consider that in a future version. diff --cc docs/content/en/getting-started/installing.md index f92ad21a,00000000..ae3fe7f9 mode 100644,000000..100644 --- a/docs/content/en/getting-started/installing.md +++ b/docs/content/en/getting-started/installing.md @@@ -1,537 -1,0 +1,562 @@@ +--- +title: Install Hugo +linktitle: Install Hugo +description: Install Hugo on macOS, Windows, Linux, OpenBSD, FreeBSD, and on any machine where the Go compiler tool chain can run. +date: 2016-11-01 +publishdate: 2016-11-01 +lastmod: 2018-01-02 +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 +* OpenBSD +* FreeBSD + +Hugo may also be compiled from source wherever the Go toolchain 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. + +### Docker + +We currently do not offer official Hugo images for Docker, but we do recommend these up to date distributions: https://hub.docker.com/r/klakegg/hugo/ + +### 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. + ++### MacPorts (macOS) ++ ++If you are on macOS and using [MacPorts][macports], you can install Hugo with the following one-liner: ++ ++{{< code file="install-with-macports.sh" >}} ++port install hugo ++{{< /code >}} ++ +### Homebrew (Linux) + +If you are using [Homebrew][linuxbrew] on Linux, you can install Hugo with the following one-liner: + +{{< code file="install-with-linuxbrew.sh" >}} +brew install hugo +{{< /code >}} + +Installation guides for Homebrew on Linux are available on their [website][linuxbrew]. + +### 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 >}} + +Or if you need the “extended” Sass/SCSS version: + +{{< code file="install-extended-with-chocolatey.ps1" >}} +choco install hugo-extended -confirm +{{< /code >}} + +### Scoop (Windows) + +If you are on a Windows machine and use [Scoop][] for package management, you can install Hugo with the following one-liner: + +```bash +scoop install hugo +``` + +Or install the extended version with: + +```bash +scoop install hugo-extended +``` + +### Source + +#### Prerequisite Tools + +* [Git][installgit] +* [Go (at least Go 1.11)](https://golang.org/dl/) + +#### Fetch from GitHub + +Since Hugo 0.48, Hugo uses the Go Modules support built into Go 1.11 to build. The easiest way to get started is to clone Hugo in a directory outside of the GOPATH, as in the following example: + +{{< code file="from-gh.sh" >}} +mkdir $HOME/src +cd $HOME/src +git clone https://github.com/gohugoio/hugo.git +cd hugo +go install --tags extended +{{< /code >}} + +Remove `--tags extended` if you do not want/need Sass/SCSS support. + +{{% 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 ++1. A package manager, like [Homebrew][brew] (`brew`) or [MacPorts][macports] (`port`) +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. ++1. **Package Manager.** Using a package manager 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 in Homebrew). Releases may lag a few days behind because it has to be coordinated with another team. Nevertheless, this is the recommended installation method if you want to work from a stable, widely used source. Package managers work well and they are 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. ++You may need to add your bin directory to your `PATH` environment 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: ++If `hugo` is not in your `PATH`: + - ``` - nano ~/.bash_profile - ``` ++1. Determine your default shell (zsh or bash). + - Add a line to update your `PATH` variable: ++ ``` ++ echo $SHELL ++ ``` + - ``` - export PATH=$PATH:$HOME/bin - ``` ++2. Edit your profile. ++ ++ If your default shell is zsh: ++ ++ ``` ++ nano ~/.zprofile ++ ``` ++ ++ If your default shell is bash: ++ ++ ``` ++ nano ~/.bash_profile ++ ``` ++ ++3. Insert a line to add `$HOME/bin` to your existing `PATH`. ++ ++ ``` ++ export PATH=$PATH:$HOME/bin ++ ``` + - Then save the file by pressing Control-X, then Y to save the file and return to the prompt. ++4. Save the file by pressing Control-X, then Y. + - 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. ++5. Close the terminal and open a new terminal to pick up the changes to your profile. Verify the change 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 + +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. 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: The hugo executable (`hugo.exe`), `LICENSE`, and `README.md`. + +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], you may install the "extended" Sass/SCSS version with this command: + + snap install hugo --channel=extended + +To install the non-extended version without Sass/SCSS support: + + snap install hugo + +To switch between the two, use either `snap refresh hugo --channel=extended` or `snap refresh hugo --channel=stable`. + +{{% note %}} +Hugo installed via 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 + +[@anthonyfok](https://github.com/anthonyfok) and friends in the [Debian Go Packaging Team](https://go-team.pages.debian.net/) maintains an official hugo [Debian package](https://packages.debian.org/hugo) which is shared with [Ubuntu](https://packages.ubuntu.com/hugo) and is installable via `apt-get`: + + sudo apt-get install hugo + +What this installs depends on your Debian/Ubuntu version. On Ubuntu bionic (18.04), this installs the non-extended version without Sass/SCSS support. On Ubuntu disco (19.04), this installs the extended version with Sass/SCSS support. + +This option is not recommended because the Hugo in Linux package managers for Debian and Ubuntu is usually a few versions behind as described [here](https://github.com/gcushen/hugo-academic/issues/703) + +### Arch Linux + +You can also install Hugo from the Arch Linux [community](https://www.archlinux.org/packages/community/x86_64/hugo/) repository. Applies also to derivatives such as Manjaro. + +``` +sudo pacman -Syu hugo +``` + +### Fedora, Red Hat and CentOS + +Fedora maintains an [official package for Hugo](https://apps.fedoraproject.org/packages/hugo) which may be installed with: + + sudo dnf install hugo + +For the latest version, the Hugo package maintained by [@daftaupe](https://github.com/daftaupe) at Fedora Copr is recommended: + +* + +See the [related discussion in the Hugo forums][redhatforum]. + +### Solus + +Solus includes Hugo in its package repository, it may be installed with: + +``` +sudo eopkg install hugo +``` + +## OpenBSD + +OpenBSD provides a package for Hugo via `pkg_add`: + + doas pkg_add hugo + + +## 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. + +## 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/ ++[macports]: https://www.macports.org/ +[Chocolatey]: https://chocolatey.org/ +[content]: /content-management/ +[@dhersam]: https://github.com/dhersam +[forum]: https://discourse.gohugo.io +[mage]: https://github.com/magefile/mage +[dep]: https://github.com/golang/dep +[highlight shortcode]: /content-management/shortcodes/#highlight +[installgit]: https://git-scm.com/ +[installgo]: https://golang.org/dl/ +[linuxbrew]: https://docs.brew.sh/Homebrew-on-Linux +[Path Editor]: https://patheditor2.codeplex.com/ +[pygments]: https://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 +[Scoop]: https://scoop.sh/ +[snaps]: https://snapcraft.io/docs/installing-snapd +[windowsarch]: https://esupport.trendmicro.com/en-us/home/pages/technical-support/1038680.aspx +[Windows Environment Variables Editor]: http://eveditor.com/ diff --cc docs/content/en/getting-started/quick-start.md index 0d79c3ed,00000000..28b6b039 mode 100644,000000..100644 --- a/docs/content/en/getting-started/quick-start.md +++ b/docs/content/en/getting-started/quick-start.md @@@ -1,176 -1,0 +1,179 @@@ +--- +title: Quick Start +linktitle: Quick Start +description: Create a Hugo site using the beautiful Ananke theme. +date: 2013-07-01 +publishdate: 2013-07-01 +categories: [getting started] +keywords: [quick start,usage] +authors: [Shekhar Gulati, Ryan Watters] +menu: + docs: + parent: "getting-started" + weight: 10 +weight: 10 +sections_weight: 10 +draft: false +aliases: [/quickstart/,/overview/quickstart/] +toc: true +--- + +{{% note %}} +This quick start uses `macOS` in the examples. For instructions about how to install Hugo on other operating systems, see [install](/getting-started/installing). + +It is recommended to have [Git installed](https://git-scm.com/downloads) to run this tutorial. + +For other approaches learning Hugo like book or a video tutorial refer to the [external learning resources](/getting-started/external-learning-resources/) page. +{{% /note %}} + +## Step 1: Install Hugo + +{{% note %}} - `Homebrew`, a package manager for `macOS`, can be installed from [brew.sh](https://brew.sh/). See [install](/getting-started/installing) if you are running Windows etc. ++`Homebrew` and `MacPorts`, package managers for `macOS`, can be installed from [brew.sh](https://brew.sh/) or [macports.org](https://www.macports.org/) respectively. See [install](/getting-started/installing) if you are running Windows etc. +{{% /note %}} + +```bash +brew install hugo ++# or ++port install hugo +``` + +To verify your new install: + +```bash +hugo version +``` + +{{< asciicast ItACREbFgvJ0HjnSNeTknxWy9 >}} + +## Step 2: Create a New Site + +```bash +hugo new site quickstart +``` + +The above will create a new Hugo site in a folder named `quickstart`. + +{{< asciicast 3mf1JGaN0AX0Z7j5kLGl3hSh8 >}} + +## Step 3: Add a Theme + +See [themes.gohugo.io](https://themes.gohugo.io/) for a list of themes to consider. This quickstart uses the beautiful [Ananke theme](https://themes.gohugo.io/gohugo-theme-ananke/). + +First, download the theme from GitHub and add it to your site's `themes` directory: + +```bash +cd quickstart +git init +git submodule add https://github.com/budparr/gohugo-theme-ananke.git themes/ananke +``` + +*Note for non-git users:* + - If you do not have git installed, you can download the archive of the latest + version of this theme from: + https://github.com/budparr/gohugo-theme-ananke/archive/master.zip + - Extract that .zip file to get a "gohugo-theme-ananke-master" directory. + - Rename that directory to "ananke", and move it into the "themes/" directory. + +Then, add the theme to the site configuration: + +```bash +echo 'theme = "ananke"' >> config.toml +``` + +{{< asciicast 7naKerRYUGVPj8kiDmdh5k5h9 >}} + +## Step 4: Add Some Content + +You can manually create content files (for example as `content//.`) and provide metadata in them, however you can use the `new` command to do a few things for you (like add title and date): + +``` +hugo new posts/my-first-post.md +``` + +{{< asciicast eUojYCfRTZvkEiqc52fUsJRBR >}} + +Edit the newly created content file if you want, it will start with something like this: + +```markdown +--- +title: "My First Post" +date: 2019-03-26T08:47:11+01:00 +draft: true +--- + +``` + ++{{% note %}} ++Drafts do not get deployed; once you finish a post, update the header of the post to say `draft: false`. More info [here](/getting-started/usage/#draft-future-and-expired-content). ++{{% /note %}} ++ +## Step 5: Start the Hugo server + +Now, start the Hugo server with [drafts](/getting-started/usage/#draft-future-and-expired-content) enabled: + +{{< asciicast BvJBsF6egk9c163bMsObhuNXj >}} + +``` +▶ hugo server -D + + | EN ++------------------+----+ + Pages | 10 + Paginator pages | 0 + Non-page files | 0 + Static files | 3 + Processed images | 0 + Aliases | 1 + Sitemaps | 1 + Cleaned | 0 + +Total in 11 ms +Watching for changes in /Users/bep/quickstart/{content,data,layouts,static,themes} +Watching for config changes in /Users/bep/quickstart/config.toml +Environment: "development" +Serving pages from memory +Running in Fast Render Mode. For full rebuilds on change: hugo server --disableFastRender +Web Server is available at http://localhost:1313/ (bind address 127.0.0.1) +Press Ctrl+C to stop +``` + +**Navigate to your new site at [http://localhost:1313/](http://localhost:1313/).** + +Feel free to edit or add new content and simply refresh in browser to see changes quickly (You might need to force refresh in webbrowser, something like Ctrl-R usually works). + +## Step 6: Customize the Theme + +Your new site already looks great, but you will want to tweak it a little before you release it to the public. + +### Site Configuration + +Open up `config.toml` in a text editor: + +``` +baseURL = "https://example.org/" +languageCode = "en-us" +title = "My New Hugo Site" +theme = "ananke" +``` + +Replace the `title` above with something more personal. Also, if you already have a domain ready, set the `baseURL`. Note that this value is not needed when running the local development server. + +{{% note %}} +**Tip:** Make the changes to the site configuration or any other file in your site while the Hugo server is running, and you will see the changes in the browser right away, though you may need to [clear your cache](https://kb.iu.edu/d/ahic). +{{% /note %}} + +For theme specific configuration options, see the [theme site](https://github.com/budparr/gohugo-theme-ananke). + +**For further theme customization, see [Customize a Theme](/themes/customizing/).** + +### Step 7: Build static pages + +It is simple. Just call: + +``` +hugo -D +``` + +Output will be in `./public/` directory by default (`-d`/`--destination` flag to change it, or set `publishdir` in the config file). + - {{% note %}} - Drafts do not get deployed; once you finish a post, update the header of the post to say `draft: false`. More info [here](/getting-started/usage/#draft-future-and-expired-content). - {{% /note %}} diff --cc docs/content/en/hugo-modules/configuration.md index 4106b393,00000000..c97e8d5a mode 100644,000000..100644 --- a/docs/content/en/hugo-modules/configuration.md +++ b/docs/content/en/hugo-modules/configuration.md @@@ -1,132 -1,0 +1,135 @@@ +--- +title: Configure Modules +linktitle: Configure Modules +description: This page describes the configuration options for a module. +date: 2019-07-24 +categories: [hugo modules] +keywords: [themes, source, organization, directories] +menu: + docs: + parent: "modules" + weight: 10 +weight: 10 +sections_weight: 10 +toc: true +--- + +## Module Config: Top level + +{{< code-toggle file="config">}} +[module] +proxy = "direct" +noProxy = "none" +private = "*.*" +{{< /code-toggle >}} + +proxy +: Defines the proxy server to use to download remote modules. Default is `direct`, which means "git clone" and similar. + +noProxy +: Comma separated glob list matching paths that should not use the proxy configured above. + +private +: Comma separated glob list matching paths that should be treated as private. + +Note that the above terms maps directly to their counterparts in Go Modules. Some of these setting may be natural to set as OS environment variables. To set the proxy server to use, as an example: + +``` +env HUGO_MODULE_PROXY=https://proxy.example.org hugo +``` + +{{< gomodules-info >}} + +## Module Config: hugoVersion + +If your module requires a particular version of Hugo to work, you can indicate that in the `module` section and the user will be warned if using a too old/new version. + +{{< code-toggle file="config">}} +[module] +[module.hugoVersion] + min = "" + max = "" + extended = false + +{{< /code-toggle >}} + +Any of the above can be omitted. + +min +: The minimum Hugo version supported, e.g. `0.55.0` + +max +: The maximum Hugo version supported, e.g. `0.55.0` + +extended +: Whether the extended version of Hugo is required. + +## Module Config: imports + +{{< code-toggle file="config">}} +[module] +[[module.imports]] + path = "github.com/gohugoio/hugoTestModules1_linux/modh1_2_1v" + ignoreConfig = false + disable = false +[[module.imports]] + path = "my-shortcodes" +{{< /code-toggle >}} + +path +: Can be either a valid Go Module module path, e.g. `github.com/gohugoio/myShortcodes`, or the directory name for the module as stored in your themes folder. + +ignoreConfig +: If enabled, any module configuration file, e.g. `config.toml`, will not be loaded. Note that this will also stop the loading of any transitive module dependencies. + +disable +: Set to `true` to disable the module off while keeping any version info in the `go.*` files. + +{{< gomodules-info >}} + + +## Module Config: mounts + +{{% note %}} - When the `mounts` config was introduced in Hugo 0.56.0, we were careful to preserve the existing `staticDir` and similar configuration to make sure all existing sites just continued to work. - - But you should not have both. So if you add a `mounts` section you should make it complete and remove the old `staticDir` etc. settings. ++When the `mounts` config was introduced in Hugo 0.56.0, we were careful to preserve the existing `staticDir` and similar configuration to make sure all existing sites just continued to work. But you should not have both: if you add a `mounts` section you should remove the old `staticDir` etc. settings. +{{% /note %}} + ++{{% warning %}} ++When you add a mount, the default mount for the concerned target root is ignored: be sure to explicitly add it. ++{{% /warning %}} ++ ++**Default mounts** +{{< code-toggle file="config">}} +[module] +[[module.mounts]] + source="content" + target="content" +[[module.mounts]] + source="static" + target="static" +[[module.mounts]] + source="layouts" + target="layouts" +[[module.mounts]] + source="data" + target="data" +[[module.mounts]] + source="assets" + target="assets" +[[module.mounts]] + source="i18n" + target="i18n" +[[module.mounts]] + source="archetypes" + target="archetypes" +{{< /code-toggle >}} + +source +: The source directory of the mount. For the main project, this can be either project-relative or absolute and even a symbolic link. For other modules it must be project-relative. + +target +: Where it should be mounted into Hugo's virtual filesystem. It must start with one of Hugo's component folders: `static`, `content`, `layouts`, `data`, `assets`, `i18n`, or `archetypes`. E.g. `content/blog`. + +lang +: The language code, e.g. "en". Only relevant for `content` mounts, and `static` mounts when in multihost mode. + diff --cc docs/content/en/templates/introduction.md index fb7d341d,00000000..43f88f14 mode 100644,000000..100644 --- a/docs/content/en/templates/introduction.md +++ b/docs/content/en/templates/introduction.md @@@ -1,662 -1,0 +1,662 @@@ +--- +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: [/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](https://golang.org/pkg/text/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. + +## Basic Syntax + +Go Templates are HTML files with the addition of [variables][variables] and [functions][functions]. Go Template variables and functions are accessible within `{{ }}`. + +### Access a Predefined Variable + +A _predefined variable_ could be a variable already existing in the +current scope (like the `.Title` example in the [Variables]({{< relref +"#variables" >}}) section below) or a custom variable (like the +`$address` example in that same section). + + +```go-html-template +{{ .Title }} +{{ $address }} +``` + +Parameters for functions are separated using spaces. The general syntax is: + +``` +{{ FUNCTION ARG1 ARG2 .. }} +``` + +The following example calls the `add` function with inputs of `1` and `2`: + +```go-html-template +{{ 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][]. + +```go-html-template +{{ .Params.bar }} +``` + +#### Parentheses Can be Used to Group Items Together + +```go-html-template +{{ if or (isset .Params "alt") (isset .Params "caption") }} Caption {{ end }} +``` + +## Variables {#variables} + +Each Go Template gets a data object. In Hugo, each template is passed +a `Page`. In the below example, `.Title` is one of the elements +accessible in that [`Page` variable][pagevars]. + +With the `Page` being the default scope of a template, the `Title` +element in current scope (`.` -- "the **dot**") is accessible simply +by the dot-prefix (`.Title`): + +```go-html-template +{{ .Title }} +``` + +Values can also be stored in custom variables and referenced later: + +{{% note %}} +The custom variables need to be prefixed with `$`. +{{% /note %}} + +```go-html-template +{{ $address := "123 Main St." }} +{{ $address }} +``` + +{{% warning %}} +For Hugo v0.47 and older versions, 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 %}} + +For **Hugo v0.48** and newer, variables can be re-defined using the +new `=` operator (new in Go 1.11). + +Below example will work only in these newer Hugo versions. The example +prints "Var is Hugo Home" on the home page, and "Var is Hugo Page" on +all other pages: + +```go-html-template +{{ $var := "Hugo Page" }} +{{ if .IsHome }} + {{ $var = "Hugo Home" }} +{{ end }} +Var is {{ $var }} +``` + +## 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 + +```go-html-template +{{ add 1 2 }} + +``` + +### Example 2: Comparing Numbers + +```go-html-template +{{ lt 1 2 }} + +``` + +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 [Go Template documentation](https://golang.org/pkg/text/template/#hdr-Functions). +{{% /note %}} + +## Includes + +When including another template, you will need to pass it the data that it would +need to access. + +{{% note %}} +To pass along the current context, please remember to include a trailing **dot**. +{{% /note %}} + +The templates location will always be starting at the `layouts/` directory +within Hugo. + +### Partial + +The [`partial`][partials] function is used to include *partial* templates using +the syntax `{{ partial "/." . }}`. + +Example of including a `layouts/partials/header.html` partial: + +```go-html-template +{{ partial "header.html" . }} +``` + +### Template + +The `template` function was used to include *partial* templates +in much older Hugo versions. Now it's useful only for calling +[*internal* templates][internal_templates]. The syntax is `{{ template +"_internal/