From: Bjørn Erik Pedersen Date: Fri, 27 Nov 2020 08:30:05 +0000 (+0100) Subject: Merge commit '9f1265fde4b9ef186148337c99f08601633b6056' X-Git-Tag: v0.79.0~4 X-Git-Url: http://git.maquefel.me/?a=commitdiff_plain;h=4f1e4bb3fe8241d7a900f57e156f9679768aff24;p=brevno-suite%2Fhugo Merge commit '9f1265fde4b9ef186148337c99f08601633b6056' --- 4f1e4bb3fe8241d7a900f57e156f9679768aff24 diff --cc docs/config.toml index 77e8770bb,000000000..efa1b0573 mode 100644,000000..100644 --- a/docs/config.toml +++ b/docs/config.toml @@@ -1,71 -1,0 +1,73 @@@ +baseURL = "https://gohugo.io/" +paginate = 100 +defaultContentLanguage = "en" +enableEmoji = true +# Set the unicode character used for the "return" link in page footnotes. +footnotereturnlinkcontents = "↩" +languageCode = "en-us" +title = "Hugo" + ++ ignoreErrors = ["error-remote-getjson"] ++ + +googleAnalytics = "UA-7131036-4" + +pluralizeListTitles = false + +# We do redirects via Netlify's _redirects file, generated by Hugo (see "outputs" below). +disableAliases = true + +[module] + [module.hugoVersion] + min = "0.56.0" + [[module.imports]] + path = "github.com/gohugoio/gohugoioTheme" + +[outputs] +home = [ "HTML", "RSS", "REDIR", "HEADERS" ] +section = [ "HTML", "RSS"] + +[mediaTypes] +[mediaTypes."text/netlify"] +delimiter = "" + +[outputFormats] +[outputFormats.REDIR] +mediatype = "text/netlify" +baseName = "_redirects" +isPlainText = true +notAlternative = true +[outputFormats.HEADERS] +mediatype = "text/netlify" +baseName = "_headers" +isPlainText = true +notAlternative = true + +[related] + +threshold = 80 +includeNewer = true +toLower = false + +[[related.indices]] +name = "keywords" +weight = 100 +[[related.indices]] +name = "date" +weight = 10 +pattern = "2006" + +[social] +twitter = "GoHugoIO" + + +[imaging] +# See https://github.com/disintegration/imaging +# CatmullRom is a sharp bicubic filter which should fit the docs site well with its many screenshots. +# Note that you can also set this per image processing. +resampleFilter = "CatmullRom" + +# Default JPEG quality setting. Default is 75. +quality = 75 + +anchor = "smart" diff --cc docs/content/en/content-management/multilingual.md index 036d74064,000000000..e24c573c2 mode 100644,000000..100644 --- a/docs/content/en/content-management/multilingual.md +++ b/docs/content/en/content-management/multilingual.md @@@ -1,510 -1,0 +1,510 @@@ +--- +title: Multilingual Mode +linktitle: Multilingual and i18n +description: Hugo supports the creation of websites with multiple languages side by side. +date: 2017-01-10 +publishdate: 2017-01-10 +lastmod: 2017-01-10 +categories: [content management] +keywords: [multilingual,i18n, internationalization] +menu: + docs: + parent: "content-management" + weight: 150 +weight: 150 #rem +draft: false +aliases: [/content/multilingual/,/tutorials/create-a-multilingual-site/] +toc: true +--- + +You should define the available languages in a `languages` section in your site configuration. + +> Also See [Hugo Multilingual Part 1: Content translation](https://regisphilibert.com/blog/2018/08/hugo-multilingual-part-1-managing-content-translation/) + +## Configure Languages + +The following is an example of a site configuration for a multilingual Hugo project: + +{{< code-toggle file="config" >}} - DefaultContentLanguage = "en" ++defaultContentLanguage = "en" +copyright = "Everything is mine" + +[params] +[params.navigation] +help = "Help" + +[languages] +[languages.en] +title = "My blog" +weight = 1 +[languages.en.params] +linkedin = "https://linkedin.com/whoever" + +[languages.fr] +title = "Mon blogue" +weight = 2 +[languages.fr.params] +linkedin = "https://linkedin.com/fr/whoever" +[languages.fr.params.navigation] +help = "Aide" + +[languages.ar] +title = "مدونتي" +weight = 2 +languagedirection = "rtl" + +[languages.pt-pt] +title = "O meu blog" +weight = 3 +{{< /code-toggle >}} + +Anything not defined in a `languages` block will fall back to the global value for that key (e.g., `copyright` for the English `en` language). This also works for `params`, as demonstrated with `help` above: You will get the value `Aide` in French and `Help` in all the languages without this parameter set. + +With the configuration above, all content, sitemap, RSS feeds, paginations, +and taxonomy pages will be rendered below `/` in English (your default content language) and then below `/fr` in French. + +When working with front matter `Params` in [single page templates][singles], omit the `params` in the key for the translation. + +`defaultContentLanguage` sets the project's default language. If not set, the default language will be `en`. + +If the default language needs to be rendered below its own language code (`/en`) like the others, set `defaultContentLanguageInSubdir: true`. + +Only the obvious non-global options can be overridden per language. Examples of global options are `baseURL`, `buildDrafts`, etc. + - **Please note:** use lowercase language codes, even when using regional languages (ie. use pt-pt instead of pt-PT). Currently Hugo language internals lowercase language codes, which can cause conflicts with settings like `DefaultContentLanguage` which are not lowercased. Please track the evolution of this issue in [Hugo repository issue tracker](https://github.com/gohugoio/hugo/issues/7344) ++**Please note:** use lowercase language codes, even when using regional languages (ie. use pt-pt instead of pt-PT). Currently Hugo language internals lowercase language codes, which can cause conflicts with settings like `defaultContentLanguage` which are not lowercased. Please track the evolution of this issue in [Hugo repository issue tracker](https://github.com/gohugoio/hugo/issues/7344) + +### Disable a Language + +You can disable one or more languages. This can be useful when working on a new translation. + +```toml +disableLanguages = ["fr", "ja"] +``` + +Note that you cannot disable the default content language. + +We kept this as a standalone setting to make it easier to set via [OS environment](/getting-started/configuration/#configure-with-environment-variables): + +```bash +HUGO_DISABLELANGUAGES="fr ja" hugo +``` +If you have already a list of disabled languages in `config.toml`, you can enable them in development like this: + +```bash +HUGO_DISABLELANGUAGES=" " hugo server +``` + + +### Configure Multilingual Multihost + +From **Hugo 0.31** we support multiple languages in a multihost configuration. See [this issue](https://github.com/gohugoio/hugo/issues/4027) for details. + +This means that you can now configure a `baseURL` per `language`: + + +> If a `baseURL` is set on the `language` level, then all languages must have one and they must all be different. + +Example: + +{{< code-toggle file="config" >}} +[languages] +[languages.fr] +baseURL = "https://example.fr" +languageName = "Français" +weight = 1 +title = "En Français" + +[languages.en] +baseURL = "https://example.com" +languageName = "English" +weight = 2 +title = "In English" +{{}} + +With the above, the two sites will be generated into `public` with their own root: + +```bash +public +├── en +└── fr +``` + +**All URLs (i.e `.Permalink` etc.) will be generated from that root. So the English home page above will have its `.Permalink` set to `https://example.com/`.** + +When you run `hugo server` we will start multiple HTTP servers. You will typically see something like this in the console: + +```bash +Web Server is available at 127.0.0.1:1313 (bind address 127.0.0.1) +Web Server is available at 127.0.0.1:1314 (bind address 127.0.0.1) +Press Ctrl+C to stop +``` + +Live reload and `--navigateToChanged` between the servers work as expected. + +### Taxonomies and Blackfriday + +Taxonomies and [Blackfriday configuration][config] can also be set per language: + + +{{< code-toggle file="config" >}} +[Taxonomies] +tag = "tags" + +[blackfriday] +angledQuotes = true +hrefTargetBlank = true + +[languages] +[languages.en] +weight = 1 +title = "English" +[languages.en.blackfriday] +angledQuotes = false + +[languages.fr] +weight = 2 +title = "Français" +[languages.fr.Taxonomies] +plaque = "plaques" +{{}} + +## Translate Your Content + +There are two ways to manage your content translations. Both ensure each page is assigned a language and is linked to its counterpart translations. + +### Translation by filename + +Considering the following example: + +1. `/content/about.en.md` +2. `/content/about.fr.md` + +The first file is assigned the English language and is linked to the second. +The second file is assigned the French language and is linked to the first. + +Their language is __assigned__ according to the language code added as a __suffix to the filename__. + +By having the same **path and base filename**, the content pieces are __linked__ together as translated pages. + +{{< note >}} +If a file has no language code, it will be assigned the default language. +{{}} + +### Translation by content directory + +This system uses different content directories for each of the languages. Each language's content directory is set using the `contentDir` param. + +{{< code-toggle file="config" >}} + +languages: + en: + weight: 10 + languageName: "English" + contentDir: "content/english" + fr: + weight: 20 + languageName: "Français" + contentDir: "content/french" + +{{< /code-toggle >}} + +The value of `contentDir` can be any valid path -- even absolute path references. The only restriction is that the content directories cannot overlap. + +Considering the following example in conjunction with the configuration above: + +1. `/content/english/about.md` +2. `/content/french/about.md` + +The first file is assigned the English language and is linked to the second. +The second file is assigned the French language and is linked to the first. + +Their language is __assigned__ according to the content directory they are __placed__ in. + +By having the same **path and basename** (relative to their language content directory), the content pieces are __linked__ together as translated pages. + +### Bypassing default linking. + +Any pages sharing the same `translationKey` set in front matter will be linked as translated pages regardless of basename or location. + +Considering the following example: + +1. `/content/about-us.en.md` +2. `/content/om.nn.md` +3. `/content/presentation/a-propos.fr.md` + +```yaml +# set in all three pages +translationKey: "about" +``` + +By setting the `translationKey` front matter param to `about` in all three pages, they will be __linked__ as translated pages. + + +### Localizing permalinks + +Because paths and filenames are used to handle linking, all translated pages will share the same URL (apart from the language subdirectory). + +To localize the URLs, the [`slug`]({{< ref "/content-management/organization/index.md#slug" >}}) or [`url`]({{< ref "/content-management/organization/index.md#url" >}}) front matter param can be set in any of the non-default language file. + +For example, a French translation (`content/about.fr.md`) can have its own localized slug. + +{{< code-toggle >}} +Title: A Propos +slug: "a-propos" +{{< /code-toggle >}} + + +At render, Hugo will build both `/about/` and `/fr/a-propos/` while maintaining their translation linking. + +{{% note %}} +If using `url`, remember to include the language part as well: `/fr/compagnie/a-propos/`. +{{%/ note %}} + +### Page Bundles + +To avoid the burden of having to duplicate files, each Page Bundle inherits the resources of its linked translated pages' bundles except for the content files (markdown files, html files etc...). + +Therefore, from within a template, the page will have access to the files from all linked pages' bundles. + +If, across the linked bundles, two or more files share the same basename, only one will be included and chosen as follows: + +* File from current language bundle, if present. +* First file found across bundles by order of language `Weight`. + +{{% note %}} +Page Bundle resources follow the same language assignment logic as content files, both by filename (`image.jpg`, `image.fr.jpg`) and by directory (`english/about/header.jpg`, `french/about/header.jpg`). +{{%/ note %}} + +## Reference the Translated Content + +To create a list of links to translated content, use a template similar to the following: + +{{< code file="layouts/partials/i18nlist.html" >}} +{{ if .IsTranslated }} +

