From: Bjørn Erik Pedersen Date: Mon, 11 Jun 2018 20:32:19 +0000 (+0200) Subject: Merge commit 'b239595af5a9fc1fc9a1ccc666c3ab06ccc32f04' X-Git-Tag: v0.42~6 X-Git-Url: http://git.maquefel.me/?a=commitdiff_plain;h=e02629f81ab5f817a95cf0ffec8f0aa2016294aa;p=brevno-suite%2Fhugo Merge commit 'b239595af5a9fc1fc9a1ccc666c3ab06ccc32f04' --- e02629f81ab5f817a95cf0ffec8f0aa2016294aa diff --cc docs/README.md index 5f47e8a1,00000000..23c4a6f5 mode 100644,000000..100644 --- a/docs/README.md +++ b/docs/README.md @@@ -1,45 -1,0 +1,45 @@@ +# Hugo Docs + - Documentation site for [Hugo](https://github.com/gohugoio/hugo), the very fast and flexible static site generator built with love in GoLang. ++Documentation site for [Hugo](https://github.com/gohugoio/hugo), the very fast and flexible static site generator built with love in Go. + +## Contributing + +We welcome contributions to Hugo of any kind including documentation, suggestions, bug reports, pull requests etc. Also check out our [contribution guide](https://gohugo.io/contribute/documentation/). We would love to hear from you. + +Note that this repository contains solely the documentation for Hugo. For contributions that aren't documentation-related please refer to the [hugo](https://github.com/gohugoio/hugo) repository. + +*Pull requests shall **only** contain changes to the actual documentation. However, changes on the code base of Hugo **and** the documentation shall be a single, atomic pull request in the [hugo](https://github.com/gohugoio/hugo) repository.* + +Spelling fixes are most welcomed, and if you want to contribute longer sections to the documentation, it would be great if you had these in mind when writing: + +* Short is good. People go to the library to read novels. If there is more than one way to _do a thing_ in Hugo, describe the current _best practice_ (avoid "… but you can also do …" and "… in older versions of Hugo you had to …". +* For examples, try to find short snippets that teaches people about the concept. If the example is also useful as-is (copy and paste), then great, but don't list long and similar examples just so people can use them on their sites. +* Hugo has users from all over the world, so an easy to understand and [simple English](https://simple.wikipedia.org/wiki/Basic_English) is good. + +## Branches + +* The `master` branch is where the site is automatically built from, and is the place to put changes relevant to the current Hugo version. +* The `next` branch is where we store changes that is related to the next Hugo release. This can be previewed here: https://next--gohugoio.netlify.com/ + +## Build + +To view the documentation site locally, you need to clone this repository: + +```bash +git clone https://github.com/gohugoio/hugoDocs.git +``` + +Also note that the documentation version for a given version of Hugo can also be found in the `/docs` sub-folder of the [Hugo source repository](https://github.com/gohugoio/hugo). + +Then to view the docs in your browser, run Hugo and open up the link: + +```bash +▶ hugo server + +Started building sites ... +. +. +Serving pages from memory +Web Server is available at http://localhost:1313/ (bind address 127.0.0.1) +Press Ctrl+C to stop +``` diff --cc docs/content/en/about/hugo-and-gdpr.md index ef68d569,00000000..0a95e602 mode 100644,000000..100644 --- a/docs/content/en/about/hugo-and-gdpr.md +++ b/docs/content/en/about/hugo-and-gdpr.md @@@ -1,115 -1,0 +1,115 @@@ + + +--- +title: Hugo and the General Data Protection Regulation (GDPR) +linktitle: Hugo and GDPR +description: About how to configure your Hugo site to meet the new regulations. +date: 2018-05-25 +layout: single +keywords: ["GDPR", "Privacy", "Data Protection"] +menu: + docs: + parent: "about" + weight: 5 +weight: 5 +sections_weight: 5 +draft: false +aliases: [/privacy/,/gdpr/] +toc: true +--- + + + General Data Protection Regulation ([GDPR](https://en.wikipedia.org/wiki/General_Data_Protection_Regulation)) is a regulation in EU law on data protection and privacy for all individuals within the European Union and the European Economic Area. It became enforceable on 25 May 2018. + + **Hugo is a static site generator. By using Hugo you are already standing on very solid ground. Static HTML files on disk are much easier to reason about compared to server and database driven web sites.** + - But even static websites can integrate with external services, so from version `0.41`, Hugo provides a `Privacy Config` that covers the relevant built-in templates. ++ But even static websites can integrate with external services, so from version `0.41`, Hugo provides a **Privacy Config** that covers the relevant built-in templates. + + Note that: + + * These settings have their defaults setting set to _off_, i.e. how it worked before Hugo `0.41`. You must do your own evaluation of your site and apply the appropriate settings. + * We will continue this work and improve this further in future Hugo versions. + +## All Privacy Settings + +Below are all privacy settings and their default value. These settings need to be put in your site config (e.g. `config.toml`). + + {{< code-toggle file="config">}} +[privacy] +[privacy.disqus] +disable = false +[privacy.googleAnalytics] +disable = false +respectDoNotTrack = false +anonymizeIP = false +useSessionStorage = false +[privacy.instagram] +disable = false +simple = false +[privacy.twitter] +disable = false +enableDNT = false +[privacy.vimeo] +disable = false +[privacy.youtube] +disable = false +privacyEnhanced = false +{{< /code-toggle >}} + + +## Disable All Services + +An example Privacy Config that disables all the relevant services in Hugo. With this configuration, the other settings will not matter. + + {{< code-toggle file="config">}} +[privacy] +[privacy.disqus] +disable = true +[privacy.googleAnalytics] +disable = true +[privacy.instagram] +disable = true +[privacy.twitter] +disable = true +[privacy.vimeo] +disable = true +[privacy.youtube] +disable = true +{{< /code-toggle >}} + +## The Privacy Settings Explained + +### GoogleAnalytics + +anonymizeIP +: Enabling this will make it so the users' IP addresses are anonymized within Google Analytics. + +respectDoNotTrack +: Enabling this will make the GA templates respect the "Do Not Track" HTTP header. + +useSessionStorage +: Enabling this will disable the use of Cookies and use Session Storage to Store the GA Client ID. + +### Instagram + +simple +: If simple mode is enabled, a static and no-JS version of the Instagram image card will be built. Note that this only supports image cards and the image itself will be fetched from Instagram's servers. + +**Note:** If you use the _simple mode_ for Instagram and a site styled with Bootstrap 4, you may want to disable the inlines styles provided by Hugo: + + {{< code-toggle file="config">}} +[services] +[services.instagram] +disableInlineCSS = true +{{< /code-toggle >}} + +### Twitter + +enableDNT +: Enabling this for the twitter/tweet shortcode, the tweet and its embedded page on your site are not used for purposes that include personalized suggestions and personalized ads. + +### YouTube + +privacyEnhanced +: When you turn on privacy-enhanced mode, YouTube won’t store information about visitors on your website unless the user plays the embedded video. + diff --cc docs/content/en/content-management/multilingual.md index 28a6e4fe,00000000..9ac2efee mode 100644,000000..100644 --- a/docs/content/en/content-management/multilingual.md +++ b/docs/content/en/content-management/multilingual.md @@@ -1,386 -1,0 +1,386 @@@ +--- +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/,/tutorials/create-a-multilingual-site/] +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 site configuration for a multilingual Hugo project: + +{{< code-toggle file="config" >}} +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.params.navigation] +help = "Aide" +{{< /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). + +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. + +## Disable a Language + +You can disable one or more languages. This can be useful when working on a new translation. + +```toml +disableLanguages = ["fr", "jp"] +``` + +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 jp" 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.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-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 + +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" +``` + +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. + +For merging of content from other languages (i.e. missing content translations), see [lang.Merge](/functions/lang.merge/). + +## 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. + +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: ++At the time of this writing, Go 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. + +``` + + +``` + +## 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 %}} + +For merging of content from other languages (i.e. missing content translations), see [lang.Merge](/functions/lang.merge/). + +## 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/en/content-management/urls.md index d33725b7,00000000..ae58a627 mode 100644,000000..100644 --- a/docs/content/en/content-management/urls.md +++ b/docs/content/en/content-management/urls.md @@@ -1,275 -1,0 +1,275 @@@ +--- +title: URL Management +linktitle: URL Management +description: Hugo supports permalinks, aliases, link canonicalization, and multiple options for handling relative vs absolute URLs. +date: 2017-02-01 +publishdate: 2017-02-01 +lastmod: 2017-03-09 +keywords: [aliases,redirects,permalinks,urls] +categories: [content management] +menu: + docs: + parent: "content-management" + weight: 110 +weight: 110 #rem +draft: false +aliases: [/extras/permalinks/,/extras/aliases/,/extras/urls/,/doc/redirects/,/doc/alias/,/doc/aliases/] +toc: true +--- + +## Permalinks + +The default Hugo target directory for your built website is `public/`. However, you can change this value by specifying a different `publishDir` in your [site configuration][config]. The directories created at build time for a section reflect the position of the content's directory within the `content` folder and namespace matching its layout within the `contentdir` hierarchy. + +The `permalinks` option in your [site configuration][config] allows you to adjust the directory paths (i.e., the URLs) on a per-section basis. This will change where the files are written to and will change the page's internal "canonical" location, such that template references to `.RelPermalink` will honor the adjustments made as a result of the mappings in this option. + +{{% note "Default Publish and Content Folders" %}} +These examples use the default values for `publishDir` and `contentDir`; i.e., `public` and `content`, respectively. You can override the default values in your [site's `config` file](/getting-started/configuration/). +{{% /note %}} + +For example, if one of your [sections][] is called `post` and you want to adjust the canonical path to be hierarchical based on the year, month, and post title, you could set up the following configurations in YAML and TOML, respectively. + +### Permalinks Configuration Example + +{{< code-toggle file="config" copy="false" >}} +permalinks: + post: /:year/:month/:title/ +{{< /code-toggle >}} + +Only the content under `post/` will have the new URL structure. For example, the file `content/post/sample-entry.md` with `date: 2017-02-27T19:20:00-05:00` in its front matter will render to `public/2017/02/sample-entry/index.html` at build time and therefore be reachable at `https://example.com/2017/02/sample-entry/`. + +You can also configure permalinks of taxonomies with the same syntax, by using the plural form of the taxonomy instead of the section. You will probably only want to use the configuration values `:slug` or `:title`. + +### Permalink Configuration Values + +The following is a list of values that can be used in a `permalink` definition in your site `config` file. All references to time are dependent on the content's date. + +`:year` +: the 4-digit year + +`:month` +: the 2-digit month + +`:monthname` +: the name of the month + +`:day` +: the 2-digit day + +`:weekday` +: the 1-digit day of the week (Sunday = 0) + +`:weekdayname` +: the name of the day of the week + +`:yearday` +: the 1- to 3-digit day of the year + +`:section` +: the content's section + +`:sections` +: the content's sections hierarchy + +`:title` +: the content's title + +`:slug` +: the content's slug (or title if no slug is provided in the front matter) + +`:filename` +: the content's filename (without extension) + +## Aliases + +For people migrating existing published content to Hugo, there's a good chance you need a mechanism to handle redirecting old URLs. + +Luckily, redirects can be handled easily with **aliases** in Hugo. + +### Example: Aliases + - Let's assume you create a new piece of content at `content/posts/my-awesome-blog-post.md`. The content is a revision of your previous post at `content/posts/my-original-url.md`. You can create an `aliases` field in the front matter of your new `my-awesome-blog-post.md` where you can add previous paths. The following examples show how to create this filed in TOML and YAML front matter, respectively. ++Let's assume you create a new piece of content at `content/posts/my-awesome-blog-post.md`. The content is a revision of your previous post at `content/posts/my-original-url.md`. You can create an `aliases` field in the front matter of your new `my-awesome-blog-post.md` where you can add previous paths. The following examples show how to create this field in TOML and YAML front matter, respectively. + +#### TOML Front Matter + +{{< code file="content/posts/my-awesome-post.md" copy="false" >}} ++++ +aliases = [ + "/posts/my-original-url/", + "/2010/01/01/even-earlier-url.html" +] ++++ +{{< /code >}} + +#### YAML Front Matter + +{{< code file="content/posts/my-awesome-post.md" copy="false" >}} +--- +aliases: + - /posts/my-original-url/ + - /2010/01/01/even-earlier-url.html +--- +{{< /code >}} + +Now when you visit any of the locations specified in aliases---i.e., *assuming the same site domain*---you'll be redirected to the page they are specified on. For example, a visitor to `example.com/posts/my-original-url/` will be immediately redirected to `example.com/posts/my-awesome-post/`. + +### Example: Aliases in Multilingual + +On [multilingual sites][multilingual], each translation of a post can have unique aliases. To use the same alias across multiple languages, prefix it with the language code. + +In `/posts/my-new-post.es.md`: + +``` +--- +aliases: + - /es/posts/my-original-post/ +--- +``` + +### How Hugo Aliases Work + +When aliases are specified, Hugo creates a directory to match the alias entry. Inside the directory, Hugo creates an `.html` file specifying the canonical URL for the page and the new redirect target. + +For example, a content file at `posts/my-intended-url.md` with the following in the front matter: + +``` +--- +title: My New post +aliases: [/posts/my-old-url/] +--- +``` + +Assuming a `baseURL` of `example.com`, the contents of the auto-generated alias `.html` found at `https://example.com/posts/my-old-url/` will contain the following: + +``` + + + + https://example.com/posts/my-intended-url + + + + + + +``` + +The `http-equiv="refresh"` line is what performs the redirect, in 0 seconds in this case. If an end user of your website goes to `https://example.com/posts/my-old-url`, they will now be automatically redirected to the newer, correct URL. The addition of `` lets search engine bots know that they should not crawl and index your new alias page. + +### Customize +You may customize this alias page by creating an `alias.html` template in the +layouts folder of your site (i.e., `layouts/alias.html`). In this case, the data passed to the template is + +`Permalink` +: the link to the page being aliased + +`Page` +: the Page data for the page being aliased + +### Important Behaviors of Aliases + +1. Hugo makes no assumptions about aliases. They also do not change based +on your UglyURLs setting. You need to provide absolute paths to your web root +and the complete filename or directory. +2. Aliases are rendered *before* any content are rendered and therefore will be overwritten by any content with the same location. + +## Pretty URLs + +Hugo's default behavior is to render your content with "pretty" URLs. No non-standard server-side configuration is required for these pretty URLs to work. + +The following demonstrates the concept: + +``` +content/posts/_index.md +=> example.com/posts/index.html +content/posts/post-1.md +=> example.com/posts/post-1/ +``` + +## Ugly URLs + - If you would like to have what are often referred to as "ugly URLs" (e.g., example.com/urls.html), set `uglyurls = true` or `uglyurls: true` in your site's `config.toml` or `config.yaml`, respectively. You can also use the `--uglyURLs=true` [flag from the command line][usage] with `hugo` or `hugo server`.. ++If you would like to have what are often referred to as "ugly URLs" (e.g., example.com/urls.html), set `uglyurls = true` or `uglyurls: true` in your site's `config.toml` or `config.yaml`, respectively. You can also use the `--uglyURLs=true` [flag from the command line][usage] with `hugo` or `hugo server`. + +If you want a specific piece of content to have an exact URL, you can specify this in the [front matter][] under the `url` key. The following are examples of the same content directory and what the eventual URL structure will be when Hugo runs with its default behavior. + +See [Content Organization][contentorg] for more details on paths. + +``` +. +└── 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/ +``` + +Here's the same organization run with `hugo --uglyURLs`: + +``` +. +└── content + └── about + | └── _index.md // <- https://example.com/about.html + ├── post + | ├── firstpost.md // <- https://example.com/post/firstpost.html + | ├── happy + | | └── ness.md // <- https://example.com/post/happy/ness.html + | └── secondpost.md // <- https://example.com/post/secondpost.html + └── quote + ├── first.md // <- https://example.com/quote/first.html + └── second.md // <- https://example.com/quote/second.html +``` + + +## Canonicalization + +By default, all relative URLs encountered in the input are left unmodified, e.g. `/css/foo.css` would stay as `/css/foo.css`. The `canonifyURLs` field in your site `config` has a default value of `false`. + +By setting `canonifyURLs` to `true`, all relative URLs would instead be *canonicalized* using `baseURL`. For example, assuming you have `baseURL = https://example.com/`, the relative URL `/css/foo.css` would be turned into the absolute URL `https://example.com/css/foo.css`. + +Benefits of canonicalization include fixing all URLs to be absolute, which may aid with some parsing tasks. Note, however, that all modern browsers handle this on the client without issue. + +Benefits of non-canonicalization include being able to have scheme-relative resource inclusion; e.g., so that `http` vs `https` can be decided according to how the page was retrieved. + +{{% note "`canonifyURLs` default change" %}} +In the May 2014 release of Hugo v0.11, the default value of `canonifyURLs` was switched from `true` to `false`, which we think is the better default and should continue to be the case going forward. Please verify and adjust your website accordingly if you are upgrading from v0.10 or older versions. +{{% /note %}} + +To find out the current value of `canonifyURLs` for your website, you may use the handy `hugo config` command added in v0.13. + +``` +hugo config | grep -i canon +``` + +Or, if you are on Windows and do not have `grep` installed: + +``` +hugo config | FINDSTR /I canon +``` + - ## Override URLS with Front Matter ++## Override URLs with Front Matter + +In addition to specifying permalink values in your site configuration for different content sections, Hugo provides even more granular control for individual pieces of content. + +Both `slug` and `url` can be defined in individual front matter. For more information on content destinations at build time, see [Content Organization][contentorg]. + +## Relative URLs + +By default, all relative URLs are left unchanged by Hugo, which can be problematic when you want to make your site browsable from a local file system. + +Setting `relativeURLs` to `true` in your [site configuration][config] will cause Hugo to rewrite all relative URLs to be relative to the current content. + +For example, if your `/post/first/` page contains a link to `/about/`, Hugo will rewrite the URL to `../../about/`. + +[config]: /getting-started/configuration/ +[contentorg]: /content-management/organization/ +[front matter]: /content-management/front-matter/ +[multilingual]: /content-management/multilingual/ +[sections]: /content-management/sections/ +[usage]: /getting-started/usage/ diff --cc docs/content/en/contribute/development.md index aafec411,00000000..be2ca4a2 mode 100644,000000..100644 --- a/docs/content/en/contribute/development.md +++ b/docs/content/en/contribute/development.md @@@ -1,416 -1,0 +1,416 @@@ +--- +title: Contribute to Hugo Development +linktitle: Development +description: Hugo relies heavily on contributions from the open source community. +date: 2017-02-01 +publishdate: 2017-02-01 +lastmod: 2017-02-01 +categories: [contribute] +keywords: [dev,open source] +authors: [digitalcraftsman] +menu: + docs: + parent: "contribute" + weight: 10 +weight: 10 +sections_weight: 10 +draft: false +aliases: [/contribute/development/] +toc: true +--- + +## Introduction + +Hugo is an open-source project and lives by the work of its [contributors][]. There are plenty of [open issues][issues], and we need your help to make Hugo even more awesome. You don't need to be a Go guru to contribute to the project's development. + +## Assumptions + +This contribution guide takes a step-by-step approach in hopes of helping newcomers. Therefore, we only assume the following: + +* You are new to Git or open-source projects in general +* You are a fan of Hugo and enthusiastic about contributing to the project + +{{% note "Additional Questions?" %}} +If you're struggling at any point in this contribution guide, reach out to the Hugo community in [Hugo's Discussion forum](https://discourse.gohugo.io). +{{% /note %}} + +## Install Go + +The installation of Go should take only a few minutes. You have more than one option to get Go up and running on your machine. + +If you are having trouble following the installation guides for Go, check out [Go Bootcamp, which contains setups for every platform][gobootcamp] or reach out to the Hugo community in the [Hugo Discussion Forums][forums]. + +### Install Go From Source + - [Download the latest stable version of Go][godl] and follow the official [Golang installation guide][goinstall]. ++[Download the latest stable version of Go][godl] and follow the official [Go installation guide][goinstall]. + +Once you're finished installing Go, let's confirm everything is working correctly. Open a terminal---or command line under Windows--and type the following: + +``` +go version +``` + +You should see something similar to the following written to the console. Note that the version here reflects the most recent version of Go as of the last update for this page: + +``` +go version go1.8 darwin/amd64 +``` + +Next, make sure that you set up your `GOPATH` [as described in the installation guide][setupgopath]. + +You can print the `GOPATH` with `echo $GOPATH`. You should see a non-empty string containing a valid path to your Go workspace; for example: + +``` +/Users//Code/go +``` + +### Install Go with Homebrew + +If you are a MacOS user and have [Homebrew](https://brew.sh/) installed on your machine, installing Go is as simple as the following command: + +{{< code file="install-go.sh" >}} +brew install go +{{< /code >}} + +### Install Go via GVM + +More experienced users can use the [Go Version Manager][gvm] (GVM). GVM allows you to switch between different Go versions *on the same machine*. If you're a beginner, you probably don't need this feature. However, GVM makes it easy to upgrade to a new released Go version with just a few commands. + +GVM comes in especially handy if you follow the development of Hugo over a longer period of time. Future versions of Hugo will usually be compiled with the latest version of Go. Sooner or later, you will have to upgrade if you want to keep up. + +## Create a GitHub Account + +If you're going to contribute code, you'll need to have an account on GitHub. Go to [www.github.com/join](https://github.com/join) and set up a personal account. + +## Install Git on Your System + +You will need to have Git installed on your computer to contribute to Hugo development. Teaching Git is outside the scope of the Hugo docs, but if you're looking for an excellent reference to learn the basics of Git, we recommend the [Git book][gitbook] if you are not sure where to begin. We will include short explainations of the Git commands in this document. + +Git is a [version control system](https://en.wikipedia.org/wiki/Version_control) to track the changes of source code. Hugo depends on smaller third-party packages that are used to extend the functionality. We use them because we don't want to reinvent the wheel. + +Go ships with a sub-command called `get` that will download these packages for us when we setup our working environment. The source code of the packages is tracked with Git. `get` will interact with the Git servers of the package hosters in order to fetch all dependencies. + +Move back to the terminal and check if Git is already installed. Type in `git version` and press enter. You can skip the rest of this section if the command returned a version number. Otherwise [download](https://git-scm.com/downloads) the latest version of Git and follow this [installation guide](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git). + +Finally, check again with `git version` if Git was installed successfully. + +### Git Graphical Front Ends + +There are several [GUI clients](https://git-scm.com/downloads/guis) that help you to operate Git. Not all are available for all operating systems and maybe differ in their usage. Because of this we will document how to use the command line, since the commands are the same everywhere. + +### Install Hub on Your System (Optional) + +Hub is a great tool for working with GitHub. The main site for it is [hub.github.com](https://hub.github.com/). Feel free to install this little Git wrapper. + +On a Mac, you can install [Hub](https://github.com/github/hub) using [Homebrew](https://brew.sh): + +``` +brew install hub +``` + +Now we'll create an [alias in Bash](http://tldp.org/LDP/abs/html/aliases.html) so that typing `git` actually runs `Hub`: + +``` +echo "alias git='hub'" >> ~/.bash_profile +``` + +Confirm the installation: + +``` +git version 2.6.3 +hub version 2.2.2 +``` + +## Set up your working copy + +You set up the working copy of the repository locally on your computer. Your local copy of the files is what you'll edit, compile, and end up pushing back to GitHub. The main steps are cloning the repository and creating your fork as a remote. + +### Clone the repository + +We assume that you've set up your `GOPATH` (see the section above if you're unsure about this). You should now copy the Hugo repository down to your computer. You'll hear this called "clone the repo". GitHub's [help pages](https://help.github.com/articles/cloning-a-repository/) give us a short explanation: + +> When you create a repository on GitHub, it exists as a remote repository. You can create a local clone of your repository on your computer and sync between the two locations. + +We're going to clone the [master Hugo repository](https://github.com/gohugoio/hugo). That seems counter-intuitive, since you won't have commit rights on it. But it's required for the Go workflow. You'll work on a copy of the master and push your changes to your own repository on GitHub. + +So, let's clone that master repository: + +``` +go get -v -u github.com/gohugoio/hugo +``` + +Hugo relies on [Testify](https://github.com/stretchr/testify) for testing Go code. If you don't already have it, get the Testify testing tools: + +``` +go get github.com/stretchr/testify +``` + +### Fork the repository + +If you're not familiar with this term, GitHub's [help pages](https://help.github.com/articles/fork-a-repo/) provide again a simple explanation: + +> A fork is a copy of a repository. Forking a repository allows you to freely experiment with changes without affecting the original project. + +#### Fork by hand + +Open the [Hugo repository](https://github.com/gohugoio/hugo) on GitHub and click on the "Fork" button in the top right. + +![Fork button](/images/contribute/development/forking-a-repository.png) + +Now open your fork repository on GitHub and copy the remote url of your fork. You can choose between HTTPS and SSH as protocol that Git should use for the following operations. HTTPS works always [if you're not sure](https://help.github.com/articles/which-remote-url-should-i-use/). + +![Copy remote url](/images/contribute/development/copy-remote-url.png) + +Switch back to the terminal and move into the directory of the cloned master repository from the last step. + +``` +cd $GOPATH/src/github.com/gohugoio/hugo +``` + +Now Git needs to know that our fork exists by adding the copied remote url: + +``` +git remote add +``` + +#### Fork with Hub + +Alternatively, you can use the Git wrapper Hub. Hub makes forking a repository easy: + +``` +git fork +``` + +That command will log in to GitHub using your account, create a fork of the repository that you're currently working in, and add it as a remote to your working copy. + +#### Trust, but verify + +Let's check if everything went right by listing all known remotes: + +``` +git remote -v +``` + +The output should look similar: + +``` +digitalcraftsman git@github.com:digitalcraftsman/hugo.git (fetch) +digitalcraftsman git@github.com:digitalcraftsman/hugo.git (push) +origin https://github.com/gohugoio/hugo (fetch) +origin https://github.com/gohugoio/hugo (push) +``` + +## The Hugo Git Contribution Workflow + +### Create a new branch + +You should never develop against the "master" branch. The development team will not accept a pull request against that branch. Instead, create a descriptive named branch and work on it. + +First, you should always pull the latest changes from the master repository: + +``` +git checkout master +git pull +``` + +Now we can create a new branch for your additions: + +``` +git checkout -b +``` + +You can check on which branch you are with `git branch`. You should see a list of all local branches. The current branch is indicated with a little asterisk. + +### Contribute to Documentation + +Perhaps you want to start contributing to the Hugo docs. If so, you can ignore most of the following steps and focus on the `/docs` directory within your newly cloned repository. You can change directories into the Hugo docs using `cd docs`. + +You can start Hugo's built-in server via `hugo server`. Browse the documentation by entering [http://localhost:1313](http://localhost:1313) in the address bar of your browser. The server automatically updates the page whenever you change content. + +We have developed a [separate Hugo documentation contribution guide][docscontrib] for more information on how the Hugo docs are built, organized, and improved by the generosity of people like you. + +### Build Hugo + +While making changes in the codebase it's a good idea to build the binary to test them: + +``` +go build -o hugo main.go +``` + +### Test +Sometimes changes on the codebase can cause unintended side effects. Or they don't work as expected. Most functions have their own test cases. You can find them in files ending with `_test.go`. + +Make sure the commands `go test ./...` passes, and `go build` completes. + +### Formatting +The Go code styleguide maybe is opinionated but it ensures that the codebase looks the same, regardless who wrote the code. Go comes with its own formatting tool. Let's apply the styleguide to our addtions: + +``` +go fmt ./... +``` + +Once you made your additions commit your changes. Make sure that you follow our [code contribution guidelines](https://github.com/gohugoio/hugo/blob/master/CONTRIBUTING.md): + +``` +# Add all changed files +git add --all +git commit --message "YOUR COMMIT MESSAGE" +``` + +The commit message should describe what the commit does (e.g. add feature XYZ), not how it is done. + +### Modify commits + +You noticed some commit messages don't fulfill the code contribution guidelines or you just forget something to add some files? No problem. Git provides the necessary tools to fix such problems. The next two methods cover all common cases. + +If you are unsure what a command does leave the commit as it is. We can fix your commits later in the pull request. + +#### Modify the last commit + +Let's say you want to modify the last commit message. Run the following command and replace the current message: + +``` +git commit --amend -m"YOUR NEW COMMIT MESSAGE" +``` + +Take a look at the commit log to see the change: + +``` +git log +# Exit with q +``` + +After making the last commit you may have forgot something. There is no need to create a new commit. Just add the latest changes and merge them into the intended commit: + +``` +git add --all +git commit --amend +``` + +#### Modify multiple commits + +{{% warning "Be Careful Modifying Multiple Commits"%}} +Modifications such as those described in this section can have serious unintended consequences. Skip this section if you're not sure! +{{% /warning %}} + +This is a bit more advanced. Git allows you to [rebase](https://git-scm.com/docs/git-rebase) commits interactively. In other words: it allows you to rewrite the commit history. + +``` +git rebase --interactive @~6 +``` + +The `6` at the end of the command represents the number of commits that should be modified. An editor should open and present a list of last six commit messages: + +``` +pick 80d02a1 tpl: Add hasPrefix to the template funcs' "smoke test" +pick aaee038 tpl: Sort the smoke tests +pick f0dbf2c tpl: Add the other test case for hasPrefix +pick 911c35b Add "How to contribute to Hugo" tutorial +pick 33c8973 Begin workflow +pick 3502f2e Refactoring and typo fixes +``` + +In the case above we should merge the last to commits in the commit of this tutorial (`Add "How to contribute to Hugo" tutorial`). You can "squash" commits, i.e. merge two or more commits into a single one. + +All operations are written before the commit message. Replace "pick" with an operation. In this case `squash` or `s` for short: + +``` +pick 80d02a1 tpl: Add hasPrefix to the template funcs' "smoke test" +pick aaee038 tpl: Sort the smoke tests +pick f0dbf2c tpl: Add the other test case for hasPrefix +pick 911c35b Add "How to contribute to Hugo" tutorial +squash 33c8973 Begin workflow +squash 3502f2e Refactoring and typo fixes +``` + +We also want to rewrite the commits message of the third last commit. We forgot "docs:" as prefix according to the code contribution guidelines. The operation to rewrite a commit is called `reword` (or `r` as shortcut). + +You should end up with a similar setup: + +``` +pick 80d02a1 tpl: Add hasPrefix to the template funcs' "smoke test" +pick aaee038 tpl: Sort the smoke tests +pick f0dbf2c tpl: Add the other test case for hasPrefix +reword 911c35b Add "How to contribute to Hugo" tutorial +squash 33c8973 Begin workflow +squash 3502f2e Refactoring and typo fixes +``` + +Close the editor. It should open again with a new tab. A text is instructing you to define a new commit message for the last two commits that should be merged (aka "squashed"). Save the file with CTRL+S and close the editor again. + +A last time a new tab opens. Enter a new commit message and save again. Your terminal should contain a status message. Hopefully this one: + +``` +Successfully rebased and updated refs/heads/. +``` + +Check the commit log if everything looks as expected. Should an error occur you can abort this rebase with `git rebase --abort`. + +### Push commits + +To push our commits to the fork on GitHub we need to specify a destination. A destination is defined by the remote and a branch name. Earlier, the defined that the remote url of our fork is the same as our GitHub handle, in my case `digitalcraftsman`. The branch should have the same as our local one. This makes it easy to identify corresponding branches. + +``` +git push --set-upstream +``` + +Now Git knows the destination. Next time when you to push commits you just need to enter `git push`. + +If you modified your commit history in the last step GitHub will reject your try to push. This is a safety-feature because the commit history isn't the same and new commits can't be appended as usual. You can enforce this push explicitly with `git push --force`. + +## Open a pull request + +We made a lot of progress. Good work. In this step we finally open a pull request to submit our additions. Open the [Hugo master repository](https://github.com/gohugoio/hugo/) on GitHub in your browser. + +You should find a green button labeled with "New pull request". But GitHub is clever and probably suggests you a pull request like in the beige box below: + +![Open a pull request](/images/contribute/development/open-pull-request.png) + +The new page summaries the most important information of your pull request. Scroll down and you find the additions of all your commits. Make sure everything looks as expected and click on "Create pull request". + +### Accept the contributor license agreement + +Last but not least you should accept the contributor license agreement (CLA). A new comment should be added automatically to your pull request. Click on the yellow badge, accept the agreement and authenticate yourself with your GitHub account. It just takes a few clicks and only needs to be done once. + +![Accept the CLA](/images/contribute/development/accept-cla.png) + +### Automatic builds + +We use the [Travis CI loop](https://travis-ci.org/gohugoio/hugo) (Linux and OS X) and [AppVeyor](https://ci.appveyor.com/project/gohugoio/hugo/branch/master) (Windows) to compile Hugo with your additions. This should ensure that everything works as expected before merging your pull request. This in most cases only relevant if you made changes to the codebase of Hugo. + +![Automic builds and their status](/images/contribute/development/ci-errors.png) + +Above you can see that Travis wasn't able to compile the changes in this pull request. Click on "Details" and try to investigate why the build failed. But it doesn't have to be your fault. Mostly, the `master` branch that we used as foundation for your pull request should build without problems. + +If you have questions, leave a comment in the pull request. We are willing to assist you. + +## Where to start? + +Thank you for reading through this contribution guide. Hopefully, we will see you again soon on GitHub. There are plenty of [open issues][issues] for you to help with. + +Feel free to [open an issue][newissue] if you think you found a bug or you have a new idea to improve Hugo. We are happy to hear from you. + - ## Additional References for Learning Git and Golang ++## Additional References for Learning Git and Go + +* [Codecademy's Free "Learn Git" Course][codecademy] (Free) +* [Code School and GitHub's "Try Git" Tutorial][trygit] (Free) +* [The Git Book][gitbook] (Free) +* [Go Bootcamp][gobootcamp] +* [GitHub Pull Request Tutorial, Thinkful][thinkful] + + +[codecademy]: https://www.codecademy.com/learn/learn-git +[contributors]: https://github.com/gohugoio/hugo/graphs/contributors +[docscontrib]: /contribute/documentation/ +[forums]: https://discourse.gohugo.io +[gitbook]: https://git-scm.com/ +[gobootcamp]: http://www.golangbootcamp.com/book/get_setup +[godl]: https://golang.org/dl/ +[goinstall]: https://golang.org/doc/install +[gvm]: https://github.com/moovweb/gvm +[issues]: https://github.com/gohugoio/hugo/issues +[newissue]: https://github.com/gohugoio/hugo/issues/new +[releases]: /getting-started/ +[setupgopath]: https://golang.org/doc/code.html#Workspaces +[thinkful]: https://www.thinkful.com/learn/github-pull-request-tutorial/ +[trygit]: https://try.github.io/levels/1/challenges/1 diff --cc docs/content/en/functions/findRe.md index 23817c57,00000000..743c8542 mode 100644,000000..100644 --- a/docs/content/en/functions/findRe.md +++ b/docs/content/en/functions/findRe.md @@@ -1,47 -1,0 +1,47 @@@ +--- +title: findRE +description: Returns a list of strings that match the regular expression. +godocref: +date: 2017-02-01 +publishdate: 2017-02-01 +lastmod: 2017-02-01 +categories: [functions] +menu: + docs: + parent: "functions" +keywords: [regex] +signature: ["findRE PATTERN INPUT [LIMIT]"] +workson: [] +hugoversion: +relatedfuncs: [] +deprecated: false +aliases: [] +--- + + +By default all matches will be included. The number of matches can be limitted with an optional third parameter. + +The example below returns a list of all second level headers (`

`) in the content: + +``` +{{ findRE "(.|\n)*?

" .Content }} +``` + +You can limit the number of matches in the list with a third parameter. The following example shows how to limit the returned value to just one match (or none, if there are no matched substrings): + +``` +{{ findRE "(.|\n)*?" .Content 1 }} + +``` + +{{% note %}} - Hugo uses Golang's [Regular Expression package](https://golang.org/pkg/regexp/), which is the same general syntax used by Perl, Python, and other languages but with a few minor differences for those coming from a background in PCRE. For a full syntax listing, see the [GitHub wiki for re2](https://github.com/google/re2/wiki/Syntax). ++Hugo uses Go's [Regular Expression package](https://golang.org/pkg/regexp/), which is the same general syntax used by Perl, Python, and other languages but with a few minor differences for those coming from a background in PCRE. For a full syntax listing, see the [GitHub wiki for re2](https://github.com/google/re2/wiki/Syntax). + - If you are just learning RegEx, or at least Golang's flavor, you can practice pattern matching in the browser at . ++If you are just learning RegEx, or at least Go's flavor, you can practice pattern matching in the browser at . +{{% /note %}} + + +[partials]: /templates/partials/ +[`plainify`]: /functions/plainify/ +[toc]: /content-management/toc/ +[`urlize`]: /functions/urlize diff --cc docs/content/en/functions/format.md index 1d498cc3,00000000..fef4d85d mode 100644,000000..100644 --- a/docs/content/en/functions/format.md +++ b/docs/content/en/functions/format.md @@@ -1,123 -1,0 +1,123 @@@ +--- +title: .Format +description: Formats built-in Hugo dates---`.Date`, `.PublishDate`, and `.Lastmod`---according to Go's layout string. +godocref: https://golang.org/pkg/time/#example_Time_Format +date: 2017-02-01 +publishdate: 2017-02-01 +lastmod: 2017-02-01 +categories: [functions] +menu: + docs: + parent: "functions" +keywords: [dates,time] +signature: [".Format FORMAT"] +workson: [times] +hugoversion: +relatedfuncs: [dateFormat,now,Unix,time] +deprecated: false +aliases: [] +toc: true +--- + +`.Format` will format date values defined in your front matter and can be used as a property on the following [page variables][pagevars]: + +* `.PublishDate` +* `.Date` +* `.Lastmod` + +Assuming a key-value of `date: 2017-03-03` in a content file's front matter, your can run the date through `.Format` followed by a layout string for your desired output at build time: + +``` +{{ .PublishDate.Format "January 2, 2006" }} => March 3, 2017 +``` + - For formatting *any* string representations of dates defined in your front matter, see the [`dateFormat` function][dateFormat], which will still leverage the Golang layout string explained below but uses a slightly different syntax. ++For formatting *any* string representations of dates defined in your front matter, see the [`dateFormat` function][dateFormat], which will still leverage the Go layout string explained below but uses a slightly different syntax. + +## Go's Layout String + +Hugo templates [format your dates][time] via layout strings that point to a specific reference time: + +``` +Mon Jan 2 15:04:05 MST 2006 +``` + +While this may seem arbitrary, the numerical value of `MST` is `07`, thus making the layout string a sequence of numbers. + +Here is a visual explanation [taken directly from the Go docs][gdex]: + +``` + Jan 2 15:04:05 2006 MST +=> 1 2 3 4 5 6 -7 +``` + +### Hugo Date and Time Templating Reference + +The following examples show the layout string followed by the rendered output. + +The examples were rendered and tested in [CST][] and all point to the same field in a content file's front matter: + +``` +date: 2017-03-03T14:15:59-06:00 +``` + +`.Date` (i.e. called via [page variable][pagevars]) +: **Returns**: `2017-03-03 14:15:59 -0600 CST` + +`"Monday, January 2, 2006"` +: **Returns**: `Friday, March 3, 2017` + +`"Mon Jan 2 2006"` +: **Returns**: `Fri Mar 3 2017` + +`"January 2006"` +: **Returns**: `March 2017` + +`"2006-01-02"` +: **Returns**: `2017-03-03` + +`"Monday"` +: **Returns**: `Friday` + +`"02 Jan 06 15:04 MST"` (RFC822) +: **Returns**: `03 Mar 17 14:15 CST` + +`"02 Jan 06 15:04 -0700"` (RFC822Z) +: **Returns**: `03 Mar 17 14:15 -0600` + +`"Mon, 02 Jan 2006 15:04:05 MST"` (RFC1123) +: **Returns**: `Fri, 03 Mar 2017 14:15:59 CST` + +`"Mon, 02 Jan 2006 15:04:05 -0700"` (RFC339) +: **Returns**: `Fri, 03 Mar 2017 14:15:59 -0600` + +### Cardinal Numbers and Ordinal Abbreviations + +Spelled-out cardinal numbers (e.g. "one", "two", and "three") and ordinal abbreviations (i.e., with shorted suffixes like "1st", "2nd", and "3rd") are not currently supported: + +``` +{{.Date.Format "Jan 2nd 2006"}} +``` + +Hugo assumes you want to append `nd` as a string to the day of the month and outputs the following: + +``` +Mar 3nd 2017 +``` + + + +### Use `.Local` and `.UTC` + +In conjunction with the [`dateFormat` function][dateFormat], you can also convert your dates to `UTC` or to local timezones: + +`{{ dateFormat "02 Jan 06 15:04 MST" .Date.UTC }}` +: **Returns**: `03 Mar 17 20:15 UTC` + +`{{ dateFormat "02 Jan 06 15:04 MST" .Date.Local }}` +: **Returns**: `03 Mar 17 14:15 CST` + +[CST]: https://en.wikipedia.org/wiki/Central_Time_Zone +[dateFormat]: /functions/dateformat/ +[gdex]: https://golang.org/pkg/time/#example_Time_Format +[pagevars]: /variables/page/ +[time]: https://golang.org/pkg/time/ diff --cc docs/content/en/functions/len.md index b8e380e4,00000000..e054ed5f mode 100644,000000..100644 --- a/docs/content/en/functions/len.md +++ b/docs/content/en/functions/len.md @@@ -1,60 -1,0 +1,60 @@@ +--- +title: len +linktitle: len +description: Returns the length of a variable according to its type. +godocref: https://golang.org/pkg/builtin/#len +date: 2017-02-01 +publishdate: 2017-02-01 +lastmod: 2017-04-18 +categories: [functions] +keywords: [] +signature: ["len INPUT"] +workson: [lists,taxonomies,terms] +hugoversion: +relatedfuncs: [] +deprecated: false +toc: false +aliases: [] +--- + - `len` is a built-in function in Golang that returns the length of a variable according to its type. From the Golang documentation: ++`len` is a built-in function in Go that returns the length of a variable according to its type. From the Go documentation: + +> Array: the number of elements in v. +> +> Pointer to array: the number of elements in *v (even if v is nil). +> +> Slice, or map: the number of elements in v; if v is nil, len(v) is zero. +> +> String: the number of bytes in v. +> +> Channel: the number of elements queued (unread) in the channel buffer; if v is nil, len(v) is zero. + +`len` is also considered a [fundamental function for Hugo templating][]. + +## `len` Example 1: Longer Headings + +You may want to append a class to a heading according to the length of the string therein. The following templating checks to see if the title's length is greater than 80 characters and, if so, adds a `long-title` class to the `

`: + +{{< code file="check-title-length.html" >}} +
+ {{.Title}}

+ +{{< /code >}} + +## `len` Example 2: Counting Pages with `where` + +The following templating uses [`where`][] in conjunction with `len` to figure out the total number of content pages in a `posts` [section][]: + +{{< code file="how-many-posts.html" >}} +{{ $posts := (where .Site.RegularPages "Section" "==" "post") }} +{{ $postCount := len $posts }} +{{< /code >}} + +Note the use of `.RegularPages`, a [site variable][] that counts all regular content pages but not the `_index.md` pages used to add front matter and content to [list templates][]. + + +[fundamental function for Hugo templating]: /templates/introduction/ +[list templates]: /templates/lists/ +[section]: /content-management/sections/ +[site variable]: /variables/site/ - [`where`]: /functions/where/ ++[`where`]: /functions/where/ diff --cc docs/content/en/functions/now.md index 8c706835,00000000..ae8213d0 mode 100644,000000..100644 --- a/docs/content/en/functions/now.md +++ b/docs/content/en/functions/now.md @@@ -1,50 -1,0 +1,50 @@@ +--- +title: now +linktitle: now +description: Returns the current local time +godocref: https://godoc.org/time#Time +date: 2017-02-01 +publishdate: 2017-02-01 +lastmod: 2017-04-30 +categories: [functions] +menu: + docs: + parent: "functions" +keywords: [dates,time] +signature: ["now"] +workson: [] +hugoversion: +relatedfuncs: [Unix,dateFormat] +deprecated: false +aliases: [] +--- + +See [`time.Time`](https://godoc.org/time#Time). + +For example, building your site on June 24, 2017, with the following templating: + +``` +
+ © {{ now.Format "2006"}} +
+``` + +would produce the following: + +``` +
+ © 2017 +
+``` + - The above example uses the [`.Format` function](/functions/format), which page includes a full listing of date formatting using Golang's layout string. ++The above example uses the [`.Format` function](/functions/format), which page includes a full listing of date formatting using Go's layout string. + +{{% note %}} +Older Hugo themes may still be using the obsolete Page’s `.Now` (uppercase with leading dot), which causes build error that looks like the following: + + ERROR ... Error while rendering "..." in "...": ... + executing "..." at <.Now.Format>: + can't evaluate field Now in type *hugolib.PageOutput + +Be sure to use `now` (lowercase with _**no**_ leading dot) in your templating. +{{% /note %}} diff --cc docs/content/en/functions/replacere.md index 0571c92b,00000000..9c2778b5 mode 100644,000000..100644 --- a/docs/content/en/functions/replacere.md +++ b/docs/content/en/functions/replacere.md @@@ -1,31 -1,0 +1,31 @@@ +--- +title: replaceRE +# linktitle: replaceRE +description: Replaces all occurrences of a regular expression with the replacement pattern. +godocref: +date: 2017-02-01 +publishdate: 2017-02-01 +lastmod: 2017-04-30 +categories: [functions] +menu: + docs: + parent: "functions" +keywords: [regex] +signature: ["replaceRE PATTERN REPLACEMENT INPUT"] +workson: [] +hugoversion: +relatedfuncs: [] +deprecated: false +aliases: [] +--- + +``` +{{ replaceRE "^https?://([^/]+).*" "$1" "http://gohugo.io/docs" }}` → "gohugo.io" +{{ "http://gohugo.io/docs" | replaceRE "^https?://([^/]+).*" "$1" }}` → "gohugo.io" +``` + +{{% note %}} - Hugo uses Golang's [Regular Expression package](https://golang.org/pkg/regexp/), which is the same general syntax used by Perl, Python, and other languages but with a few minor differences for those coming from a background in PCRE. For a full syntax listing, see the [GitHub wiki for re2](https://github.com/google/re2/wiki/Syntax). ++Hugo uses Go's [Regular Expression package](https://golang.org/pkg/regexp/), which is the same general syntax used by Perl, Python, and other languages but with a few minor differences for those coming from a background in PCRE. For a full syntax listing, see the [GitHub wiki for re2](https://github.com/google/re2/wiki/Syntax). + - If you are just learning RegEx, or at least Golang's flavor, you can practice pattern matching in the browser at . ++If you are just learning RegEx, or at least Go's flavor, you can practice pattern matching in the browser at . +{{% /note %}} diff --cc docs/content/en/getting-started/configuration.md index 518e4a2c,00000000..ea21fa5c mode 100644,000000..100644 --- a/docs/content/en/getting-started/configuration.md +++ b/docs/content/en/getting-started/configuration.md @@@ -1,404 -1,0 +1,407 @@@ +--- +title: Configure Hugo +linktitle: Configuration +description: How to configure your Hugo site. +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 +--- + +Hugo uses the `config.toml`, `config.yaml`, or `config.json` (if found in the +site root) as the default site config file. + +The user can choose to override that default with one or more site config files +using the command line `--config` switch. + +Examples: + +``` +hugo --config debugconfig.toml +hugo --config a.toml,b.toml,c.toml +``` + +{{% note %}} +Multiple site config files can be specified as a comma-separated string to the `--config` switch. +{{% /note %}} + +## All Configuration Settings + +The following is the full list of Hugo-defined variables with their default +value in parentheses. Users may choose to override those values in their site +config file(s). + +archetypeDir ("archetypes") +: The directory where Hugo finds archetype files (content templates). + +baseURL +: Hostname (and path) to the root, e.g. http://bep.is/ + +blackfriday +: See [Configure Blackfriday](/getting-started/configuration/#configure-blackfriday) + +buildDrafts (false) +: Include drafts when building. + +buildExpired (false) +: Include content already expired. + +buildFuture (false) +: Include content with publishdate in the future. + +canonifyURLs (false) +: Enable to turn relative URLs into absolute. + +contentDir ("content") +: The directory from where Hugo reads content files. + +dataDir ("data") +: The directory from where Hugo reads data files. + +defaultContentLanguage ("en") +: Content without language indicator will default to this language. + +defaultContentLanguageInSubdir (false) +: Render the default content language in subdir, e.g. `content/en/`. The site root `/` will then redirect to `/en/`. + +disableHugoGeneratorInject (false) +: Hugo will, by default, inject a generator meta tag in the HTML head on the _home page only_. You can turn it off, but we would really appreciate if you don't, as this is a good way to watch Hugo's popularity on the rise. + +disableKinds ([]) +: Enable disabling of all pages of the specified *Kinds*. Allowed values in this list: `"page"`, `"home"`, `"section"`, `"taxonomy"`, `"taxonomyTerm"`, `"RSS"`, `"sitemap"`, `"robotsTXT"`, `"404"`. + +disableLiveReload (false) +: Disable automatic live reloading of browser window. + +disablePathToLower (false) +: Do not convert the url/path to lowercase. + +enableEmoji (false) +: Enable Emoji emoticons support for page content; see the [Emoji Cheat Sheet](https://www.webpagefx.com/tools/emoji-cheat-sheet/). + +enableGitInfo (false) +: Enable `.GitInfo` object for each page (if the Hugo site is versioned by Git). This will then update the `Lastmod` parameter for each page using the last git commit date for that content file. + +enableMissingTranslationPlaceholders (false) +: Show a placeholder instead of the default value or an empty string if a translation is missing. + +enableRobotsTXT (false) +: Enable generation of `robots.txt` file. + +frontmatter + +: See [Front matter Configuration](#configure-front-matter). + +footnoteAnchorPrefix ("") +: Prefix for footnote anchors. + +footnoteReturnLinkContents ("") +: Text to display for footnote return links. + +googleAnalytics ("") +: Google Analytics tracking ID. + +hasCJKLanguage (false) +: If true, auto-detect Chinese/Japanese/Korean Languages in the content. This will make `.Summary` and `.WordCount` behave correctly for CJK languages. + +imaging +: See [Image Processing Config](/content-management/image-processing/#image-processing-config). + +languages +: See [Configure Languages](/content-management/multilingual/#configure-languages). + +languageCode ("") +: The site's language code. + +disableLanguages +: See [Disable a Language](/content-management/multilingual/#disable-a-language) + +layoutDir ("layouts") +: The directory from where Hugo reads layouts (templates). + +log (false) +: Enable logging. + +logFile ("") +: Log File path (if set, logging enabled automatically). + +menu +: See [Add Non-content Entries to a Menu](/content-management/menus/#add-non-content-entries-to-a-menu). + +metaDataFormat ("toml") +: Front matter meta-data format. Valid values: `"toml"`, `"yaml"`, or `"json"`. + +newContentEditor ("") +: The editor to use when creating new content. + +noChmod (false) +: Don't sync permission mode of files. + +noTimes (false) +: Don't sync modification time of files. + +paginate (10) +: Default number of pages per page in [pagination](/templates/pagination/). + +paginatePath ("page") +: The path element used during pagination (https://example.com/page/2). + +permalinks +: See [Content Management](/content-management/urls/#permalinks). + +pluralizeListTitles (true) +: Pluralize titles in lists. + +preserveTaxonomyNames (false) +: Preserve special characters in taxonomy names ("Gérard Depardieu" vs "Gerard Depardieu"). + +publishDir ("public") +: The directory to where Hugo will write the final static site (the HTML files etc.). + +pygmentsCodeFencesGuessSyntax (false) +: Enable syntax guessing for code fences without specified language. + +pygmentsStyle ("monokai") +: Color-theme or style for syntax highlighting. See [Pygments Color Themes](https://help.farbox.com/pygments.html). + +pygmentsUseClasses (false) +: Enable using external CSS for syntax highlighting. + +related +: See [Related Content](/content-management/related/#configure-related-content). + +relativeURLs (false) +: Enable this to make all relative URLs relative to content root. Note that this does not affect absolute URLs. + +rssLimit (unlimited) +: Maximum number of items in the RSS feed. + +sectionPagesMenu ("") +: See ["Section Menu for Lazy Bloggers"](/templates/menu-templates/#section-menu-for-lazy-bloggers). + +sitemap +: Default [sitemap configuration](/templates/sitemap-template/#configure-sitemap-xml). + +staticDir ("static") +: Relative directory from where Hugo reads static files. + +stepAnalysis (false) +: Display memory and timing of different steps of the program. + +summaryLength (70) +: The length of text to show in a [`.Summary`](/content-management/summaries/#hugo-defined-automatic-summary-splitting). + +taxonomies +: See [Configure Taxonomies](/content-management/taxonomies#configure-taxonomies). + +theme ("") +: Theme to use (located by default in `/themes/THEMENAME/`). + +themesDir ("themes") +: The directory where Hugo reads the themes from. + ++timeout (10000) ++: Timeout for generating page contents, in milliseconds (defaults to 10 seconds). *Note:* this is used to bail out of recursive content generation, if your pages are slow to generate (e.g., because they require large image processing or depend on remote contents) you might need to raise this limit. ++ +title ("") +: Site title. + +uglyURLs (false) +: When enabled, creates URL of the form `/filename.html` instead of `/filename/`. + +verbose (false) +: Enable verbose output. + +verboseLog (false) +: Enable verbose logging. + +watch (false) +: Watch filesystem for changes and recreate as needed. + +{{% 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 %}} + +## 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. + + +## Example Configuration + +The following is a typical example of a configuration file. The values nested under `params:` will populate the [`.Site.Params`][] variable for use in [templates][]: + +{{< code-toggle file="config">}} +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-toggle >}} + +## Configure with Environment 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 +``` + +This is really useful if you use a service such as Netlify to deploy your site. Look at the Hugo docs [Netlify configuration file](https://github.com/gohugoio/hugoDocs/blob/master/netlify.toml) for an example. + +{{% 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 %}} + +{{< todo >}} +Test and document setting params via JSON env var. +{{< /todo >}} + +## 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 Front Matter + +### Configure Dates + +Dates are important in Hugo, and you can configure how Hugo assigns dates to your content pages. You do this by adding a `frontmatter` section to your `config.toml`. + + +The default configuration is: + +```toml +[frontmatter] +date = ["date","publishDate", "lastmod"] +lastmod = [":git" "lastmod", "date","publishDate"] +publishDate = ["publishDate", "date"] +expiryDate = ["expiryDate"] +``` + +If you, as an example, have a non-standard date parameter in some of your content, you can override the setting for `date`: + + ```toml +[frontmatter] +date = [ "myDate", ":default"] +``` + +The `:default` is a shortcut to the default settings. The above will set `.Date` to the date value in `myDate` if present, if not we will look in `date`,`publishDate`, `lastmod` and pick the first valid date. + +In the list to the right, values starting with ":" are date handlers with a special meaning (see below). The others are just names of date parameters (case insensitive) in your front matter configuration. Also note that Hugo have some built-in aliases to the above: `lastmod` => `modified`, `publishDate` => `pubdate`, `published` and `expiryDate` => `unpublishdate`. With that, as an example, using `pubDate` as a date in front matter, will, by default, be assigned to `.PublishDate`. + +The special date handlers are: + + +`:fileModTime` +: Fetches the date from the content file's last modification timestamp. + +An example: + + ```toml +[frontmatter] +lastmod = ["lastmod" ,":fileModTime", ":default"] +``` + + +The above will try first to extract the value for `.Lastmod` starting with the `lastmod` front matter parameter, then the content file's modification timestamp. The last, `:default` should not be needed here, but Hugo will finally look for a valid date in `:git`, `date` and then `publishDate`. + + +`:filename` +: Fetches the date from the content file's filename. For example, `218-02-22-mypage.md` will extract the date `218-02-22`. Also, if `slug` is not set, `mypage` will be used as the value for `.Slug`. + +An example: + +```toml +[frontmatter] +date = [":filename", ":default"] +``` + +The above will try first to extract the value for `.Date` from the filename, then it will look in front matter parameters `date`, `publishDate` and lastly `lastmod`. + + +`:git` +: This is the Git author date for the last revision of this content file. This will only be set if `--enableGitInfo` is set or `enableGitInfo = true` is set in site config. + +## 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/en/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-toggle file="config" >}} +[blackfriday] + angledQuotes = true + fractions = false + plainIDAnchors = true + extensions = ["hardLineBreak"] +{{< /code-toggle >}} + +## 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/en/hosting-and-deployment/deployment-with-nanobox.md index 245e9544,00000000..1ab77c40 mode 100644,000000..100644 --- a/docs/content/en/hosting-and-deployment/deployment-with-nanobox.md +++ b/docs/content/en/hosting-and-deployment/deployment-with-nanobox.md @@@ -1,249 -1,0 +1,249 @@@ +--- +title: Host-Agnostic Deploys with Nanobox +linktitle: Host-Agnostic Deploys with Nanobox +description: Easily deploy Hugo to AWS, DigitalOcean, Google, Azure, and more... +date: 2017-08-24 +publishdate: 2017-08-24 +lastmod: 2017-08-24 +categories: [hosting and deployment] +keywords: [nanobox,deployment,hosting,aws,digitalocean,azure,google,linode] +authors: [Steve Domino] +menu: + docs: + parent: "hosting-and-deployment" + weight: 05 +weight: 05 +sections_weight: 05 +draft: false +aliases: [/tutorials/deployment-with-nanobox/] +toc: true +--- + +![hugo with nanobox](/images/hosting-and-deployment/deployment-with-nanobox/hugo-with-nanobox.png) + +Nanobox provides an entire end-to-end workflow for developing and deploying applications. Using Nanobox to deploy also means you'll use it to develop your application. + +{{% note %}} +If you're already using Nanobox and just need deployment instructions, you can skip to [Deploying Hugo with Nanobox](#deploying-hugo-with-nanobox) +{{% /note %}} + + +## What You'll Need + - With Nanobox you don't need to worry about having Golang or Hugo installed. They'll be installed as part of the development environment created for you. ++With Nanobox you don't need to worry about having Go or Hugo installed. They'll be installed as part of the development environment created for you. + +To get started you'll just need the following three items: + +* [A Nanobox Account](https://nanobox.io) - Signup is free +* [Nanobox Desktop](https://dashboard.nanobox.io/download) - The free desktop development tool +* An account with a hosting provider such as: + - [AWS](https://docs.nanobox.io/providers/hosting-accounts/aws/) + - [Google](https://docs.nanobox.io/providers/hosting-accounts/gcp/) + - [Azure](https://docs.nanobox.io/providers/hosting-accounts/azure/) + - [DigitalOcean](https://docs.nanobox.io/providers/hosting-accounts/digitalocean/) + - [Linode](https://docs.nanobox.io/providers/hosting-accounts/linode/) + - [More...](https://docs.nanobox.io/providers/hosting-accounts/) + - [Roll Your Own](https://docs.nanobox.io/providers/create/) + +### Before You Begin + +There are a few things to get out of the way before diving into the guide. To deploy, you'll need to make sure you have connected a host account to your Nanobox account, and launched a new application. + +#### Connect a Host Account + +Nanobox lets you choose where to host your application (AWS, DigitalOcean, Google, Azure, etc.). In the [Hosting Accounts](https://dashboard.nanobox.io/provider_accounts) section of your Nanobox dashboard [link your Nanobox account with your host](https://docs.nanobox.io/providers/hosting-accounts/). + +#### Launch a New Application on Nanobox + +[Launching a new app on Nanobox](https://docs.nanobox.io/workflow/launch-app/) is very simple. Navigate to [Launch New App](https://dashboard.nanobox.io/apps/new) in the dashboard, and follow the steps there. You'll be asked to name your app, and to select a host and region. + +With those out of the way you're ready to get started! + + +## Getting Started + +{{% note %}} +If you already have a functioning Hugo app, you can skip to [Configure Hugo to run with Nanobox](#configure-hugo-to-run-with-nanobox) +{{% /note %}} + +To get started, all you'll need is an empty project directory. Create a directory wherever you want your application to live and `cd` into it: + +`mkdir path/to/project && cd path/to/project` + +### Configure Hugo to run with Nanobox + +Nanobox uses a simple config file known as a [boxfile.yml](https://docs.nanobox.io/boxfile/) to describe your application's infrastructure. In the root of your project add the following `boxfile.yml`: + +{{< code file="boxfile.yml" >}} +run.config: + + # use the static engine + engine: static + engine.config: + + # tell the engine where to serve static assets from + rel_dir: public + + # enable file watching for live reload + fs_watch: true + + # install hugo + extra_steps: + - bash ./install.sh + +deploy.config: + + # generate site on deploy + extra_steps: + - hugo + +{{< /code >}} + +{{% note %}} +If you already have a functioning Hugo app, after adding the boxfile, you can skip to [Deploying Hugo with Nanobox](#deploying-hugo-with-nanobox). +{{% /note %}} + +### Installing Hugo + +Nanobox uses Docker to create instant, isolated, development environments. Because of this, you'll need to make sure that during development you have Hugo available. + +Do this by adding a custom install script at the root of your project that will install Hugo automatically for you: + +{{< code file="install.sh" >}} + +#!/bin/bash + +if [[ ! -f /data/bin/hugo ]]; then + cd /tmp + wget https://github.com/gohugoio/hugo/releases/download/v0.31.1/hugo_0.31.1_Linux-64bit.tar.gz + tar -xzf hugo_0.31.1_Linux-64bit.tar.gz + mv hugo /data/bin/hugo + cd - + rm -rf /tmp/* +fi + +{{< /code >}} + +{{% note %}} +If the install script fails during `nanobox run` you may need to make it executable with `chmod +x install.sh` +{{% /note %}} +{{% note %}} +Make sure to check the version of Hugo you have installed and update the install script to match. +{{% /note %}} + +### Generating a New Hugo App + - You'll generate your new application from inside the Nanobox VM (this is why you don't need to worry about having Golang or Hugo installed). ++You'll generate your new application from inside the Nanobox VM (this is why you don't need to worry about having Go or Hugo installed). + +Run the following command to drop into a Nanobox console (inside the VM) where your codebase is mounted: + +``` +nanobox run +``` + +![nanobox run](/images/hosting-and-deployment/deployment-with-nanobox/nanobox-run.png) + +Once inside the console use the following steps to create a new Hugo application: + +``` +# cd into the /tmp dir to create an app +cd /tmp + +# generate the hugo app +hugo new site app + +# cd back into the /app dir +cd - + +# copy the generated app into the project +shopt -s dotglob +cp -a /tmp/app/* . +``` + +### Install a theme + +`cd` into the `themes` directory and clone the `nanobox-hugo-theme` repo: + +``` +cd themes +git clone https://github.com/sdomino/nanobox-hugo-theme +``` + +To use the theme *either* copy the entire `config.toml` that comes with the theme, or just add the theme to your existing `config.toml` + +``` +# copy the config.toml that comes with the theme +cp ./themes/nanobox-hugo-theme/config.toml config.toml + +# or, add it to your existing config.toml +theme = "nanobox-hugo-theme" +``` + +{{% note %}} +It is not intended that you use the `nanobox-hugo-theme` as your actual theme. It's simply a theme to start with and should be replaced. +{{% /note %}} + +### View Your App + +To view your application simply run the following command from a Nanobox console: + +``` +hugo server --bind="0.0.0.0" --baseUrl=$APP_IP +``` + +![hugo server](/images/hosting-and-deployment/deployment-with-nanobox/hugo-server.png) + +With that you should be able to visit your app at the given IP:1313 address + +{{% note %}} +You can [add a custom DNS alias](https://docs.nanobox.io/cli/dns/#add) to make it easier to access your app. Run `nanobox dns add local hugo.dev`. After starting your server, visit your app at [hugo.dev:1313](http://hugo.dev:1313) +{{% /note %}} + +### Develop, Develop, Develop + +{{% note %}} +IMPORTANT: One issue we are aware of, and actively investigating, is livereload. Currently, livereload does not work when developing Hugo applications with Nanobox. +{{% /note %}} + +With Hugo installed you're ready to go. Develop Hugo like you would normally (using all the generators, etc.). Once your app is ready to deploy, run `hugo` to generate your static assets and get ready to deploy! + + +## Deploying Hugo with Nanobox + +{{% note %}} +If you haven't already, make sure to [connect a hosting account](#connect-a-host-account) to your Nanobox account, and [launch a new application](#launch-a-new-application-on-nanobox) in the Dashboard. +{{% /note %}} + +To deploy your application to Nanobox you simply need to [link your local codebase](https://docs.nanobox.io/workflow/deploy-code/#add-your-live-app-as-a-remote) to an application you've created on Nanobox. That is done with the following command: + +``` +nanobox remote add +``` + +{{% note %}} +You may be prompted to login using your ***Nanobox credentials*** at this time +{{% /note %}} + +### Stage Your Application (optional) + +Nanobox gives you the ability to [simulate your production environment locally](https://docs.nanobox.io/workflow/deploy-code/#preview-locally). While staging is optional it's always recommended, so there's no reason not to! + +To stage your app simply run: + +``` +nanobox deploy dry-run +``` + +Now visit your application with the IP address provided. + +![nanobox deploy dry-run](/images/hosting-and-deployment/deployment-with-nanobox/nanobox-deploy-dry-run.png) + +### Deploy Your Application + +Once everything checks out and you're [ready to deploy](https://docs.nanobox.io/workflow/deploy-code/#deploy-to-production), simply run: + +``` +nanobox deploy +``` + +Within minutes you're Hugo app will be deployed to your host and humming along smoothly. That's it! diff --cc docs/content/en/hosting-and-deployment/hosting-on-netlify.md index fca639fa,00000000..f2820a8d mode 100644,000000..100644 --- a/docs/content/en/hosting-and-deployment/hosting-on-netlify.md +++ b/docs/content/en/hosting-and-deployment/hosting-on-netlify.md @@@ -1,153 -1,0 +1,153 @@@ +--- +title: Host on Netlify +linktitle: Host on Netlify +description: Netlify can host your Hugo site with CDN, continuous deployment, 1-click HTTPS, an admin GUI, and its own CLI. +date: 2017-02-01 +publishdate: 2017-02-01 +lastmod: 2017-03-11 +categories: [hosting and deployment] +keywords: [netlify,hosting,deployment] +authors: [Ryan Watters, Seth MacLeod] +menu: + docs: + parent: "hosting-and-deployment" + weight: 10 +weight: 10 +sections_weight: 10 +draft: false +aliases: [] +toc: true +--- + +[Netlify][netlify] provides continuous deployment services, global CDN, ultra-fast DNS, atomic deploys, instant cache invalidation, one-click SSL, a browser-based interface, a CLI, and many other features for managing your Hugo website. + +## Assumptions + +* You have an account with GitHub, GitLab, or Bitbucket. +* You have completed the [Quick Start][] or have Hugo website you are ready to deploy and share with the world. +* You do not already have a Netlify account. + +## Create a Netlify account + +Go to [app.netlify.com][] and select your preferred signup method. This will likely be a hosted Git provider, although you also have the option to sign up with an email address. + +The following examples use GitHub, but other git providers will follow a similar process. + +![Screenshot of the homepage for app.netlify.com, containing links to the most popular hosted git solutions.](/images/hosting-and-deployment/hosting-on-netlify/netlify-signup.jpg) + - Selecting GitHub will bring up a typical modal you've seen through other application that use GitHub for authentication. Select "Authorize application." ++Selecting GitHub will bring up an authorization modal for authentication. Select "Authorize application." + +![Screenshot of the authorization popup for Netlify and GitHub.](/images/hosting-and-deployment/hosting-on-netlify/netlify-first-authorize.jpg) + +## Create a New Site with Continuous Deployment + +You're now already a Netlify member and should be brought to your new dashboard. Select "New site from git." + +![Screenshot of the blank Netlify admin panel with no sites and highlighted 'add new site' button'](/images/hosting-and-deployment/hosting-on-netlify/netlify-add-new-site.jpg) + +Netlify will then start walking you through the steps necessary for continuous deployment. First, you'll need to select your git provider again, but this time you are giving Netlify added permissions to your repositories. + +![Screenshot of step 1 of create a new site for Netlify: selecting the git provider](/images/hosting-and-deployment/hosting-on-netlify/netlify-create-new-site-step-1.jpg) + +And then again with the GitHub authorization modal: + +![Screenshot of step 1 of create a new site for Netlify: selecting the git provider](/images/hosting-and-deployment/hosting-on-netlify/netlify-authorize-added-permissions.jpg) + +Select the repo you want to use for continuous deployment. If you have a large number of repositories, you can filter through them in real time using repo search: + +![Screenshot of step 1 of create a new site for Netlify: selecting the git provider](/images/hosting-and-deployment/hosting-on-netlify/netlify-create-new-site-step-2.jpg) + +Once selected, you'll be brought to a screen for basic setup. Here you can select the branch you wanted published, your [build command][], and your publish (i.e. deploy) directory. The publish directory should mirror that of what you've set in your [site configuration][config], the default of which is `public`. The following steps assume you are publishing from the `master` branch. + +## Configure Hugo Version in Netlify + +You can [set Hugo version](https://www.netlify.com/blog/2017/04/11/netlify-plus-hugo-0.20-and-beyond/) for your environments in `netlify.toml` file or set `HUGO_VERSION` as a build environment variable in the Netlify console. + +For production: + +``` +[context.production.environment] + HUGO_VERSION = "0.36" +``` + +For testing: + +``` +[context.deploy-preview.environment] + HUGO_VERSION = "0.36" +``` + +The Netlify configuration file can be a little hard to understand and get right for the different environment, and you may get some inspiration and tips from this site's `netlify.toml`: + +{{< code file="netlify.toml" nocode="true" >}} +{{< readfile file="netlify.toml" highlight="toml" >}} +{{< /code >}} + +## Build and Deploy Site + +In the Netlify console, selecting "Deploy site" will immediately take you to a terminal for your build:. + +![Animated gif of deploying a site to Netlify, including the terminal read out for the build.](/images/hosting-and-deployment/hosting-on-netlify/netlify-deploying-site.gif) + +Once the build is finished---this should only take a few seconds--you should now see a "Hero Card" at the top of your screen letting you know the deployment is successful. The Hero Card is the first element that you see in most pages. It allows you to see a quick summary of the page and gives access to the most common/pertinent actions and information. You'll see that the URL is automatically generated by Netlify. You can update the URL in "Settings." + +![Screenshot of successful deploy badge at the top of a deployments screen from within the Netlify admin.](/images/hosting-and-deployment/hosting-on-netlify/netlify-deploy-published.jpg) + +![Screenshot of homepage to https://hugo-netlify-example.netlify.com, which is mostly dummy text](/images/hosting-and-deployment/hosting-on-netlify/netlify-live-site.jpg) + +[Visit the live site][visit]. + +Now every time you push changes to your hosted git repository, Netlify will rebuild and redeploy your site. + +See [this blog post](https://www.netlify.com/blog/2017/04/11/netlify-plus-hugo-0.20-and-beyond/) for more details about how Netlify handles Hugo versions. + +## Use Hugo Themes with Netlify + +The [`git clone` method for installing themes][installthemes] is not supported by Netlify. If you were to use `git clone`, it would require you to recursively remove the `.git` subdirectory from the theme folder and would therefore prevent compatibility with future versions of the theme. + +A *better* approach is to install a theme as a proper git submodule. You can [read the GitHub documentation for submodules][ghsm] or those found on [Git's website][gitsm] for more information, but the command is similar to that of `git clone`: + +``` +cd themes +git submodule add https://github.com// +``` + +It is recommended to only use stable versions of a theme (if it’s versioned) and always check the changelog. This can be done by checking out a specific release within the theme's directory. + +Switch to the theme's directory and list all available versions: + +``` +cd themes/ +git tag +# exit with q +``` + +You can checkout a specific version as follows: + +``` +git checkout tags/ +``` + +## Next Steps + +You now have a live website served over https, distributed through CDN, and configured for continuous deployment. Dig deeper into the Netlify documentation: + +1. [Using a Custom Domain][] +2. [Setting up HTTPS on Custom Domains][httpscustom] +3. [Redirects and Rewrite Rules][] + + +[app.netlify.com]: https://app.netlify.com +[build command]: /getting-started/usage/#the-hugo-command +[config]: /getting-started/configuration/ +[ghsm]: https://github.com/blog/2104-working-with-submodules +[gitsm]: https://git-scm.com/book/en/v2/Git-Tools-Submodules +[httpscustom]: https://www.netlify.com/docs/ssl/ +[hugoversions]: https://github.com/netlify/build-image/blob/master/Dockerfile#L216 +[installthemes]: /themes/installing/ +[netlify]: https://www.netlify.com/ +[netlifysignup]: https://app.netlify.com/signup +[Quick Start]: /getting-started/quick-start/ +[Redirects and Rewrite Rules]: https://www.netlify.com/docs/redirects/ +[Using a Custom Domain]: https://www.netlify.com/docs/custom-domains/ +[visit]: https://hugo-netlify-example.netlify.com diff --cc docs/content/en/news/0.41-relnotes/featured-hugo-41-poster.png index 00000000,00000000..8f752f66 new file mode 100644 Binary files differ diff --cc docs/content/en/news/0.41-relnotes/index.md index ab6fbed6,00000000..411e373e mode 100644,000000..100644 --- a/docs/content/en/news/0.41-relnotes/index.md +++ b/docs/content/en/news/0.41-relnotes/index.md @@@ -1,64 -1,0 +1,64 @@@ + +--- +date: 2018-05-25 - title: "0.41" - description: "0.41" ++title: "Hugo 0.41: Privacy Configuration for GDPR" ++description: "Hugo 0.41 adds a new site configuration section to meet the new General Data Protection Regulation (GDPR)." +categories: ["Releases"] +--- + + - In Hugo `0.41` we add a new **Privacy Configuration** section to meet the new regulations in the new **General Data Protection Regulation ([GDPR](https://en.wikipedia.org/wiki/General_Data_Protection_Regulation))**. Many have contributed in the discussion about this, but a special thanks to [@onedrawingperday](https://github.com/onedrawingperday), [@jhabdas](https://github.com/jhabdas), and [@it-gro](https://github.com/it-gro). ++In Hugo `0.41` we add a new **Privacy Configuration** section to meet the new regulations in the new **General Data Protection Regulation ([GDPR](https://en.wikipedia.org/wiki/General_Data_Protection_Regulation))**. Many have contributed work on this project, but a special thanks to [@onedrawingperday](https://github.com/onedrawingperday), [@jhabdas](https://github.com/jhabdas), and [@it-gro](https://github.com/it-gro). + +> You can read more about the new Privacy Config [here](https://gohugo.io/about/hugo-and-gdpr/). + + +Hugo now has: + +* 25917+ [stars](https://github.com/gohugoio/hugo/stargazers) +* 446+ [contributors](https://github.com/gohugoio/hugo/graphs/contributors) +* 231+ [themes](http://themes.gohugo.io/) + +## Notes + +* We have fixed an issue where we sent the wrong `.Site` object into the archetype templates used in `hugo new`. This meant that if you wanted to access site params and some other fields you needed to use `.Site.Info.Params` etc. This release fixes that so now you can use the same construct in the archetype templates as in the regular templates. + +## Enhancements + +* Alias tweet shortode to twitter [3bfe8f4b](https://github.com/gohugoio/hugo/commit/3bfe8f4be653f44674293685cb5750d90668b2f6) [@bep](https://github.com/bep) [#4765](https://github.com/gohugoio/hugo/issues/4765) +* Adjust GA templates [f45b522e](https://github.com/gohugoio/hugo/commit/f45b522ebffafc61a3cb9b694bc3542747c73e07) [@bep](https://github.com/bep) [#4616](https://github.com/gohugoio/hugo/issues/4616) +* Wrap the relevant templates with the privacy policy disable check [67892073](https://github.com/gohugoio/hugo/commit/6789207347fc2df186741644a6fe968d41ea9077) [@bep](https://github.com/bep) [#4616](https://github.com/gohugoio/hugo/issues/4616) +* Extract internal templates [34ad9a4f](https://github.com/gohugoio/hugo/commit/34ad9a4f178fcf50abe7246ad9d30b294327da16) [@bep](https://github.com/bep) [#4457](https://github.com/gohugoio/hugo/issues/4457) +* Use double quotes instead of back quotes [b2b500f5](https://github.com/gohugoio/hugo/commit/b2b500f563c3bb36751a4c1610df113c4daad604) [@anthonyfok](https://github.com/anthonyfok) +* Provide the correct .Site object to archetype templates [ab02594e](https://github.com/gohugoio/hugo/commit/ab02594e09c0414124186e42d67d52d474dd341a) [@bep](https://github.com/bep) [#4732](https://github.com/gohugoio/hugo/issues/4732) +* Document the GDPR Privacy Config [c71f201f](https://github.com/gohugoio/hugo/commit/c71f201fd93287afa7cb7b875bd523c25e48400c) [@bep](https://github.com/bep) [#4751](https://github.com/gohugoio/hugo/issues/4751) +* Add no-cookie variants of the Google Analytics templates [a51945ea] (https://github.com/gohugoio/hugo/commit/a51945ea4b99d17501d73cf3367926683e4a4dfd) [@bep](https://github.com/bep) [#4775](https://github.com/gohugoio/hugo/issues/4775) +* Remove youtube_simple for now [448081b8](https://github.com/gohugoio/hugo/commit/448081b840db4a23c0c49c2d869ac207dcb6ac40) [@bep](https://github.com/bep) [#4751](https://github.com/gohugoio/hugo/issues/4751) +* Add anonymizeIP to GA privacy config [1f1d955b](https://github.com/gohugoio/hugo/commit/1f1d955b56471e41d5288c57f1ef8333dc297120) [@bep](https://github.com/bep) [#4751](https://github.com/gohugoio/hugo/issues/4751) +* Support DNT in Twitter shortcode for GDPR [9753cb59](https://github.com/gohugoio/hugo/commit/9753cb59f1f1d866943a485dd7c917d1b68f6eda) [@bep](https://github.com/bep) [#4765](https://github.com/gohugoio/hugo/issues/4765) +* Regenerate embedded templates [6aa2c385](https://github.com/gohugoio/hugo/commit/6aa2c38507aa1c2246222684717b4d69d26b03d7) [@bep](https://github.com/bep) [#4761](https://github.com/gohugoio/hugo/issues/4761) +* Add instagram_simple shortcode [9ad46a20](https://github.com/gohugoio/hugo/commit/9ad46a20357a7e28b405feef5c8f7d4501186da6) [@bep](https://github.com/bep) [#4748](https://github.com/gohugoio/hugo/issues/4748) +* Go fmt [4256de33](https://github.com/gohugoio/hugo/commit/4256de3392d320a5a47fcab49882f2a3249c2163) [@bep](https://github.com/bep) +* Remove the id from youtube_simple [bed7a0fa](https://github.com/gohugoio/hugo/commit/bed7a0faff90bbe389629347026853b7bc4c8c3f) [@bep](https://github.com/bep) [#4751](https://github.com/gohugoio/hugo/issues/4751) +* Add an unified .Site.Config with a services section [4ddcf52c](https://github.com/gohugoio/hugo/commit/4ddcf52ccc7af3e23109ebaac1f0486087a212ba) [@bep](https://github.com/bep) [#4751](https://github.com/gohugoio/hugo/issues/4751) +* Move the privacy config into a parent [353148c2](https://github.com/gohugoio/hugo/commit/353148c2bc2cdb9f2eb8ee967ba756ce09323801) [@bep](https://github.com/bep) [#4751](https://github.com/gohugoio/hugo/issues/4751) +* Make the simple mode YouTube links schemaless [69ee6b41](https://github.com/gohugoio/hugo/commit/69ee6b41e36625595e2bcabcde0bc58663e5b93c) [@bep](https://github.com/bep) [#4616](https://github.com/gohugoio/hugo/issues/4616) +* Add YouTube shortcode simple mode [88e35686](https://github.com/gohugoio/hugo/commit/88e356868062cc618385cd22b6730df2459518cd) [@bep](https://github.com/bep) [#4616](https://github.com/gohugoio/hugo/issues/4616) +* Do not return error on .Get "class" and vice versa in shortcodes [2f17f937](https://github.com/gohugoio/hugo/commit/2f17f9378ad96c4a9f6d7d24b0776ed3a25a08a3) [@bep](https://github.com/bep) [#4745](https://github.com/gohugoio/hugo/issues/4745) +* Create SUPPORT.md [0a7027e2](https://github.com/gohugoio/hugo/commit/0a7027e2a87283743d5310b74e18666e4a64d3e1) [@coliff](https://github.com/coliff) +* Add PrivacyEnhanced mode for YouTube to the GDPR Policy [5f24a2c0](https://github.com/gohugoio/hugo/commit/5f24a2c047db0bff8c9e267bfa8ef8e43e6bd24e) [@bep](https://github.com/bep) [#4616](https://github.com/gohugoio/hugo/issues/4616) +* Add RespectDoNotTrack to GDPR privacy policy for Google Analytics [71014201](https://github.com/gohugoio/hugo/commit/710142016b140538bfc11e48bb32d26fa685b2ad) [@bep](https://github.com/bep) [#4616](https://github.com/gohugoio/hugo/issues/4616) +* Add the foundation for GDPR privacy configuration [0bbdef98](https://github.com/gohugoio/hugo/commit/0bbdef986d8eecf4fabe9a372e33626dbdfeb36b) [@bep](https://github.com/bep) [#4616](https://github.com/gohugoio/hugo/issues/4616) +* Show site build warning in TestPageBundlerSiteRegular [9bd4236e](https://github.com/gohugoio/hugo/commit/9bd4236e1b3bee332439eef50e12d4481340c3eb) [@anthonyfok](https://github.com/anthonyfok) [#4672](https://github.com/gohugoio/hugo/issues/4672) +* Do not show empty BuildDate in version [4eedb377](https://github.com/gohugoio/hugo/commit/4eedb377b60fb6742c97398942a0045ff2a824c4) [@anthonyfok](https://github.com/anthonyfok) +* Improve markup determination logic [2fb9af59](https://github.com/gohugoio/hugo/commit/2fb9af59c14b1732ba1a2f21794e2cf8dfca0604) [@vassudanagunta](https://github.com/vassudanagunta) +* Update CONTRIBUTING.md [b6ededf0](https://github.com/gohugoio/hugo/commit/b6ededf0591a81667754f1dccef2c6fe6d342811) [@domdomegg](https://github.com/domdomegg) + +## Fixes + +* Avoid ANSI character output on Windows [568b4335](https://github.com/gohugoio/hugo/commit/568b4335c20effb46168bd639317a3420f563463) [@LorenzCK](https://github.com/LorenzCK) [#4462](https://github.com/gohugoio/hugo/issues/4462) + + + + + + diff --cc docs/content/en/templates/introduction.md index 32df1129,00000000..f13378ef mode 100644,000000..100644 --- a/docs/content/en/templates/introduction.md +++ b/docs/content/en/templates/introduction.md @@@ -1,541 -1,0 +1,541 @@@ +--- +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 `{{ }}`. ++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 + +``` +{{ 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 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). ++There are more boolean operators than those listed in the Hugo docs in the [Go template documentation](http://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: + +``` +{{ partial "header.html" . }} +``` + +### Template + +The `template` function was used to include *partial* templates in much older +Hugo versions. Now it is still useful for calling [*internal* +templates][internal_templates]: + +``` +{{ template "_internal/opengraph.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 {#ie-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 + +## Comments + +In order to keep your templates organized and share information throughout your team, you may want to add comments to your templates. There are two ways to do that with Hugo. + +### Go templates comments + +Go templates support `{{/*` and `*/}}` to open and close a comment block. Nothing within that block will be rendered. + +For example: + +``` +Bonsoir, {{/* {{ add 0 + 2 }} */}}Eliott. +``` + +Will render `Bonsoir, Eliott.`, and not care about the syntax error (`add 0 + 2`) in the comment block. + +### HTML comments + +If you need to produce HTML comments from your templates, take a look at the [Internet Explorer conditional comments](#ie-conditional-comments) example. If you need variables to construct such HTML comments, just pipe `printf` to `safeHTML`. For example: + +``` +{{ printf "" .Site.Title | safeHTML }} +``` + +#### HTML comments containing Go templates + +HTML comments are by default stripped, but their content is still evaluated. That means that although the HTML comment will never render any content to the final HTML pages, code contained within the comment may fail the build process. + +{{% note %}} +Do **not** try to comment out Go template code using HTML comments. +{{% /note %}} + +``` + +{{ $author }} +``` + +The templating engine will strip the content within the HTML comment, but will first evaluate any Go template code if present within. So the above example will render `Emma Goldman`, as the `$author` variable got evaluated in the HTML comment. But the build would have failed if that code in the HTML comment had an error. + +## 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-toggle file="config" >}} +params: + copyrighthtml: "Copyright © 2017 John Doe. All Rights Reserved." + twitteruser: "spf13" + sidebarrecentlimit: 5 +{{< /code >}} + +Within a footer layout, you might then declare a `