{{ i18n "translations" }}

+ +{{ end }} +{{< /code >}} + +The above can be put in a `partial` (i.e., inside `layouts/partials/`) and included in any template, whether a [single content page][contenttemplate] or the [homepage][]. It will not print anything if there are no translations for a given page. + +The above also uses the [`i18n` function][i18func] described in the next section. + +### List All Available Languages + +`.AllTranslations` on a `Page` can be used to list all translations, including the page itself. On the home page it can be used to build a language navigator: + + +{{< code file="layouts/partials/allLanguages.html" >}} + +{{< /code >}} + +## Translation of Strings + +Hugo uses [go-i18n][] to support string translations. [See the project's source repository][go-i18n-source] to find tools that will help you manage your translation workflows. + +Translations are collected from the `themes//i18n/` folder (built into the theme), as well as translations present in `i18n/` at the root of your project. In the `i18n`, the translations will be merged and take precedence over what is in the theme folder. Language files should be named according to [RFC 5646][] with names such as `en-US.toml`, `fr.toml`, etc. + +{{% note %}} +From **Hugo 0.31** you no longer need to use a valid language code. It can be anything. + +See https://github.com/gohugoio/hugo/issues/3564 + +{{% /note %}} + +### Query basic translation + +From within your templates, use the `i18n` function like this: + +``` +{{ i18n "home" }} +``` + +The function will search for the `"home"` id from `i18n/en-US.toml` file: + +``` +[home] +other = "Home" +``` + +The result will be + +``` +Home +``` + +### Query a flexible translation with variables + +Often you will want to use to the page variables in the translations strings. To do that, pass on the `.` context when calling `i18n`: + +``` +{{ i18n "wordCount" . }} +``` + +The function will pass the `.` context to the `"wordCount"` id in `i18n/en-US.toml` file: + +``` +[wordCount] +other = "This article has {{ .WordCount }} words." +``` + +Assume `.WordCount` in the context has value is 101. The result will be: + +``` +This article has 101 words. +``` + +### Query a singular/plural translation + +In order to meet singular/plural requirement, you must pass a dictionary (map) with a numeric `.Count` property to the `i18n` function. The below example uses `.ReadingTime` variable which has a built-in `.Count` property. + +``` +{{ i18n "readingTime" .ReadingTime }} +``` + +The function will read `.Count` from `.ReadingTime` and evaluate where the number is singular (`one`) or plural (`other`). After that, it will pass to `readingTime` id in `i18n/en-US.toml` file: + +``` +[readingTime] +one = "One minute to read" +other = "{{.Count}} minutes to read" +``` + +Assume `.ReadingTime.Count` in the context has value of 525600. The result will be: + +``` +525600 minutes to read +``` + +If `.ReadingTime.Count` in the context has value is 1. The result is: + +``` +One minutes to read +``` + +In case you need to pass custom data: (`(dict "Count" 25)` is minimum requirement) + +``` +{{ i18n "readingTime" (dict "Count" 25 "FirstArgument" true "SecondArgument" false "Etc" "so on, so far") }} +``` + + +## Customize Dates + +At the time of this writing, Go does not yet have support for internationalized locales for dates, but if you do some work, you can simulate it. For example, if you want to use French month names, you can add a data file like ``data/mois.yaml`` with this content: + +~~~yaml +1: "janvier" +2: "février" +3: "mars" +4: "avril" +5: "mai" +6: "juin" +7: "juillet" +8: "août" +9: "septembre" +10: "octobre" +11: "novembre" +12: "décembre" +~~~ + +...then index the non-English date names in your templates like so: + +~~~html + +~~~ + +This technique extracts the day, month and year by specifying ``.Date.Day``, ``.Date.Month``, and ``.Date.Year``, and uses the month number as a key, when indexing the month name data file. + +## Menus + +You can define your menus for each language independently. Creating multilingual menus works just like [creating regular menus][menus], except they're defined in language-specific blocks in the configuration file: + +``` +defaultContentLanguage = "en" + +[languages.en] +weight = 0 +languageName = "English" + +[[languages.en.menu.main]] +url = "/" +name = "Home" +weight = 0 + + +[languages.de] +weight = 10 +languageName = "Deutsch" + +[[languages.de.menu.main]] +url = "/" +name = "Startseite" +weight = 0 +``` + +The rendering of the main navigation works as usual. `.Site.Menus` will just contain the menu in the current language. Note that `absLangURL` below will link to the correct locale of your website. Without it, menu entries in all languages would link to the English version, since it's the default content language that resides in the root directory. + +``` + + +``` + +## Missing Translations + +If a string does not have a translation for the current language, Hugo will use the value from the default language. If no default value is set, an empty string will be shown. + +While translating a Hugo website, it can be handy to have a visual indicator of missing translations. The [`enableMissingTranslationPlaceholders` configuration option][config] will flag all untranslated strings with the placeholder `[i18n] identifier`, where `identifier` is the id of the missing translation. + +{{% note %}} +Hugo will generate your website with these missing translation placeholders. It might not be suitable for production environments. +{{% /note %}} + +For merging of content from other languages (i.e. missing content translations), see [lang.Merge](/functions/lang.merge/). + +To track down missing translation strings, run Hugo with the `--i18n-warnings` flag: + +``` + hugo --i18n-warnings | grep i18n +i18n|MISSING_TRANSLATION|en|wordCount +``` + +## Multilingual Themes support + +To support Multilingual mode in your themes, some considerations must be taken for the URLs in the templates. If there is more than one language, URLs must meet the following criteria: + +* Come from the built-in `.Permalink` or `.RelPermalink` +* Be constructed with the [`relLangURL` template function][rellangurl] or the [`absLangURL` template function][abslangurl] **OR** be prefixed with `{{ .LanguagePrefix }}` + +If there is more than one language defined, the `LanguagePrefix` variable will equal `/en` (or whatever your `CurrentLanguage` is). If not enabled, it will be an empty string (and is therefore harmless for single-language Hugo websites). + +[abslangurl]: /functions/abslangurl +[config]: /getting-started/configuration/ +[contenttemplate]: /templates/single-page-templates/ +[go-i18n-source]: https://github.com/nicksnyder/go-i18n +[go-i18n]: https://github.com/nicksnyder/go-i18n +[homepage]: /templates/homepage/ +[i18func]: /functions/i18n/ +[menus]: /content-management/menus/ +[rellangurl]: /functions/rellangurl +[RFC 5646]: https://tools.ietf.org/html/rfc5646 +[singles]: /templates/single-page-templates/ diff --cc docs/content/en/content-management/page-bundles.md index 2ccf058e0,000000000..9561ea2e9 mode 100644,000000..100644 --- a/docs/content/en/content-management/page-bundles.md +++ b/docs/content/en/content-management/page-bundles.md @@@ -1,189 -1,0 +1,188 @@@ +--- +title : "Page Bundles" +description : "Content organization using Page Bundles" +date : 2018-01-24T13:09:00-05:00 - lastmod : 2018-01-28T22:26:40-05:00 +linktitle : "Page Bundles" +keywords : ["page", "bundle", "leaf", "branch"] +categories : ["content management"] +toc : true +menu : + docs: + identifier : "page-bundles" + parent : "content-management" + weight : 11 +--- + +Page Bundles are a way to group [Page Resources](/content-management/page-resources/). + +A Page Bundle can be one of: + +- Leaf Bundle (leaf means it has no children) +- Branch Bundle (home page, section, taxonomy terms, taxonomy list) + +| | Leaf Bundle | Branch Bundle | +|-------------------------------------|----------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Usage | Collection of content and attachments for single pages | Collection of attachments for section pages (home page, section, taxonomy terms, taxonomy list) | +| Index file name | `index.md` [^fn:1] | `_index.md` [^fn:1] | +| Allowed Resources | Page and non-page (like images, pdf, etc.) types | Only non-page (like images, pdf, etc.) types | +| Where can the Resources live? | At any directory level within the leaf bundle directory. | Only in the directory level **of** the branch bundle directory i.e. the directory containing the `_index.md` ([ref](https://discourse.gohugo.io/t/question-about-content-folder-structure/11822/4?u=kaushalmodi)). | +| Layout type | `single` | `list` | +| Nesting | Does not allow nesting of more bundles under it | Allows nesting of leaf or branch bundles under it | +| Example | `content/posts/my-post/index.md` | `content/posts/_index.md` | +| Content from non-index page files... | Accessed only as page resources | Accessed only as regular pages | + + +## Leaf Bundles {#leaf-bundles} + +A _Leaf Bundle_ is a directory at any hierarchy within the `content/` +directory, that contains an **`index.md`** file. + +### Examples of Leaf Bundle organization {#examples-of-leaf-bundle-organization} + +```text +content/ +├── about +│ ├── index.md +├── posts +│ ├── my-post +│ │ ├── content1.md +│ │ ├── content2.md +│ │ ├── image1.jpg +│ │ ├── image2.png +│ │ └── index.md +│ └── my-other-post +│    └── index.md +│ +└── another-section + ├── .. +    └── not-a-leaf-bundle + ├── .. +    └── another-leaf-bundle +    └── index.md +``` + +In the above example `content/` directory, there are four leaf +bundles: + +about +: This leaf bundle is at the root level (directly under + `content` directory) and has only the `index.md`. + +my-post +: This leaf bundle has the `index.md`, two other content + Markdown files and two image files. + +image1 +: This image is a page resource of `my-post` + and only available in `my-post/index.md` resources. + +image2 +: This image is a page resource of `my-post` + and only available in `my-post/index.md` resources. + +my-other-post +: This leaf bundle has only the `index.md`. + +another-leaf-bundle +: This leaf bundle is nested under couple of + directories. This bundle also has only the `index.md`. + +{{% note %}} +The hierarchy depth at which a leaf bundle is created does not matter, +as long as it is not inside another **leaf** bundle. +{{% /note %}} + + +### Headless Bundle {#headless-bundle} + +A headless bundle is a bundle that is configured to not get published +anywhere: + +- It will have no `Permalink` and no rendered HTML in `public/`. +- It will not be part of `.Site.RegularPages`, etc. + +But you can get it by `.Site.GetPage`. Here is an example: + +```go-html-template +{{ $headless := .Site.GetPage "/some-headless-bundle" }} +{{ $reusablePages := $headless.Resources.Match "author*" }} +

Authors

+{{ range $reusablePages }} +

{{ .Title }}

+ {{ .Content }} +{{ end }} +``` + +_In this example, we are assuming the `some-headless-bundle` to be a headless + bundle containing one or more **page** resources whose `.Name` matches + `"author*"`._ + +Explanation of the above example: + +1. Get the `some-headless-bundle` Page "object". +2. Collect a *slice* of resources in this *Page Bundle* that matches + `"author*"` using `.Resources.Match`. +3. Loop through that *slice* of nested pages, and output their `.Title` and + `.Content`. + +--- + +A leaf bundle can be made headless by adding below in the Front Matter +(in the `index.md`): + +```toml +headless = true +``` + +There are many use cases of such headless page bundles: + +- Shared media galleries +- Reusable page content "snippets" + + +## Branch Bundles {#branch-bundles} + +A _Branch Bundle_ is any directory at any hierarchy within the +`content/` directory, that contains at least an **`_index.md`** file. + +This `_index.md` can also be directly under the `content/` directory. + +{{% note %}} +Here `md` (markdown) is used just as an example. You can use any file +type as a content resource as long as it is a content type recognized by Hugo. +{{% /note %}} + + +### Examples of Branch Bundle organization {#examples-of-branch-bundle-organization} + +```text +content/ +├── branch-bundle-1 +│   ├── branch-content1.md +│   ├── branch-content2.md +│   ├── image1.jpg +│   ├── image2.png +│   └── _index.md +└── branch-bundle-2 + ├── _index.md + └── a-leaf-bundle + └── index.md +``` + +In the above example `content/` directory, there are two branch +bundles (and a leaf bundle): + +`branch-bundle-1` +: This branch bundle has the `_index.md`, two + other content Markdown files and two image files. + +`branch-bundle-2` +: This branch bundle has the `_index.md` and a + nested leaf bundle. + +{{% note %}} +The hierarchy depth at which a branch bundle is created does not +matter. +{{% /note %}} + - [^fn:1]: The `.md` extension is just an example. The extension can be `.html`, `.json` or any of any valid MIME type. ++[^fn:1]: The `.md` extension is just an example. The extension can be `.html`, `.json` or any valid MIME type. diff --cc docs/content/en/functions/with.md index 3fad8bd9c,000000000..a5c27d4f3 mode 100644,000000..100644 --- a/docs/content/en/functions/with.md +++ b/docs/content/en/functions/with.md @@@ -1,31 -1,0 +1,35 @@@ +--- +title: with +# linktitle: with - description: Rebinds the context (`.`) within its scope and skips the block if the variable is absent. ++description: Rebinds the context (`.`) within its scope and skips the block if the variable is absent or empty. +godocref: +date: 2017-02-01 +publishdate: 2017-02-01 +lastmod: 2017-03-12 +categories: [functions] +menu: + docs: + parent: "functions" +keywords: [conditionals] +signature: ["with INPUT"] +workson: [] +hugoversion: +relatedfuncs: [] +deprecated: false +--- + - An alternative way of writing an `if` statement 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 or unset. ++An alternative way of writing an `if` statement 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, unset or empty. ++ ++The set of *empty* values is defined by [the Go templates package](https://golang.org/pkg/text/template/). Empty values include `false`, the number zero, and the empty string. ++ ++If you want to render a block if an index or key is present in a slice, array, channel or map, regardless of whether the value is empty, you should use [`isset`](/functions/isset) instead. + +The following example checks for a [user-defined site variable](/variables/site/) called `twitteruser`. If the key-value is not set, the following will render nothing: + +{{< code file="layouts/partials/twitter.html" >}} +{{with .Site.Params.twitteruser}}{{end}} +{{< /code >}} diff --cc docs/content/en/getting-started/configuration.md index d12ecdf3b,000000000..fbfa676bf mode 100644,000000..100644 --- a/docs/content/en/getting-started/configuration.md +++ b/docs/content/en/getting-started/configuration.md @@@ -1,575 -1,0 +1,586 @@@ +--- +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 +--- + + +## Configuration File + +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 %}} + +{{< todo >}}TODO: distinct config.toml and others (the root object files){{< /todo >}} + +## Configuration Directory + +In addition to using a single site config file, one can use the `configDir` directory (default to `config/`) to maintain easier organization and environment specific settings. + - - Each file represents a configuration root object, such as `Params`, `Menus`, `Languages` etc... ++- Each file represents a configuration root object, such as `params.toml` for `[Params]`, `menu(s).toml` for `[Menu]`, `languages.toml` for `[Languages]` etc... ++- Each file's content must be top-level, for example: ++ ++ In `config.toml` is: ++ ```toml ++ [Params] ++ foo = "bar" ++ ``` ++ In `params.toml` is: ++ ``` ++ foo = "bar" ++ ``` +- Each directory holds a group of files containing settings unique to an environment. +- Files can be localized to become language specific. + + +``` +├── config +│ ├── _default +│ │ ├── config.toml +│ │ ├── languages.toml +│ │ ├── menus.en.toml +│ │ ├── menus.zh.toml +│ │ └── params.toml +│ ├── production +│ │ ├── config.toml +│ │ └── params.toml +│ └── staging +│ ├── config.toml +│ └── params.toml +``` + +Considering the structure above, when running `hugo --environment staging`, Hugo will use every settings from `config/_default` and merge `staging`'s on top of those. +{{% note %}} +Default environments are __development__ with `hugo server` and __production__ with `hugo`. +{{%/ 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). {{% module-mounts-note %}} + +assetDir ("assets") +: The directory where Hugo finds asset files used in [Hugo Pipes](/hugo-pipes/). {{% module-mounts-note %}} + +baseURL +: Hostname (and path) to the root, e.g. https://bep.is/ + +blackfriday +: See [Configure Blackfriday](/getting-started/configuration-markup#blackfriday) + +build +: See [Configure Build](#configure-build) + +buildDrafts (false) +: Include drafts when building. + +buildExpired (false) +: Include content already expired. + +buildFuture (false) +: Include content with publishdate in the future. + +caches +: See [Configure File Caches](#configure-file-caches) + +canonifyURLs (false) +: Enable to turn relative URLs into absolute. + +contentDir ("content") +: The directory from where Hugo reads content files. {{% module-mounts-note %}} + +dataDir ("data") +: The directory from where Hugo reads data files. {{% module-mounts-note %}} + +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/`. + +disableAliases (false) +: Will disable generation of alias redirects. Note that even if `disableAliases` is set, the aliases themselves are preserved on the page. The motivation with this is to be able to generate 301 redirects in an `.htaccess`, a Netlify `_redirects` file or similar using a custom output format. + +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"`, `"term"`, `"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. + +enableInlineShortcodes (false) +: Enable inline shortcode support. See [Inline Shortcodes](/templates/shortcode-templates/#inline-shortcodes). + +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. It is used in the default [RSS template](/templates/rss/#configure-rss) and can be useful for [multi-lingual sites](/content-management/multilingual/#configure-multilingual-multihost). + +languageName ("") +: The site's language name. + +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). + +markup +: See [Configure Markup](/getting-started/configuration-markup).{{< new-in "0.60.0" >}} + +menu +: See [Add Non-content Entries to a Menu](/content-management/menus/#add-non-content-entries-to-a-menu). + +minify +: See [Configure Minify](#configure-minify) + +module +: Module config see [Module Config](/hugo-modules/configuration/).{{< new-in "0.56.0" >}} + +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 elements 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. + +publishDir ("public") +: The directory to where Hugo will write the final static site (the HTML files etc.). + +related +: See [Related Content](/content-management/related/#configure-related-content).{{< new-in "0.27" >}} + +relativeURLs (false) +: Enable this to make all relative URLs relative to content root. Note that this does not affect absolute URLs. + +refLinksErrorLevel ("ERROR") +: When using `ref` or `relref` to resolve page links and a link cannot resolved, it will be logged with this logg level. Valid values are `ERROR` (default) or `WARNING`. Any `ERROR` will fail the build (`exit -1`). + +refLinksNotFoundURL +: URL to be used as a placeholder when a page reference cannot be found in `ref` or `relref`. Is used as-is. + +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") +: A directory or a list of directories from where Hugo reads [static files][static-files]. {{% module-mounts-note %}} + +summaryLength (70) +: The length of text in words 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. + +titleCaseStyle ("AP") +: See [Configure Title Case](#configure-title-case) + +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 %}} + +## Configure Build + +{{< new-in "0.66.0" >}} + +The `build` configuration section contains global build-related configuration options. + +{{< code-toggle file="config">}} +[build] +useResourceCacheWhen="fallback" +writeStats = false +noJSConfigInAssets = false +{{< /code-toggle >}} + + +useResourceCacheWhen +: When to use the cached resources in `/resources/_gen` for PostCSS and ToCSS. Valid values are `never`, `always` and `fallback`. The last value means that the cache will be tried if PostCSS/extended version is not available. + +writeStats {{< new-in "0.69.0" >}} +: When enabled, a file named `hugo_stats.json` will be written to your project root with some aggregated data about the build, e.g. list of HTML entities published to be used to do [CSS pruning](/hugo-pipes/postprocess/#css-purging-with-postcss). If you're only using this for the production build, you should consider placing it below [config/production](/getting-started/configuration/#configuration-directory). It's also worth mentioning that, due to the nature of the partial server builds, new HTML entities will be added when you add or change them while the server is running, but the old values will not be removed until you restart the server or run a regular `hugo` build. + +noJSConfigInAssets {{< new-in "0.78.0" >}} +: Turn off writing a `jsconfig.js` into your `/assets` folder with mapping of imports from running [js.Build](https://gohugo.io/hugo-pipes/js). This file is intended to help with intellisense/navigation inside code editors such as [VS Code](https://code.visualstudio.com/). Note that if you do not use `js.Build`, no file will be written. + +## Configure Server + +{{< new-in "0.67.0" >}} + +This is only relevant when running `hugo server`, and it allows to set HTTP headers during development, which allows you to test out your Content Security Policy and similar. The configuration format matches [Netlify's](https://docs.netlify.com/routing/headers/#syntax-for-the-netlify-configuration-file) with slighly more powerful [Glob matching](https://github.com/gobwas/glob): + + +{{< code-toggle file="config">}} +[server] +[[server.headers]] +for = "/**.html" + +[server.headers.values] +X-Frame-Options = "DENY" +X-XSS-Protection = "1; mode=block" +X-Content-Type-Options = "nosniff" +Referrer-Policy = "strict-origin-when-cross-origin" +Content-Security-Policy = "script-src localhost:1313" +{{< /code-toggle >}} + +Since this is is "development only", it may make sense to put it below the `development` environment: + + +{{< code-toggle file="config/development/server">}} +[[headers]] +for = "/**.html" + +[headers.values] +X-Frame-Options = "DENY" +X-XSS-Protection = "1; mode=block" +X-Content-Type-Options = "nosniff" +Referrer-Policy = "strict-origin-when-cross-origin" +Content-Security-Policy = "script-src localhost:1313" +{{< /code-toggle >}} + + +{{< new-in "0.72.0" >}} + +You can also specify simple redirects rules for the server. The syntax is again similar to Netlify's. + +Note that a `status` code of 200 will trigger a [URL rewrite](https://docs.netlify.com/routing/redirects/rewrites-proxies/), which is what you want in SPA situations, e.g: + +{{< code-toggle file="config/development/server">}} +[[redirects]] +from = "/myspa/**" +to = "/myspa/" +status = 200 +force = false +{{< /code-toggle >}} + +{{< new-in "0.76.0" >}} Setting `force=true` will make a redirect even if there is existing content in the path. Note that before Hugo 0.76 `force` was the default behaviour, but this is inline with how Netlify does it. + +## Configure Title Case + +Set `titleCaseStyle` to specify the title style used by the [title](/functions/title/) template function and the automatic section titles in Hugo. It defaults to [AP Stylebook](https://www.apstylebook.com/) for title casing, but you can also set it to `Chicago` or `Go` (every word starts with a capital letter). + +## Configuration Environment Variables + +HUGO_NUMWORKERMULTIPLIER +: Can be set to increase or reduce the number of workers used in parallel processing in Hugo. If not set, the number of logical CPUs will be used. + +## 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: + posts: /: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. + +To set config params, prefix the name with `HUGO_PARAMS_` +{{% /note %}} + +{{< new-in "0.79.0" >}} If you are using snake_cased variable names, the above will not work, so since Hugo 0.79.0 Hugo determines the delimiter to use by the first character after `HUGO`. This allows you to define environment variables on the form `HUGOxPARAMSxAPI_KEY=abcdefgh`, using any [allowed](https://stackoverflow.com/questions/2821043/allowed-characters-in-linux-environment-variable-names#:~:text=So%20names%20may%20contain%20any,not%20begin%20with%20a%20digit.) delimiter. + +{{< todo >}} +Test and document setting params via JSON env var. +{{< /todo >}} + +## Ignore Content Files When Rendering + +The following statement inside `./config.toml` will cause Hugo to ignore content 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, `2018-02-22-mypage.md` will extract the date `2018-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 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. + +## Configure Minify + +{{< new-in "0.68.0" >}} + +Default configuration: + +{{< code-toggle config="minify" />}} + +## Configure File Caches + +Since Hugo 0.52 you can configure more than just the `cacheDir`. This is the default configuration: + +{{< code-toggle >}} +[caches] +[caches.getjson] +dir = ":cacheDir/:project" +maxAge = -1 +[caches.getcsv] +dir = ":cacheDir/:project" +maxAge = -1 +[caches.images] +dir = ":resourceDir/_gen" +maxAge = -1 +[caches.assets] +dir = ":resourceDir/_gen" +maxAge = -1 +[caches.modules] +dir = ":cacheDir/modules" +maxAge = -1 +{{< /code-toggle >}} + +You can override any of these cache settings in your own `config.toml`. + +### The keywords explained + +`:cacheDir` +: This is the value of the `cacheDir` config option if set (can also be set via OS env variable `HUGO_CACHEDIR`). It will fall back to `/opt/build/cache/hugo_cache/` on Netlify, or a `hugo_cache` directory below the OS temp dir for the others. This means that if you run your builds on Netlify, all caches configured with `:cacheDir` will be saved and restored on the next build. For other CI vendors, please read their documentation. For an CircleCI example, see [this configuration](https://github.com/bep/hugo-sass-test/blob/6c3960a8f4b90e8938228688bc49bdcdd6b2d99e/.circleci/config.yml). + +`:project` +: The base directory name of the current Hugo project. This means that, in its default setting, every project will have separated file caches, which means that when you do `hugo --gc` you will not touch files related to other Hugo projects running on the same PC. + +`:resourceDir` +: This is the value of the `resourceDir` config option. + +maxAge +: This is the duration before a cache entry will be evicted, -1 means forever and 0 effectively turns that particular cache off. Uses Go's `time.Duration`, so valid values are `"10s"` (10 seconds), `"10m"` (10 minutes) and `"10h"` (10 hours). + +dir +: The absolute path to where the files for this cache will be stored. Allowed starting placeholders are `:cacheDir` and `:resourceDir` (see above). + +## 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]: https://yaml.org/spec/ +[static-files]: /content-management/static-files/ diff --cc docs/content/en/getting-started/external-learning-resources/index.md index 573fdfdbf,000000000..349d7e29d mode 100644,000000..100644 --- a/docs/content/en/getting-started/external-learning-resources/index.md +++ b/docs/content/en/getting-started/external-learning-resources/index.md @@@ -1,33 -1,0 +1,37 @@@ +--- +title: External Learning Resources +linktitle: External Learning Resources +description: A list of tutorials and books on Hugo. +date: 2019-10-20 +publishdate: 2019-10-20 +lastmod: 2019-10-20 +keywords: [books, tutorials, learning, usage] +menu: + docs: + parent: "getting-started" + weight: 70 +weight: 70 +sections_weight: 70 +draft: false +toc: false +--- + +## Books + +### Hugo In Action + +[![Hugo In Action](hia.jpg)](https://www.manning.com/books/hugo-in-action) + +Hugo in Action is a step-by-step guide to using Hugo to create static websites. Working with a complete example website and source code samples, you’ll learn how to build and host a low-maintenance, high-performance site that will wow your users and stay stable without relying on a third-party server. + +[Hugo In Action Home Page](https://www.manning.com/books/hugo-in-action) + ++### Build Websites with Hugo ++ ++[Build Websites with Hugo - Fast Web Development with Markdown (2020)](https://pragprog.com/titles/bhhugo/) by Brian P. Hogan. ++ +## Video tutorials + +### Video Playlist by Mike Dane + +Mike Dane explains the various features of Hugo via dedicated tutorials on [YouTube](https://www.youtube.com/watch?list=PLLAZ4kZ9dFpOnyRlyS-liKL5ReHDcj4G3&v=qtIqKaDlqXo). diff --cc docs/content/en/hosting-and-deployment/hosting-on-github.md index 70803d360,000000000..55cfcccd6 mode 100644,000000..100644 --- a/docs/content/en/hosting-and-deployment/hosting-on-github.md +++ b/docs/content/en/hosting-and-deployment/hosting-on-github.md @@@ -1,253 -1,0 +1,253 @@@ +--- +title: Host on GitHub +linktitle: Host on GitHub +description: Deploy Hugo as a GitHub Pages project or personal/organizational site and automate the whole process with a simple shell script. +date: 2014-03-21 +publishdate: 2014-03-21 +lastmod: 2018-09-22 +categories: [hosting and deployment] +keywords: [github,git,deployment,hosting] +authors: [Spencer Lyon, Gunnar Morling] +menu: + docs: + parent: "hosting-and-deployment" + weight: 30 +weight: 30 +sections_weight: 30 +draft: false +toc: true +aliases: [/tutorials/github-pages-blog/] +--- + +GitHub provides free and fast static hosting over SSL for personal, organization, or project pages directly from a GitHub repository via its [GitHub Pages service][]. + +## Assumptions + +1. You have Git 2.8 or greater [installed on your machine][installgit]. +2. You have a GitHub account. [Signing up][ghsignup] for GitHub is free. +3. You have a ready-to-publish Hugo website or have at least completed the [Quick Start][]. + +## Types of GitHub Pages + +There are 2 types of GitHub Pages: + +- User/Organization Pages (`https://.github.io/`) +- Project Pages (`https://.github.io//`) + +Please refer to the [GitHub Pages documentation][ghorgs] to decide which type of site you would like to create as it will determine which of the below methods to use. + +To create a User/Organization Pages site, follow the single method in the *GitHub User and Organization Pages* section below. + +To create a Project Pages site, choose a method from the *Project Pages* section below. + +## GitHub User or Organization Pages + +As mentioned in the [GitHub Pages documentation][ghorgs], you can host a user/organization page in addition to project pages. Here are the key differences in GitHub Pages websites for Users and Organizations: + +1. You must use a `.github.io` to host your **generated** content +2. Content from the `main` branch will be used to publish your GitHub Pages site + +This is a much simpler setup as your Hugo files and generated content are published into two different repositories. + +### Step-by-step Instructions + +1. Create a `` (e.g. `blog`) repository on GitHub. This repository will contain Hugo's content and other source files. +2. Create a `.github.io` GitHub repository. This is the repository that will contain the fully rendered version of your Hugo website. +3. `git clone && cd ` +4. Paste your existing Hugo project into the new local `` repository. Make sure your website works locally (`hugo server` or `hugo server -t `) and open your browser to . +5. Once you are happy with the results: + * Press Ctrl+C to kill the server + * Before proceeding run `rm -rf public` to completely remove the `public` directory +6. `git submodule add -b main https://github.com//.github.io.git public`. This creates a git [submodule][]. Now when you run the `hugo` command to build your site to `public`, the created `public` directory will have a different remote origin (i.e. hosted GitHub repository). +7. Make sure the `baseURL` in your config file is updated with: `.github.io` + +### Put it Into a Script + +You're almost done. In order to automate next steps create a `deploy.sh` script. You can also make it executable with `chmod +x deploy.sh`. + +The following are the contents of the `deploy.sh` script: + +``` +#!/bin/sh + +# If a command fails then the deploy stops +set -e + +printf "\033[0;32mDeploying updates to GitHub...\033[0m\n" + +# Build the project. +hugo # if using a theme, replace with `hugo -t ` + +# Go To Public folder +cd public + +# Add changes to git. +git add . + +# Commit changes. +msg="rebuilding site $(date)" +if [ -n "$*" ]; then + msg="$*" +fi +git commit -m "$msg" + +# Push source and build repos. +git push origin main +``` + + +You can then run `./deploy.sh "Your optional commit message"` to send changes to `.github.io`. Note that you likely will want to commit changes to your `` repository as well. + +That's it! Your personal page should be up and running at `https://.github.io` within a couple minutes. + +## GitHub Project Pages + +{{% note %}} +Make sure your `baseURL` key-value in your [site configuration](/getting-started/configuration/) reflects the full URL of your GitHub pages repository if you're using the default GH Pages URL (e.g., `.github.io//`) and not a custom domain. +{{% /note %}} + +### Deployment of Project Pages from `/docs` folder on `main` branch + +[As described in the GitHub Pages documentation][ghpfromdocs], you can deploy from a folder called `docs/` on your main branch. To effectively use this feature with Hugo, you need to change the Hugo publish directory in your [site's][config] `config.toml` and `config.yaml`, respectively: + +``` +publishDir = "docs" +``` +``` +publishDir: docs +``` + +After running `hugo`, push your main branch to the remote repository and choose the `docs/` folder as the website source of your repo. Do the following from within your GitHub project: + +1. Go to **Settings** → **GitHub Pages** +2. From **Source**, select "main branch /docs folder". If the option isn't enabled, you likely do not have a `docs/` folder in the root of your project. + +{{% note %}} +The `docs/` option is the simplest approach but requires you set a publish directory in your site configuration. You cannot currently configure GitHub pages to publish from another directory on main, and not everyone prefers the output site live concomitantly with source files in version control. +{{% /note %}} + +### Deployment of Project Pages From Your `gh-pages` branch + +You can also tell GitHub pages to treat your `main` branch as the published site or point to a separate `gh-pages` branch. The latter approach is a bit more complex but has some advantages: + +* It keeps your source and generated website in different branches and therefore maintains version control history for both. +* Unlike the preceding `docs/` option, it uses the default `public` folder. + +#### Preparations for `gh-pages` Branch + +These steps only need to be done once. Replace `upstream` with the name of your remote; e.g., `origin`: + +##### Add the `public` Folder + +First, add the `public` folder to your `.gitignore` file at the project root so that the directory is ignored on the main branch: + +``` +echo "public" >> .gitignore +``` + +##### Initialize Your `gh-pages` Branch + +You can now initialize your `gh-pages` branch as an empty [orphan branch][]: + +``` +git checkout --orphan gh-pages +git reset --hard +git commit --allow-empty -m "Initializing gh-pages branch" +git push upstream gh-pages +git checkout main +``` + +#### Build and Deployment + +Now check out the `gh-pages` branch into your `public` folder using git's [worktree feature][]. Essentially, the worktree allows you to have multiple branches of the same local repository to be checked out in different directories: + +``` +rm -rf public +git worktree add -B gh-pages public upstream/gh-pages +``` + +Regenerate the site using the `hugo` command and commit the generated files on the `gh-pages` branch: + +{{< code file="commit-gh-pages-files.sh">}} +hugo +cd public && git add --all && git commit -m "Publishing to gh-pages" && cd .. +{{< /code >}} + +If the changes in your local `gh-pages` branch look alright, push them to the remote repo: + +``` +git push upstream gh-pages +``` + +##### Set `gh-pages` as Your Publish Branch + +In order to use your `gh-pages` branch as your publishing branch, you'll need to configure the repository within the GitHub UI. This will likely happen automatically once GitHub realizes you've created this branch. You can also set the branch manually from within your GitHub project: + +1. Go to **Settings** → **GitHub Pages** +2. From **Source**, select "gh-pages branch" and then **Save**. If the option isn't enabled, you likely have not created the branch yet OR you have not pushed the branch from your local machine to the hosted repository on GitHub. + +After a short while, you'll see the updated contents on your GitHub Pages site. + +#### Put it Into a Script + +To automate these steps, you can create a script with the following contents: + +{{< code file="publish_to_ghpages.sh" >}} +#!/bin/sh + +if [ "`git status -s`" ] +then + echo "The working directory is dirty. Please commit any pending changes." + exit 1; +fi + +echo "Deleting old publication" +rm -rf public +mkdir public +git worktree prune +rm -rf .git/worktrees/public/ + +echo "Checking out gh-pages branch into public" +git worktree add -B gh-pages public upstream/gh-pages + +echo "Removing existing files" +rm -rf public/* + +echo "Generating site" +hugo + +echo "Updating gh-pages branch" +cd public && git add --all && git commit -m "Publishing to gh-pages (publish.sh)" + +#echo "Pushing to github" +#git push --all +{{< /code >}} + +This will abort if there are pending changes in the working directory and also makes sure that all previously existing output files are removed. Adjust the script to taste, e.g. to include the final push to the remote repository if you don't need to take a look at the gh-pages branch before pushing. + +### Deployment of Project Pages from Your `main` Branch + +To use `main` as your publishing branch, you'll need your rendered website to live at the root of the GitHub repository. Steps should be similar to that of the `gh-pages` branch, with the exception that you will create your GitHub repository with the `public` directory as the root. Note that this does not provide the same benefits of the `gh-pages` branch in keeping your source and output in separate, but version controlled, branches within the same repo. + +You will also need to set `main` as your publishable branch from within the GitHub UI: + +1. Go to **Settings** → **GitHub Pages** +2. From **Source**, select "main branch" and then **Save**. + +## Use a Custom Domain + +If you'd like to use a custom domain for your GitHub Pages site, create a file `static/CNAME`. Your custom domain name should be the only contents inside `CNAME`. Since it's inside `static`, the published site will contain the CNAME file at the root of the published site, which is a requirements of GitHub Pages. + +Refer to the [official documentation for custom domains][domains] for further information. + +[config]: /getting-started/configuration/ +[domains]: https://help.github.com/articles/using-a-custom-domain-with-github-pages/ +[ghorgs]: https://help.github.com/articles/user-organization-and-project-pages/#user--organization-pages +[ghpfromdocs]: https://help.github.com/articles/configuring-a-publishing-source-for-github-pages/ +[ghsignup]: https://github.com/join +[GitHub Pages service]: https://help.github.com/articles/what-is-github-pages/ +[installgit]: https://git-scm.com/downloads - [orphan branch]: https://git-scm.com/docs/git-checkout/#git-checkout---orphanltnewbranchgt ++[orphan branch]: https://git-scm.com/docs/git-checkout/#Documentation/git-checkout.txt---orphanltnewbranchgt +[Quick Start]: /getting-started/quick-start/ +[submodule]: https://github.com/blog/2104-working-with-submodules +[worktree feature]: https://git-scm.com/docs/git-worktree diff --cc docs/content/en/hosting-and-deployment/hosting-on-render.md index eb7947161,000000000..f23cb42ba mode 100644,000000..100644 --- a/docs/content/en/hosting-and-deployment/hosting-on-render.md +++ b/docs/content/en/hosting-and-deployment/hosting-on-render.md @@@ -1,93 -1,0 +1,92 @@@ +--- +title: Host on Render +linktitle: Host on Render +description: Host your Hugo site for free with Render's global CDN, fully-managed SSL and auto deploys from GitHub. +date: 2019-06-06 +publishdate: 2019-06-06 +lastmod: 2020-01-01 +categories: [hosting and deployment] +keywords: [render,hosting,deployment] +authors: [Anurag Goel] +menu: + docs: + parent: "hosting-and-deployment" + weight: 10 +weight: 10 +sections_weight: 10 +draft: false +aliases: [] +toc: true +--- + +## Introduction + +[Render](https://render.com) is a fully-managed cloud platform where you can host static sites, backend APIs, databases, cron jobs, and all your other apps in one place. + +Static sites are **completely free** on Render and include the following: + +- Continuous, automatic builds & deploys from [GitHub](https://render.com/docs/github) and [GitLab](https://render.com/docs/gitlab). +- Automatic SSL certificates through [Let's Encrypt](https://letsencrypt.org). +- Instant cache invalidation with a lightning fast, global CDN. +- Unlimited collaborators. +- Unlimited [custom domains](https://render.com/docs/custom-domains). +- Automatic [Brotli compression](https://en.wikipedia.org/wiki/Brotli) for faster sites. +- Native HTTP/2 support. +- [Pull Request Previews](https://render.com/docs/pull-request-previews). +- Automatic HTTP → HTTPS redirects. +- Custom URL redirects and rewrites. + +## Assumptions + +* You have an account with GitHub or GitLab. +* You have completed the [Quick Start][] or have a Hugo website you are ready to deploy and share with the world. +* You have a Render account. You can sign up at https://render.com/register. + +## Deployment + +You can set up a Hugo site on Render in two quick steps: + - 1. Create a new **Web Service** on Render, and give Render permission to access your GitHub/Gitlab repo. ++1. Create a new **Static Site** on Render, and give Render permission to access your GitHub/Gitlab repo. +2. Use the following values during creation: + + Field | Value + ------------------- | ------------------- - **Environment** | `Static Site` + **Build Command** | `hugo --gc --minify` (or your own build command) + **Publish Directory** | `public` (or your own output directory) + +That's it! Your site will be live on your Render URL (which looks like `yoursite.onrender.com`) as soon as the build is done. + +## Continuous Deploys + +Now that Render is connected to your repo, it will **automatically build and publish your site** any time you push to your GitHub/Gitlab. + +You can choose to disable auto deploys under the **Settings** section for your site and deploy it manually from the Render dashboard. + +## CDN and Cache Invalidation + +Render hosts your site on a global, lightning fast CDN which ensures the fastest possible download times for all your users across the globe. + +Every deploy automatically and instantly invalidates the CDN cache, so your users can always access the latest content on your site. + +## Custom Domains + +Add your own domains to your site easily using Render's [custom domains](https://render.com/docs/custom-domains) guide. + +## Pull Request Previews + +With Pull Request (PR) previews, you can visualize changes introduced in a pull request instead of simply relying on code reviews. + +Once enabled, every PR for your site will automatically generate a new static site based on the code in the PR. It will have its own URL, and it will be deleted automatically when the PR is closed. + +Read more about [Pull Request Previews](https://render.com/docs/pull-request-previews) on Render. + +## Hugo Themes + +Render automatically downloads all Git submodules defined in your Git repo on every build. This way Hugo themes added as submodules work as expected. + +## Support + +Chat with Render developers at https://render.com/chat or email `support@render.com` if you need help. + + +[Quick Start]: /getting-started/quick-start/ diff --cc docs/content/en/hugo-modules/use-modules.md index aa03489d2,000000000..db12964b4 mode 100644,000000..100644 --- a/docs/content/en/hugo-modules/use-modules.md +++ b/docs/content/en/hugo-modules/use-modules.md @@@ -1,142 -1,0 +1,143 @@@ +--- +title: Use Hugo Modules +linktitle: Use Hugo Modules +description: How to use Hugo Modules to build and manage your site. +date: 2019-07-24 +categories: [hugo modules] +keywords: [install, themes, source, organization, directories,usage,modules] +menu: + docs: + parent: "modules" + weight: 20 +weight: 20 +sections_weight: 20 +draft: false +aliases: [/themes/usage/,/themes/installing/,/installing-and-using-themes/] +toc: true +--- + +## Prerequisite + +{{< gomodules-info >}} + + + +## Initialize a New Module + +Use `hugo mod init` to initialize a new Hugo Module. If it fails to guess the module path, you must provide it as an argument, e.g.: + +```bash +hugo mod init github.com/gohugoio/myShortcodes +``` + +Also see the [CLI Doc](/commands/hugo_mod_init/). + +## Use a Module for a Theme +The easiest way to use a Module for a theme is to import it in the config. + +1. Initialize the hugo module system: `hugo mod init github.com//` +2. Import the theme in your `config.toml`: + +```toml +[module] + [[module.imports]] + path = "github.com/spf13/hyde" +``` + +## Update Modules + +Modules will be downloaded and added when you add them as imports to your configuration, see [Module Imports](/hugo-modules/configuration/#module-config-imports). + +To update or manage versions, you can use `hugo mod get`. + +Some examples: + +### Update All Modules + +```bash +hugo mod get -u +``` + +### Update All Modules Recursively + +{{< new-in "0.65.0" >}} + +```bash +hugo mod get -u ./... +``` + +### Update One Module + +```bash +hugo mod get -u github.com/gohugoio/myShortcodes +``` +### Get a Specific Version + +```bash +hugo mod get github.com/gohugoio/myShortcodes@v1.0.7 +``` + +Also see the [CLI Doc](/commands/hugo_mod_get/). + +## Make and test changes in a module + +One way to do local development of a module imported in a project is to add a replace directive to a local directory with the source in `go.mod`: + +```bash +replace github.com/bep/hugotestmods/mypartials => /Users/bep/hugotestmods/mypartials +``` + +If you have the `hugo server` running, the configuration will be reloaded and `/Users/bep/hugotestmods/mypartials` put on the watch list. + ++Note that since v.0.77.0 you can use modules config [`replacements`](https://gohugo.io/hugo-modules/configuration/#module-config-top-level) option. {{< new-in "0.77.0" >}} + +## Print Dependency Graph + + +Use `hugo mod graph` from the relevant module directory and it will print the dependency graph, including vendoring, module replacement or disabled status. + +E.g.: + +``` +hugo mod graph + +github.com/bep/my-modular-site github.com/bep/hugotestmods/mymounts@v1.2.0 +github.com/bep/my-modular-site github.com/bep/hugotestmods/mypartials@v1.0.7 +github.com/bep/hugotestmods/mypartials@v1.0.7 github.com/bep/hugotestmods/myassets@v1.0.4 +github.com/bep/hugotestmods/mypartials@v1.0.7 github.com/bep/hugotestmods/myv2@v1.0.0 +DISABLED github.com/bep/my-modular-site github.com/spf13/hyde@v0.0.0-20190427180251-e36f5799b396 +github.com/bep/my-modular-site github.com/bep/hugo-fresh@v1.0.1 +github.com/bep/my-modular-site in-themesdir + +``` + +Also see the [CLI Doc](/commands/hugo_mod_graph/). + +## Vendor Your Modules + +`hugo mod vendor` will write all the module dependencies to a `_vendor` folder, which will then be used for all subsequent builds. + +Note that: + +* You can run `hugo mod vendor` on any level in the module tree. +* Vendoring will not store modules stored in your `themes` folder. +* Most commands accept a `--ignoreVendorPaths` flag, which will then not use the vendored modules in `_vendor` for the module paths matching the [Glob](https://github.com/gobwas/glob) pattern given. Note that before Hugo 0.75 this flag was named `--ignoreVendor` and was a "all or nothing". {{< new-in "0.75.0" >}} + +Also see the [CLI Doc](/commands/hugo_mod_vendor/). + + +## Tidy go.mod, go.sum + +Run `hugo mod tidy` to remove unused entries in `go.mod` and `go.sum`. + +Also see the [CLI Doc](/commands/hugo_mod_clean/). + +## Clean Module Cache + +Run `hugo mod clean` to delete the entire modules cache. + +Note that you can also configure the `modules` cache with a `maxAge`, see [File Caches](/hugo-modules/configuration/#configure-file-caches). + + + +Also see the [CLI Doc](/commands/hugo_mod_clean/). diff --cc docs/content/en/hugo-pipes/js.md index 5e9c027d5,000000000..fd8697264 mode 100644,000000..100644 --- a/docs/content/en/hugo-pipes/js.md +++ b/docs/content/en/hugo-pipes/js.md @@@ -1,155 -1,0 +1,173 @@@ +--- +title: JavaScript Building +description: Hugo Pipes can process JavaScript files with [ESBuild](https://github.com/evanw/esbuild). +date: 2020-07-20 +publishdate: 2020-07-20 +lastmod: 2020-07-20 +categories: [asset management] +keywords: [] +menu: + docs: + parent: "pipes" + weight: 45 +weight: 45 +sections_weight: 45 +draft: false +--- + +Any JavaScript resource file can be transpiled and "tree shaken" using `js.Build` which takes for argument either a string for the filepath or a dict of options listed below. + +### Options + +targetPath [string] +: If not set, the source path will be used as the base target path. +Note that the target path's extension may change if the target MIME type is different, e.g. when the source is TypeScript. + +params [map or slice] {{< new-in "0.78.0" >}} +: Params that can be imported as JSON in your JS files, e.g.: + +```go-html-template - {{ $js := resources.Get "js/main.js" | js.Build (dict "params" (dict "api" "https://example.org/api" ) }} ++{{ $js := resources.Get "js/main.js" | js.Build (dict "params" (dict "api" "https://example.org/api")) }} +``` +And then in your JS file: + +```js +import * as params from '@params'; +``` + +Note that this is meant for small data sets, e.g. config settings. For larger data, please put/mount the files into `/assets` and import them directly. + +minify [bool] +: Let `js.Build` handle the minification. + ++avoidTDZ {{< new-in "0.78.0" >}} ++: There is/was a bug in WebKit with severe performance issue with the tracking of TDZ checks in JavaScriptCore. Enabling this flag removes the TDZ and `const` assignment checks and may improve performance of larger JS codebases until the WebKit fix is in widespread use. See https://bugs.webkit.org/show_bug.cgi?id=199866 ++ +target [string] +: The language target. + One of: `es5`, `es2015`, `es2016`, `es2017`, `es2018`, `es2019`, `es2020` or `esnext`. + Default is `esnext`. + +externals [slice] +: External dependencies. If a dependency should not be included in the bundle (Ex. library loaded from a CDN.), it should be listed here. + +```go-html-template +{{ $externals := slice "react" "react-dom" }} +``` + +> Marking a package as external doesn't imply that the library can be loaded from a CDN. It simply tells Hugo not to expand/include the package in the JS file. + +defines [map] +: Allow to define a set of string replacement to be performed when building. Should be a map where each key is to be replaced by its value. + +```go-html-template +{{ $defines := dict "process.env.NODE_ENV" `"development"` }} +``` + +format [string] {{< new-in "0.74.3" >}} +: The output format. + One of: `iife`, `cjs`, `esm`. + Default is `iife`, a self-executing function, suitable for inclusion as a +``` + +#### Shimming a JS library + +It's a very common practice to load external libraries using CDN rather than importing all packages in a single JS file, making it bulky. To do the same with Hugo, you'll need to shim the libraries as follows. In this example, `algoliasearch` and `instantsearch.js` will be shimmed. + +Firstly, add the following to your project's `package.json`: +```json +{ + "browser": { + "algoliasearch/lite": "./public/js/shims/algoliasearch.js", + "instantsearch.js/es/lib/main": "./public/js/shims/instantsearch.js" + } +} +``` + +What this does is it tells Hugo to look for the listed packages somewhere else. Here we're telling Hugo to look for `algoliasearch/lite` and `instantsearch.js/es/lib/main` in the project's `public/js/shims` folder. + +Now we'll need to create the shim JS files which export the global JS variables `module.exports = window.something`. You can create a separate shim JS file in your `assets` directory, and redirect the import paths there if you wish, but a much cleaner way is to create these files on the go, by having the following before your JS is built. + +```go-html-template +{{ $a := "module.exports = window.algoliasearch" | resources.FromString "js/shims/algoliasearch.js" }} +{{ $i := "module.exports = window.instantsearch" | resources.FromString "js/shims/instantsearch.js" }} + +{{/* Call RelPermalink unnecessarily to generate JS files */}} +{{ $placebo := slice $a.RelPermalink $i.RelPermalink }} +``` +That's it! You should now have a browser-friendly JS which can use external JS libraries. diff --cc docs/content/en/hugo-pipes/resource-from-string.md index 862fcd930,000000000..8b942d2f3 mode 100755,000000..100755 --- a/docs/content/en/hugo-pipes/resource-from-string.md +++ b/docs/content/en/hugo-pipes/resource-from-string.md @@@ -1,31 -1,0 +1,31 @@@ +--- +title: Creating a resource from a string +linkTitle: Resource from String +description: Hugo Pipes allows the creation of a resource from a string. +date: 2018-07-14 +publishdate: 2018-07-14 +lastmod: 2018-07-14 +categories: [asset management] +keywords: [] +menu: + docs: + parent: "pipes" + weight: 90 +weight: 90 +sections_weight: 90 +draft: false +--- + +It is possible to create a resource directly from the template using `resources.FromString` which takes two arguments, the given string and the resource target path. + +The following example creates a resource file containing localized variables for every project's languages. + +```go-html-template - {{ $string := (printf "var rootURL: '%s'; var apiURL: '%s';" (absURL "/") (.Param "API_URL")) }} ++{{ $string := (printf "var rootURL = '%s'; var apiURL = '%s';" (absURL "/") (.Param "API_URL")) }} +{{ $targetPath := "js/vars.js" }} +{{ $vars := $string | resources.FromString $targetPath }} +{{ $global := resources.Get "js/global.js" | resources.Minify }} + + + +``` diff --cc docs/content/en/news/0.78.0-relnotes/featured.png index 000000000,000000000..36ae0ac95 new file mode 100644 Binary files differ diff --cc docs/content/en/news/0.78.0-relnotes/index.md index dd2cd70d5,000000000..fcc20c066 mode 100644,000000..100644 --- a/docs/content/en/news/0.78.0-relnotes/index.md +++ b/docs/content/en/news/0.78.0-relnotes/index.md @@@ -1,50 -1,0 +1,50 @@@ + +--- +date: 2020-11-03 - title: "0.78.0" - description: "0.78.0" ++title: "Hugo 0.78.0: Full Hugo Modules Support in js.Build" ++description: "Resolve JavaScript imports top-down in the layered filesystem, pass parameters from template to JS, new JS intellisense helper, improved JS build errors." +categories: ["Releases"] +--- + - This release finally brings full [Hugo Modules](https://gohugo.io/hugo-modules/) support to [js.Build](https://gohugo.io/hugo-pipes/js/), curtsy of he new plugin API in the really, really fast [ESBuild](https://github.com/evanw/esbuild) by [@evanw](https://github.com/evanw). ++This release finally brings full [Hugo Modules](https://gohugo.io/hugo-modules/) support to [js.Build](https://gohugo.io/hugo-pipes/js/), curtsy of he new plugin API in the really, really fast [ESBuild](https://github.com/evanw/esbuild) by [@evanw](https://github.com/evanw). + +Some notes on the improvements in this release: + - * Now `js.Build` fully supports the virtual union file system in [Hugo Modules](https://gohugo.io/hugo-modules/). Any import inside your JavaScript components will resolve starting from the top component mount inside `/assets` with a fallback to the traditional "JS way" (`node_modules` etc.) ++* Now `js.Build` fully supports the virtual union filesystem in [Hugo Modules](https://gohugo.io/hugo-modules/). Any import inside your JavaScript components will resolve starting from the top component mount inside `/assets` with a fallback to the traditional "JS way" (`node_modules` etc.) +* You can now pass configuration data from the templates to your scripts via a new `params` option. +* Hugo now writes a `jsconfig.js` file inside `/assets` (you can turn it off) with import mappings to help editors such as VS Code with intellisense/navigation, which is especially useful when there is no common root and the source lives inside some temporary directory. +* We have also improved the build errors you get from `js.Build`. In server mode you will get a preview of the failing lines and in the console you will get a link to the location. + +Read more about this in [the documentation](https://gohugo.io/hugo-pipes/js/), but a short usage example would look like: + +In the template: + +```go-html-template +{{ $js := resources.Get "js/main.js" | js.Build (dict "params" (dict "api" "https://example.org/api" ) }} +``` + +And then in a JavaScript component: + +```js +import * as params from '@params'; + - // Wil resolve to one of `hello.{js,ts,tsx,jsx}` inside `assets/my/module`. ++// Will resolve to one of `hello.{js,ts,tsx,jsx}` inside `assets/my/module`. +import { hello } from 'my/module/hello'; + +var api = params.api; + +hello(); + +``` + +## Changes + +* Add avoidTDZ option [3b2fe3cd](https://github.com/gohugoio/hugo/commit/3b2fe3cd33b74166c3debec9826826f2b5a54fd9) [@bep](https://github.com/bep) [#7865](https://github.com/gohugoio/hugo/issues/7865) +* Make js.Build fully support modules [85e4dd73](https://github.com/gohugoio/hugo/commit/85e4dd7370eae97ae367e596aa6a10ba42fd4b7c) [@bep](https://github.com/bep) [#7816](https://github.com/gohugoio/hugo/issues/7816)[#7777](https://github.com/gohugoio/hugo/issues/7777)[#7916](https://github.com/gohugoio/hugo/issues/7916) +* Generate tsconfig files [3089fc0b](https://github.com/gohugoio/hugo/commit/3089fc0ba171be14670b19439bc2eab6b077b6c3) [@richtera](https://github.com/richtera) [#7777](https://github.com/gohugoio/hugo/issues/7777) + + + + + + diff --cc docs/content/en/news/0.78.1-relnotes/index.md index b67e5de6c,000000000..168c1bbcd mode 100644,000000..100644 --- a/docs/content/en/news/0.78.1-relnotes/index.md +++ b/docs/content/en/news/0.78.1-relnotes/index.md @@@ -1,22 -1,0 +1,20 @@@ + +--- +date: 2020-11-05 +title: "Hugo 0.78.1: A couple of Bug Fixes" +description: "This version fixes a couple of bugs introduced in 0.78.0." +categories: ["Releases"] +images: +- images/blog/hugo-bug-poster.png + +--- + - - - This is a bug-fix release with a couple of important fixes. ++The main fix in this release is that of dependency resolution for package.json/node_modules in theme components. See [the documentation](https://gohugo.io/hugo-pipes/js/#include-dependencies-in-packagejson--node_modules) for more information. + +* Disable NPM test on Travis on Windows [3437174c](https://github.com/gohugoio/hugo/commit/3437174c3a7b96925b82b351ac87530b4fa796a5) [@bep](https://github.com/bep) +* travis: Install nodejs on Windows [f66302ca](https://github.com/gohugoio/hugo/commit/f66302ca0579171ffd1730eb8f33dd05af3d9a00) [@bep](https://github.com/bep) +* js: Remove external source map option [944150ba](https://github.com/gohugoio/hugo/commit/944150bafbbb5c3e807ba3688174e70764dbdc64) [@bep](https://github.com/bep) [#7932](https://github.com/gohugoio/hugo/issues/7932) +* js: Misc fixes [bf2837a3](https://github.com/gohugoio/hugo/commit/bf2837a314eaf70135791984a423b0b09f58741d) [@bep](https://github.com/bep) [#7924](https://github.com/gohugoio/hugo/issues/7924)[#7923](https://github.com/gohugoio/hugo/issues/7923) + + + diff --cc docs/content/en/templates/404.md index 18fabc655,000000000..0916e2299 mode 100644,000000..100644 --- a/docs/content/en/templates/404.md +++ b/docs/content/en/templates/404.md @@@ -1,64 -1,0 +1,64 @@@ +--- +title: Custom 404 Page +linktitle: 404 Page +description: If you know how to create a single page template, you have unlimited options for creating a custom 404. +date: 2017-02-01 +publishdate: 2017-02-01 +lastmod: 2017-03-31 +categories: [templates] +keywords: [404, page not found] +menu: + docs: + parent: "templates" + weight: 120 +weight: 120 #rem +draft: false +aliases: [] +toc: false +--- + +When using Hugo with [GitHub Pages](https://pages.github.com/), you can provide your own template for a [custom 404 error page](https://help.github.com/articles/custom-404-pages/) by creating a 404.html template file in your `/layouts` folder. When Hugo generates your site, the `404.html` file will be placed in the root. + +404 pages will have all the regular [page variables][pagevars] available to use in the templates. + +In addition to the standard page variables, the 404 page has access to all site content accessible from `.Pages`. + +``` +▾ layouts/ + 404.html +``` + +## 404.html + +This is a basic example of a 404.html template: + +{{< code file="layouts/404.html" download="404.html" >}} +{{ define "main"}} +
+
+

Go Home

+
+
+{{ end }} +{{< /code >}} + +## Automatic Loading + +Your 404.html file can be set to load automatically when a visitor enters a mistaken URL path, dependent upon the web serving environment you are using. For example: + - * [GitHub Pages](/hosting-and-deployment/hosting-on-github/). The 404 page is automatic. ++* [GitHub Pages](/hosting-and-deployment/hosting-on-github/) and [GitLab Pages](/hosting-and-deployment/hosting-on-gitlab/). The 404 page is automatic. +* Apache. You can specify `ErrorDocument 404 /404.html` in an `.htaccess` file in the root of your site. +* Nginx. You might specify `error_page 404 /404.html;` in your `nginx.conf` file. +* Amazon AWS S3. When setting a bucket up for static web serving, you can specify the error file from within the S3 GUI. +* Amazon CloudFont. You can specify the page in the Error Pages section in the CloudFont Console. [Details here](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/custom-error-pages.html) +* Caddy Server. Using `errors { 404 /404.html }`. [Details here](https://caddyserver.com/docs/errors) +* Netlify. Add `/* /404.html 404` to `content/_redirects`. [Details Here](https://www.netlify.com/docs/redirects/#custom-404) +* Azure Static website. You can specify the `Error document path` in the Static website configuration page of the Azure portal. [More details are available in the Static website documentation](https://docs.microsoft.com/en-us/azure/storage/blobs/storage-blob-static-website). + +{{% note %}} +`hugo server` will not automatically load your custom `404.html` file, but you +can test the appearance of your custom "not found" page by navigating your +browser to `/404.html`. +{{% /note %}} + +[pagevars]: /variables/page/ diff --cc docs/content/en/tools/starter-kits.md index 60b16cccb,000000000..e4255f98e mode 100644,000000..100644 --- a/docs/content/en/tools/starter-kits.md +++ b/docs/content/en/tools/starter-kits.md @@@ -1,43 -1,0 +1,45 @@@ +--- +title: Starter Kits +linktitle: Starter Kits +description: A list of community-developed projects designed to help you get up and running with Hugo. +date: 2017-02-22 +publishdate: 2017-02-01 +lastmod: 2018-08-11 +keywords: [starters,assets,pipeline] +menu: + docs: + parent: "tools" + weight: 30 +weight: 30 +sections_weight: 30 +draft: false +aliases: [/developer-tools/migrations/,/developer-tools/migrated/] +toc: false +--- + +Know of a Hugo-related starter kit that isn't mentioned here? [Please add it to the list.][addkit] + +{{% note "Starter Kits are Not Maintained by the Hugo Team"%}} +The following starter kits are developed by active members of the Hugo community. If you find yourself having issues with any of the projects, it's best to file an issue directly with the project's maintainer(s). +{{% /note %}} + +* [Hugo Wrapper][hugow]. Hugo Wrapper is a POSIX-style shell script which acts as a wrapper to download and run Hugo binary for your platform. It can be executed in variety of [Operating Systems][hugow-test] and [Command Shells][hugow-test]. +* [Victor Hugo][]. Victor Hugo is a Hugo boilerplate for creating truly epic websites using Webpack as an asset pipeline. Victor Hugo uses post-css and Babel for CSS and JavaScript, respectively, and is actively maintained. +* [GOHUGO AMP][]. GoHugo AMP is a starter theme that aims to make it easy to adopt [Google's AMP Project][amp]. The starter kit comes with 40+ shortcodes and partials plus automatic structured data. The project also includes a [separate site with extensive documentation][gohugodocs]. +* [Blaupause][]. Blaupause is a developer-friendly Hugo starter kit based on Gulp tasks. It comes ES6-ready with several helpers for SVG and fonts and basic structure for HTML, SCSS, and JavaScript. +* [hugulp][]. hugulp is a tool to optimize the assets of a Hugo website. The main idea is to recreate the famous Ruby on Rails Asset Pipeline, which minifies, concatenates and fingerprints the assets used in your website. +* [Atlas][]. Atlas is a Hugo boilerplate designed to speed up development with support for Netlify, Hugo Pipes, SCSS & more. It's actively maintained and contributions are always welcome. ++* [Hyas][]. Hyas is a Hugo starter helping you build modern websites that are secure, fast, and SEO-ready — by default. It is Netlify-ready (functions, redirects, headers) and comes with [documentation](https://gethyas.com/) to easily make it your own. + + +[addkit]: https://github.com/gohugoio/hugo/edit/master/docs/content/en/tools/starter-kits.md +[amp]: https://amp.dev +[Blaupause]: https://github.com/fspoettel/blaupause +[GOHUGO AMP]: https://github.com/wildhaber/gohugo-amp +[gohugodocs]: https://gohugo-amp.gohugohq.com/ +[hugow]: https://github.com/khos2ow/hugo-wrapper +[hugow-test]: https://github.com/khos2ow/hugo-wrapper#tested-on +[hugulp]: https://github.com/jbrodriguez/hugulp +[Victor Hugo]: https://github.com/netlify/victor-hugo +[Atlas]: https://github.com/indigotree/atlas ++[Hyas]: https://github.com/h-enk/hyas diff --cc docs/netlify.toml index d0dc9ded3,000000000..913d7965b mode 100644,000000..100644 --- a/docs/netlify.toml +++ b/docs/netlify.toml @@@ -1,31 -1,0 +1,31 @@@ +[build] +publish = "public" +command = "hugo --gc --minify" + +[context.production.environment] - HUGO_VERSION = "0.77.0" ++HUGO_VERSION = "0.78.2" +HUGO_ENV = "production" +HUGO_ENABLEGITINFO = "true" + +[context.split1] +command = "hugo --gc --minify --enableGitInfo" + +[context.split1.environment] - HUGO_VERSION = "0.77.0" ++HUGO_VERSION = "0.78.2" +HUGO_ENV = "production" + +[context.deploy-preview] +command = "hugo --gc --minify --buildFuture -b $DEPLOY_PRIME_URL" + +[context.deploy-preview.environment] - HUGO_VERSION = "0.77.0" ++HUGO_VERSION = "0.78.2" + +[context.branch-deploy] +command = "hugo --gc --minify -b $DEPLOY_PRIME_URL" + +[context.branch-deploy.environment] - HUGO_VERSION = "0.77.0" ++HUGO_VERSION = "0.78.2" + +[context.next.environment] +HUGO_ENABLEGITINFO = "true" + diff --cc docs/resources/_gen/images/news/0.78.0-relnotes/featured_hu16cc5f543b4302736ecbd476dcae86cf_47074_480x0_resize_catmullrom_2.png index 000000000,000000000..86f7f01de new file mode 100644 Binary files differ diff --cc docs/resources/_gen/images/news/0.78.0-relnotes/featured_hu16cc5f543b4302736ecbd476dcae86cf_47074_640x0_resize_catmullrom_2.png index 000000000,000000000..b666dbafc new file mode 100644 Binary files differ diff --cc docs/static/images/site-hierarchy.svg index 7d1a043e8,000000000..3c744871b mode 100644,000000..100644 --- a/docs/static/images/site-hierarchy.svg +++ b/docs/static/images/site-hierarchy.svg @@@ -1,634 -1,0 +1,1 @@@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - ++