From 90ad8045056167004d27857a95542936657b8a16 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bj=C3=B8rn=20Erik=20Pedersen?= Date: Tue, 13 Sep 2022 20:34:24 +0200 Subject: [PATCH] Squashed 'docs/' changes from e5aa641a6..392668f4f MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 392668f4f Update theme 65d82c845 fix versions in GitHub Pages docs (#1815) 4e078a306 Create hosting-on-azure-static-web-apps.md (#1738) e24e25052 fix requirement typo (#1814) 0790eb173 fix broken link (#1813) f4a1b38c7 πŸ“„ Add more clarity on merging of config files (#1493) 2e82efff0 Install on Windows: Correct + augment (#1520) 4bffd076e Update frontends to add CloudCannon's CMS (#1509) 17eea3133 Update index.md to add resource (#1508) 5a5ac1d2f Add documentation for babel sourceMap (#1492) 899b7117c Update menu-templates.md 284dc4266 Include flexible translation in i18n.md f03421274 docs: Escaping Hugo/GO template code 4f0755683 Improve the documentation of imageConfig and the image resource 89aa723cc Clarify leaf bundle explanation and related FAQ 0c6b32bb9 Update starter-kits.md a68151b1b Update starter-kits.md 91b145384 Update starter-kits.md c8104b422 Update hosting-on-21yunbox.md 51ee7603b Update hosting-on-21yunbox.md d88314499 docs(en): add hosting on 21YunBox aab04f269 Update shortcode-templates.md to correct an error. ed48563aa Misc improvements 87dd24e1d Fix merge failure 0bcc6dca8 js.Build: Update docs to not allow boolean inputs for sourceMap e50a28fbc js.Build: Add SourceMap flag into js.Build opts which can turn on sourcemap 9695093a1 Fix Arch Linux installation command 3de773d7a Please remove hugo-elasticsearch plugin. 6510f0a5a release: Add some more ignore expressions to release notes config dc90b7517 typoe > typo (!) 3427c7436 Add hugoreleaser config 5a1f2d0dd Improves formatting of resources, assets sections (#1804) 03ba56fdd Remove Flesland Flis from Showcases 9f61dac7a Update slice.md 533e4e0cd Update theme 85e50325c Simplify writing 9b30e81b9 Typo fix and remove passive form 8974b6c53 dynamic-menu-configuration 1c5467329 netlify: Hugo 0.102.3 610a937b0 Remove Over from Showcase 99f5585bc netlify: Hugo v0.102.2 9f230ac1f netlify: Hugo v0.102.1 a6fc3f864 netlify: Bump to Hugo v0.102.0 3e9bc1a62 Merge branch 'tempv0.102.0' c08d6d898 Update en/templates/404.md with Firebase Hosting (#1796) 322b75f40 Update configuration.md 2fa6f0b94 404 template example: remove slash relURL arg 1195f168a Remove broken link (#1767) e0838e574 Update RenderString.md bee6adf71 Update page-resources.md 24e142f22 Remove duplicate word from cascade description 879fc3983 docs: Update the description of PostCSS config 2ffe539e3 fix: Use `=` instead of `:=` for variable reassignments (#1771) 7496b8f87 update 404 error for digitalocean docs c85caca4a Merge commit 'bdf935d66c1f02dfc942a30e9fc00519bba3aacb' c3888b63a docs: Regen docshelper 8a5942555 Merge commit '475f87f685439de0f907a9ffc29bfd1361eb1c59' 282007217 common: Add hugo.GoVersion 00b4b46da resources/page: Add :slugorfilename attribute git-subtree-dir: docs git-subtree-split: 392668f4f488d184b08b227028b01dbc02abd57a --- .gitignore | 1 + .../gohugoio/gohugoioTheme/data/sponsors.toml | 27 ++++--- .../layouts/_default/baseof.html | 8 --- .../static/images/sponsors/bep-consulting.svg | 3 + .../static/images/sponsors/your-company.svg | 4 ++ _vendor/modules.txt | 2 +- content/en/content-management/comments.md | 3 +- .../image-processing/index.md | 6 +- content/en/content-management/multilingual.md | 49 +++++++++++-- content/en/content-management/page-bundles.md | 19 ++--- .../en/content-management/page-resources.md | 2 +- .../content-management/syntax-highlighting.md | 14 ++++ content/en/functions/RenderString.md | 2 - content/en/functions/i18n.md | 23 +++++- content/en/functions/images/index.md | 2 + content/en/functions/slice.md | 4 +- content/en/functions/union.md | 4 +- content/en/getting-started/configuration.md | 30 ++++++-- .../en/getting-started/directory-structure.md | 9 +-- .../external-learning-resources/index.md | 6 ++ content/en/getting-started/installing.md | 66 ++++++++++++------ .../hosting-on-21yunbox.md | 65 +++++++++++++++++ .../hosting-on-azure-static-web-apps.md | 23 ++++++ .../hosting-on-github.md | 10 +-- content/en/hugo-pipes/babel.md | 4 ++ content/en/hugo-pipes/js.md | 6 +- content/en/hugo-pipes/postcss.md | 4 +- content/en/showcase/flesland-flis/bio.md | 8 --- .../en/showcase/flesland-flis/featured.png | Bin 309284 -> 0 bytes content/en/showcase/flesland-flis/index.md | 24 ------- content/en/showcase/over/bio.md | 5 -- content/en/showcase/over/featured-over.png | Bin 194841 -> 0 bytes content/en/showcase/over/index.md | 17 ----- content/en/templates/404.md | 6 +- content/en/templates/menu-templates.md | 8 ++- content/en/templates/shortcode-templates.md | 2 +- content/en/tools/frontends.md | 1 + content/en/tools/search.md | 2 +- content/en/tools/starter-kits.md | 3 +- .../en/troubleshooting/build-performance.md | 5 -- content/en/troubleshooting/faq.md | 2 + go.mod | 2 +- go.sum | 4 ++ hugoreleaser.toml | 29 ++++++++ netlify.toml | 8 +-- 45 files changed, 366 insertions(+), 156 deletions(-) create mode 100644 _vendor/github.com/gohugoio/gohugoioTheme/static/images/sponsors/bep-consulting.svg create mode 100644 _vendor/github.com/gohugoio/gohugoioTheme/static/images/sponsors/your-company.svg create mode 100644 content/en/hosting-and-deployment/hosting-on-21yunbox.md create mode 100644 content/en/hosting-and-deployment/hosting-on-azure-static-web-apps.md delete mode 100644 content/en/showcase/flesland-flis/bio.md delete mode 100644 content/en/showcase/flesland-flis/featured.png delete mode 100644 content/en/showcase/flesland-flis/index.md delete mode 100644 content/en/showcase/over/bio.md delete mode 100644 content/en/showcase/over/featured-over.png delete mode 100644 content/en/showcase/over/index.md create mode 100644 hugoreleaser.toml diff --git a/.gitignore b/.gitignore index 4164d21f8..f9cab2f80 100644 --- a/.gitignore +++ b/.gitignore @@ -1,6 +1,7 @@ /.idea /.vscode /public +/dist node_modules nohup.out .DS_Store diff --git a/_vendor/github.com/gohugoio/gohugoioTheme/data/sponsors.toml b/_vendor/github.com/gohugoio/gohugoioTheme/data/sponsors.toml index 0940da6d7..0d276b374 100644 --- a/_vendor/github.com/gohugoio/gohugoioTheme/data/sponsors.toml +++ b/_vendor/github.com/gohugoio/gohugoioTheme/data/sponsors.toml @@ -1,19 +1,18 @@ [[banners]] -name = "Linode" -link = "https://www.linode.com/" -logo = "/images/sponsors/linode-logo_standard_light_medium.png" -copy = "" + name = "Linode" + link = "https://www.linode.com/" + logo = "/images/sponsors/linode-logo_standard_light_medium.png" + copy = "" [[banners]] -name = "eSolia" -link = "https://esolia.com/post/why-did-esolia-choose-hugo/" -logo = "/images/sponsors/esolia-logo.svg" -copy = "" - + name = "eSolia" + link = "https://esolia.com/post/why-did-esolia-choose-hugo/" + logo = "/images/sponsors/esolia-logo.svg" + copy = "" [[banners]] -name = "Brave" -link = "https://brave.com/" -logo = "/images/sponsors/brave-logo.svg" -bgcolor = "#5A2FA1" -copy = "" \ No newline at end of file + name = "BEP Consulting" + link = "https://bep.consulting" + logo = "/images/sponsors/bep-consulting.svg" + bgcolor = "#004887" + copy = "" diff --git a/_vendor/github.com/gohugoio/gohugoioTheme/layouts/_default/baseof.html b/_vendor/github.com/gohugoio/gohugoioTheme/layouts/_default/baseof.html index 527547428..04261a886 100644 --- a/_vendor/github.com/gohugoio/gohugoioTheme/layouts/_default/baseof.html +++ b/_vendor/github.com/gohugoio/gohugoioTheme/layouts/_default/baseof.html @@ -70,14 +70,6 @@ {{ partial "hooks/before-body-end" . }} - {{ if .Page.Store.Get "hasMermaid" }} - - -{{ end }} - - diff --git a/_vendor/github.com/gohugoio/gohugoioTheme/static/images/sponsors/bep-consulting.svg b/_vendor/github.com/gohugoio/gohugoioTheme/static/images/sponsors/bep-consulting.svg new file mode 100644 index 000000000..5b1170f9b --- /dev/null +++ b/_vendor/github.com/gohugoio/gohugoioTheme/static/images/sponsors/bep-consulting.svg @@ -0,0 +1,3 @@ + + + diff --git a/_vendor/github.com/gohugoio/gohugoioTheme/static/images/sponsors/your-company.svg b/_vendor/github.com/gohugoio/gohugoioTheme/static/images/sponsors/your-company.svg new file mode 100644 index 000000000..6f3082b54 --- /dev/null +++ b/_vendor/github.com/gohugoio/gohugoioTheme/static/images/sponsors/your-company.svg @@ -0,0 +1,4 @@ + + + + diff --git a/_vendor/modules.txt b/_vendor/modules.txt index b755ed7f6..2147e7a1c 100644 --- a/_vendor/modules.txt +++ b/_vendor/modules.txt @@ -1 +1 @@ -# github.com/gohugoio/gohugoioTheme v0.0.0-20220228085601-7cfbda06d135 +# github.com/gohugoio/gohugoioTheme v0.0.0-20220912070954-88dcaf003b4d diff --git a/content/en/content-management/comments.md b/content/en/content-management/comments.md index ad3a1b55d..5c604fdeb 100644 --- a/content/en/content-management/comments.md +++ b/content/en/content-management/comments.md @@ -4,7 +4,6 @@ linktitle: Comments description: Hugo ships with an internal Disqus template, but this isn't the only commenting system that will work with your new Hugo website. date: 2017-02-01 publishdate: 2017-02-01 -lastmod: 2017-03-09 keywords: [sections,content,organization] categories: [project organization, fundamentals] menu: @@ -60,7 +59,7 @@ These are some alternatives to Disqus: * [Muut](https://muut.com/) * [Remark42](https://remark42.com/) (Open source, Golang, Easy to run docker) * [Staticman](https://staticman.net/) -* [Talkyard](https://www.talkyard.io/blog-comments) (Open source, & serverless hosting) +* [Talkyard](https://blog-comments.talkyard.io/) (Open source, & serverless hosting) * [Utterances](https://utteranc.es/) (Open source, GitHub comments widget built on GitHub issues) [configuration]: /getting-started/configuration/ diff --git a/content/en/content-management/image-processing/index.md b/content/en/content-management/image-processing/index.md index 710c260ca..f2748f5db 100644 --- a/content/en/content-management/image-processing/index.md +++ b/content/en/content-management/image-processing/index.md @@ -28,7 +28,11 @@ content/ └── sunset.jpg <-- page resource ``` -To access an image as a page resource: +## The Image Resource + +The `image` resource gives you access to image-specific attributes like the picture's `Width` and `Height`, as well as powerful processing methods and filters. More on that below. + +Note that the `image` resource can also be retrieved from a [global resource]({{< relref "/hugo-pipes/introduction#from-file-to-resource" >}}) ```go-html-template {{ $image := .Resources.GetMatch "sunset.jpg" }} diff --git a/content/en/content-management/multilingual.md b/content/en/content-management/multilingual.md index d1e7965b2..e2450bb29 100644 --- a/content/en/content-management/multilingual.md +++ b/content/en/content-management/multilingual.md @@ -4,7 +4,6 @@ linktitle: Multilingual 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: @@ -335,13 +334,13 @@ 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. +In other 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. ```go-html-template {{ 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: +The function will read `.Count` from `.ReadingTime` and evaluate whether the number is singular (`one`) or plural (`other`). After that, it will pass to `readingTime` id in `i18n/en-US.toml` file: {{< code-toggle file="i18n/en-US" >}} [readingTime] @@ -349,7 +348,7 @@ one = "One minute to read" other = "{{.Count}} minutes to read" {{< /code-toggle >}} -Assume `.ReadingTime.Count` in the context has value of 525600. The result will be: +Assuming `.ReadingTime.Count` in the context has value is 525600. The result will be: ```text 525600 minutes to read @@ -361,7 +360,7 @@ If `.ReadingTime.Count` in the context has value is 1. The result is: One minute to read ``` -In case you need to pass custom data: (`(dict "Count" 25)` is minimum requirement) +In case you need to pass a custom data: (`(dict "Count" numeric_value_only)` is minimum requirement) ```go-html-template {{ i18n "readingTime" (dict "Count" 25 "FirstArgument" true "SecondArgument" false "Etc" "so on, so far") }} @@ -507,6 +506,40 @@ The rendering of the main navigation works as usual. `.Site.Menus` will just con ``` +### Dynamically localizing menus with i18n +While customizing menus per language is useful, your config file can become hard to maintain if you have a lot of languages + +If your menus are the same in all languages (ie. if the only thing that changes is the translated name) you can use the `.Identifier` as a translation key for the menu name: + +{{< code-toggle file="config" >}} +[[menu.main]] +name = "About me" +url = "about" +weight = 1 +identifier = "about" +{{< /code-toggle >}} + +You now need to specify the translations for the menu keys in the i18n files: + +{{< code file="i18n/pt.toml" >}} +[about] +other="Sobre mim" +{{< /code >}} + +And do the appropriate changes in the menu code to use the `i18n` tag with the `.Identifier` as a key. You will also note that here we are using a `default` to fall back to `.Name`, in case the `.Identifier` key is also not present in the language specified in the `defaultContentLanguage` configuration. + +{{< code file="layouts/partials/menu.html" >}} + +{{< /code >}} + + ## 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. @@ -535,6 +568,12 @@ To support Multilingual mode in your themes, some considerations must be taken f 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). + +## Generate multilingual content with `hugo new` +Currently, `hugo new` is not ready to support generating multilingual content. But there is a [proposal topic](https://github.com/gohugoio/hugo/issues/7732) about this in Github issue to discuss how it should work. + + + [abslangurl]: /functions/abslangurl [config]: /getting-started/configuration/ [contenttemplate]: /templates/single-page-templates/ diff --git a/content/en/content-management/page-bundles.md b/content/en/content-management/page-bundles.md index 9561ea2e9..924efccd2 100644 --- a/content/en/content-management/page-bundles.md +++ b/content/en/content-management/page-bundles.md @@ -64,26 +64,27 @@ content/ In the above example `content/` directory, there are four leaf bundles: -about +`about` : This leaf bundle is at the root level (directly under `content` directory) and has only the `index.md`. -my-post +`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` +- image1, image2: +These images are page resources 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. +- content1, content2: +These content files are page resources of `my-post` + and only available in `my-post/index.md` resources. + They will **not** be rendered as individual pages. -my-other-post +`my-other-post` : This leaf bundle has only the `index.md`. -another-leaf-bundle +`another-leaf-bundle` : This leaf bundle is nested under couple of directories. This bundle also has only the `index.md`. diff --git a/content/en/content-management/page-resources.md b/content/en/content-management/page-resources.md index 9f2c0cfab..24b1d03ed 100644 --- a/content/en/content-management/page-resources.md +++ b/content/en/content-management/page-resources.md @@ -131,7 +131,7 @@ name : Sets the value returned in `Name`. {{% warning %}} -The methods `Match` and `GetMatch` use `Name` to match the resources. +The methods `Match`, `Get` and `GetMatch` use `Name` to match the resources. {{%/ warning %}} title diff --git a/content/en/content-management/syntax-highlighting.md b/content/en/content-management/syntax-highlighting.md index 8ff270c54..5195b8211 100644 --- a/content/en/content-management/syntax-highlighting.md +++ b/content/en/content-management/syntax-highlighting.md @@ -80,6 +80,20 @@ func GetTitleFunc(style string) func(s string) string { } {{< / highlight >}} +## Highlight Hugo/GO Template Code + +For highlighting Hugo/GO template code on your page, add `/*` after the opening double curly braces and `*/` before closing curly braces. + +``` go +{{}} +``` + +Gives this: + +``` go +{{}} +``` + ## Highlight Template Func See [Highlight](/functions/highlight/). diff --git a/content/en/functions/RenderString.md b/content/en/functions/RenderString.md index 1b77f6a38..e414b11ca 100644 --- a/content/en/functions/RenderString.md +++ b/content/en/functions/RenderString.md @@ -14,8 +14,6 @@ signature: [".RenderString MARKUP"] `.RenderString` is a method on `Page` that renders some markup to HTML using the content renderer defined for that page (if not set in the options). -*Note* that this method does not parse and render shortcodes. - The method takes an optional map argument with these options: display ("inline") diff --git a/content/en/functions/i18n.md b/content/en/functions/i18n.md index 7d88292b9..34a6ff022 100644 --- a/content/en/functions/i18n.md +++ b/content/en/functions/i18n.md @@ -18,7 +18,7 @@ deprecated: false aliases: [] --- -This translates a piece of content based on your `i18n/en-US.yaml` (and similar) files. You can use the [go-i18n](https://github.com/nicksnyder/go-i18n) tools to manage your translations. The translations can exist in both the theme and at the root of your repository. +This translates a piece of content based on your `i18n/en-US.toml` files. You can use the [go-i18n](https://github.com/nicksnyder/go-i18n) tools to manage your translations. The translations can exist in both the theme and at the root of your repository. ``` {{ i18n "translation_id" }} @@ -28,6 +28,27 @@ This translates a piece of content based on your `i18n/en-US.yaml` (and similar) `T` is an alias to `i18n`. E.g. `{{ T "translation_id" }}`. {{% /note %}} +### Query a flexible translation with variables + +Often you will want to use the page variables in the translation strings. To do so, pass the `.` context when calling `i18n`: + +``` +{{ i18n "wordCount" . }} +``` + +The function will pass the `.` context to the `"wordCount"` id: + +{{< code-toggle file="i18n/en-US" >}} +[wordCount] +other = "This article has {{ .WordCount }} words." +{{< /code-toggle >}} + +Assume `.WordCount` in the context has value is 101. The result will be: + +``` +This article has 101 words. +``` + For more information about string translations, see [Translation of Strings in Multilingual Mode][multistrings]. [multistrings]: /content-management/multilingual/#translation-of-strings diff --git a/content/en/functions/images/index.md b/content/en/functions/images/index.md index 92c6ff0da..7dd5843ee 100644 --- a/content/en/functions/images/index.md +++ b/content/en/functions/images/index.md @@ -218,6 +218,8 @@ Also see the [Filter Method](/content-management/image-processing/#filter). Parses the image and returns the height, width, and color model. +The `imageConfig` function takes a single parameter, a file path (_string_) relative to the _project's root directory_, with or without a leading slash. + {{% funcsig %}} images.ImageConfig PATH {{% /funcsig %}} diff --git a/content/en/functions/slice.md b/content/en/functions/slice.md index 0710d5e40..24b717128 100644 --- a/content/en/functions/slice.md +++ b/content/en/functions/slice.md @@ -23,7 +23,9 @@ toc: false One use case is the concatenation of elements in combination with the [`delimit` function][]: {{< code file="slice.html" >}} -{{ delimit (slice "foo" "bar" "buzz") ", " }} +{{ $sliceOfStrings := slice "foo" "bar" "buzz" }} + +{{ delimit ($sliceOfStrings) ", " }} {{< /code >}} diff --git a/content/en/functions/union.md b/content/en/functions/union.md index 459e3620d..465abcdd8 100644 --- a/content/en/functions/union.md +++ b/content/en/functions/union.md @@ -40,8 +40,8 @@ This is also very useful to use as `OR` filters when combined with where: ``` {{ $pages := where .Site.RegularPages "Type" "not in" (slice "page" "about") }} -{{ $pages := $pages | union (where .Site.RegularPages "Params.pinned" true) }} -{{ $pages := $pages | intersect (where .Site.RegularPages "Params.images" "!=" nil) }} +{{ $pages = $pages | union (where .Site.RegularPages "Params.pinned" true) }} +{{ $pages = $pages | intersect (where .Site.RegularPages "Params.images" "!=" nil) }} ``` The above fetches regular pages not of `page` or `about` type unless they are pinned. And finally, we exclude all pages with no `images` set in Page params. diff --git a/content/en/getting-started/configuration.md b/content/en/getting-started/configuration.md index 9393e4534..91279712a 100644 --- a/content/en/getting-started/configuration.md +++ b/content/en/getting-started/configuration.md @@ -4,7 +4,6 @@ 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: @@ -18,7 +17,6 @@ aliases: [/overview/source-directory/,/overview/configuration/] toc: true --- - ## Configuration File Hugo uses the `config.toml`, `config.yaml`, or `config.json` (if found in the @@ -77,6 +75,27 @@ foo = "bar" ``` 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. + +Let's take an example to understand this better. Let's say you are using Google Analytics for your website. This requires you to specify `googleAnalytics = "G-XXXXXXXX"` in `config.toml`. Now consider the following scenario: +- You don't want the Analytics code to be loaded in development i.e. in your `localhost` +- You want to use separate googleAnalytics IDs for your production & staging environments (say): + - `G-PPPPPPPP` for production + - `G-SSSSSSSS` for staging + +This is how you need to configure your `config.toml` files considering the above scenario: +1. In `_default/config.toml` you don't need to mention `googleAnalytics` parameter at all. This ensures that no Google Analytics code is loaded in your development server i.e. when you run `hugo serve`. This works since, by default Hugo sets `Environment=development` when you run `hugo serve` which uses the config files from `_default` folder +2. In `production/config.toml` you just need to have one line: + + ```googleAnalytics = "G-PPPPPPPP"``` + + You don't need to mention all other parameters like `title`, `baseURL`, `theme` etc. again in this config file. You need to mention only those parameters which are different or new for the production environment. This is due to the fact that Hugo is going to __merge__ this on top of `_default/config.toml`. Now when you run `hugo` (build command), by default hugo sets `Environment=production`, so the `G-PPPPPPPP` analytics code will be there in your production website +3. Similarly in `staging/config.toml` you just need to have one line: + + ```googleAnalytics = "G-SSSSSSSS"``` + + Now you need to tell Hugo that you are using the staging environment. So your build command should be `hugo --environment staging` which will load the `G-SSSSSSSS` analytics code in your staging website + + {{% note %}} Default environments are __development__ with `hugo server` and __production__ with `hugo`. {{%/ note %}} @@ -149,7 +168,7 @@ See [Configure File Caches](#configure-file-caches) {{< new-in "0.86.0" >}} -Pass down down default configuration values (front matter) to pages in the content tree. The options in site config is the same as in page front matter, see [Front Matter Cascade](/content-management/front-matter#front-matter-cascade). +Pass down default configuration values (front matter) to pages in the content tree. The options in site config is the same as in page front matter, see [Front Matter Cascade](/content-management/front-matter#front-matter-cascade). ### canonifyURLs @@ -271,7 +290,10 @@ See [Image Processing Config](/content-management/image-processing/#imaging-conf **Default value:** "" -A language tag as defined by [RFC 5646](https://datatracker.ietf.org/doc/html/rfc5646). The internal [RSS template](https://github.com/gohugoio/hugo/blob/master/tpl/tplimpl/embedded/templates/_default/rss.xml) populates its `` element with this value. The value is not used elsewhere. +A language tag as defined by [RFC 5646](https://datatracker.ietf.org/doc/html/rfc5646). This value is used to populate: + +- The `` element in the internal [RSS template](https://github.com/gohugoio/hugo/blob/master/tpl/tplimpl/embedded/templates/_default/rss.xml) +- The `lang` attribute of the `` element in the internal [alias template](https://github.com/gohugoio/hugo/blob/master/tpl/tplimpl/embedded/templates/alias.html) ### languages diff --git a/content/en/getting-started/directory-structure.md b/content/en/getting-started/directory-structure.md index 3fa66d4c5..c523219c2 100644 --- a/content/en/getting-started/directory-structure.md +++ b/content/en/getting-started/directory-structure.md @@ -31,6 +31,7 @@ Running the `hugo new site` generator from the command line will create a direct β”œβ”€β”€ content β”œβ”€β”€ data β”œβ”€β”€ layouts +β”œβ”€β”€ public β”œβ”€β”€ static └── themes ``` @@ -45,7 +46,7 @@ The following is a high-level overview of each of the directories with links to By default, Hugo will create new content files with at least `date`, `title` (inferred from the file name), and `draft = true`. This saves time and promotes consistency for sites using multiple content types. You can create your own [archetypes][] with custom preconfigured front matter fields as well. [`assets`][] -: Stores all the files which need be processed by [Hugo Pipes]({{< ref "/hugo-pipes" >}}). Only the files whose `.Permalink` or `.RelPermalink` are used will be published to the `public` directory. Note: assets directory is not created by default. +: Stores all the files which need be processed by [Hugo Pipes](/hugo-pipes/). Only the files whose `.Permalink` or `.RelPermalink` are used will be published to the `public` directory. Note: assets directory is not created by default. [`config`](/getting-started/configuration/) : Hugo ships with a large number of [configuration directives][]. @@ -71,11 +72,11 @@ used by Hugo when generating your website. You can write these files in YAML, JS From **Hugo 0.31** you can have multiple static directories. {{% /note %}} -resources +[`resources`][] : Caches some files to speed up generation. Can be also used by template authors to distribute built SASS files, so you don't have to have the preprocessor installed. Note: resources directory is not created by default. - [archetypes]: /content-management/archetypes/ +[`assets`]: /hugo-pipes/introduction#asset-directory/ [configuration directives]: /getting-started/configuration/#all-configuration-settings [`content`]: /content-management/organization/ [content section]: /content-management/sections/ @@ -84,6 +85,7 @@ resources [homepage]: /templates/homepage/ [`layouts`]: /templates/ [`static`]: /content-management/static-files/ +[`resources`]: /getting-started/configuration/#configure-file-caches [lists]: /templates/list/ [pagevars]: /variables/page/ [partials]: /templates/partials/ @@ -93,4 +95,3 @@ resources [taxonomies]: /content-management/taxonomies/ [taxonomy templates]: /templates/taxonomy-templates/ [types]: /content-management/types/ -[`assets`]: {{< ref "/hugo-pipes/introduction#asset-directory" >}} diff --git a/content/en/getting-started/external-learning-resources/index.md b/content/en/getting-started/external-learning-resources/index.md index 349d7e29d..feb7cbb50 100644 --- a/content/en/getting-started/external-learning-resources/index.md +++ b/content/en/getting-started/external-learning-resources/index.md @@ -30,6 +30,12 @@ Hugo in Action is a step-by-step guide to using Hugo to create static websites. [Build Websites with Hugo - Fast Web Development with Markdown (2020)](https://pragprog.com/titles/bhhugo/) by Brian P. Hogan. +## Beginner tutorials + +### Hugo tutorial by CloudCannon + +[Step-by-step written tutorial](https://cloudcannon.com/community/learn/hugo-101/) to teach you the basics of creating a Hugo site. + ## Video tutorials ### Video Playlist by Mike Dane diff --git a/content/en/getting-started/installing.md b/content/en/getting-started/installing.md index 32e9df18e..3fd8d0a57 100644 --- a/content/en/getting-started/installing.md +++ b/content/en/getting-started/installing.md @@ -109,6 +109,7 @@ scoop install hugo-extended #### Prerequisite Tools * [Git][installgit] +* [GCC][] (For Windows users only) * [Go (at least Go 1.11)](https://golang.org/dl/) #### Fetch from GitHub @@ -126,7 +127,14 @@ go install --tags extended Remove `--tags extended` if you do not want/need Sass/SCSS support. {{% note %}} -If you are a Windows user, substitute the `$HOME` environment variable above with `%USERPROFILE%`. + +##### For installation on Windows + +* Substitute the `$HOME` environment variable above with `%USERPROFILE%`. +* If you install `--tags extended` version, you may encounter this error `"gcc": executable file not found in %PATH%` + * Please make sure you have installed `gcc` command and add it to `%PATH%`. + * "MinGW" is recommended, it has been tested and built successfully + {{% /note %}} ## macOS @@ -289,21 +297,21 @@ If `hugo` is not in your `PATH`: If your default shell is zsh: - ``` - nano ~/.zprofile - ``` - - If your default shell is bash: - - ``` - nano ~/.bash_profile - ``` + ``` + nano ~/.zprofile + ``` + + If your default shell is bash: + + ``` + nano ~/.bash_profile + ``` 3. Insert a line to add `$HOME/bin` to your existing `PATH`. - ``` - export PATH=$PATH:$HOME/bin - ``` + ``` + export PATH=$PATH:$HOME/bin + ``` 4. Save the file by pressing Control-X, then Y. @@ -358,7 +366,7 @@ The following aims to be a complete guide to installing Hugo on your Windows PC. {{< youtube G7umPCU-8xc >}} -### Assumptions +### Assumptions for Windows 1. You will use `C:\Hugo\Sites` as the starting point for your new project. 2. You will use `C:\Hugo\bin` to store executable files. @@ -376,7 +384,12 @@ You'll need a place to store the Hugo executable, your [content][], and the gene 1. Download the latest zipped Hugo executable from [Hugo Releases][releases]. 2. Extract all contents to your `..\Hugo\bin` folder. -3. In PowerShell or your preferred CLI, add the `hugo.exe` executable to your PATH by navigating to `C:\Hugo\bin` (or the location of your hugo.exe file) and use the command `set PATH=%PATH%;C:\Hugo\bin`. If the `hugo` command does not work after a reboot, you may have to run the command prompt as administrator. +3. Open Windows Command Line (cmd, "DOS") to add the `hugo.exe` executable to your PATH + * do `set PATH=%PATH%;C:\Hugo\bin` to have hugo in PATH for the currently opened cmd box + * do `setx PATH "%PATH%;C:\Hugo\bin"` to have hugo in PATH for every newly opened cmd box + * note: "setx", not "set", plus syntax 'key "val"', not 'key=val' + +> You may also use "Git CMD" from the [Git for Windows package](https://gitforwindows.org/) for the native Windows commands [set](https://ss64.com/nt/set.html) and [setx](https://ss64.com/nt/setx.html), but not "Git Bash", PowerShell, or any other "CLI" with different commands ### Less-technical Users @@ -468,11 +481,15 @@ Directory of C:\hugo\sites\example.com In any of the [Linux distributions that support snaps][snaps], you may install the "extended" Sass/SCSS version with this command: - snap install hugo --channel=extended +``` +snap install hugo --channel=extended +``` To install the non-extended version without Sass/SCSS support: - snap install hugo +``` +snap install hugo +``` To switch between the two, use either `snap refresh hugo --channel=extended` or `snap refresh hugo --channel=stable`. @@ -484,7 +501,9 @@ Hugo installed via Snap can write only inside the user’s `$HOME` directory---a [@anthonyfok](https://github.com/anthonyfok) and friends in the [Debian Go Packaging Team](https://go-team.pages.debian.net/) maintains an official hugo [Debian package](https://packages.debian.org/hugo) which is shared with [Ubuntu](https://packages.ubuntu.com/hugo) and is installable via `apt-get`: - sudo apt-get install hugo +``` +sudo apt-get install hugo +``` What this installs depends on your Debian/Ubuntu version. On Ubuntu bionic (18.04), this installs the non-extended version without Sass/SCSS support. On Ubuntu disco (19.04), this installs the extended version with Sass/SCSS support. @@ -495,14 +514,16 @@ This option is not recommended because the Hugo in Linux package managers for De You can also install Hugo from the Arch Linux [community](https://www.archlinux.org/packages/community/x86_64/hugo/) repository. Applies also to derivatives such as Manjaro. ``` -sudo pacman -Syu hugo +sudo pacman -S hugo ``` ### Fedora, Red Hat and CentOS Fedora maintains an [official package for Hugo](https://packages.fedoraproject.org/pkgs/hugo/hugo) which may be installed with: - sudo dnf install hugo +``` +sudo dnf install hugo +``` For the latest version, the Hugo package maintained by [@daftaupe](https://github.com/daftaupe) at Fedora Copr is recommended: @@ -530,7 +551,9 @@ sudo eopkg install hugo OpenBSD provides a package for Hugo via `pkg_add`: - doas pkg_add hugo +``` +doas pkg_add hugo +``` ## Upgrade Hugo @@ -551,6 +574,7 @@ Now that you've installed Hugo, read the [Quick Start guide][quickstart] and exp [dep]: https://github.com/golang/dep [highlight shortcode]: /content-management/shortcodes/#highlight [installgit]: https://git-scm.com/ +[GCC]: http://www.mingw.org/ [installgo]: https://golang.org/dl/ [linuxbrew]: https://docs.brew.sh/Homebrew-on-Linux [quickstart]: /getting-started/quick-start/ diff --git a/content/en/hosting-and-deployment/hosting-on-21yunbox.md b/content/en/hosting-and-deployment/hosting-on-21yunbox.md new file mode 100644 index 000000000..b0ea7a7cf --- /dev/null +++ b/content/en/hosting-and-deployment/hosting-on-21yunbox.md @@ -0,0 +1,65 @@ +--- +title: Host on 21YunBox +linktitle: Host on 21YunBox +description: Host your Hugo site with 21YunBox's blazing fast Chinese CDN, fully-managed SSL and auto deploys from Gitee. +date: 2021-01-06 +publishdate: 2021-01-06 +lastmod: 2021-01-06 +categories: [hosting and deployment] +keywords: [21yunbox,hosting,deployment] +authors: [Toby Glei] +menu: + docs: + parent: "hosting-and-deployment" + weight: 10 +weight: 10 +sections_weight: 10 +draft: false +aliases: [] +toc: true +--- + +[21YunBox](https://www.21yunbox.com) is a fully-managed cloud platform dedicated to make web deployment easy within the Chinese Great Firewall where you can host static sites, backend APIs, databases, cron jobs, and all your other apps in one place. It provides blazing fast Chinese CDN, continuous deployment, one-click HTTPS and [other services like managed databases and backend web services](https://www.21yunbox.com/docs/), providing an avenue to launch web projects in China. + +21YunBox includes the following features: + +- Continuous, automatic builds & deploys from GitHub and Gitee +- Automatic SSL certificates through [Let's Encrypt](https://letsencrypt.org) +- Instant cache invalidation with a blazing fast, Chinese CDN +- Unlimited [custom domains](https://www.21yunbox.com/docs/#/custom-domains) +- Automatic [Brotli compression](https://en.wikipedia.org/wiki/Brotli) for faster sites +- Native HTTP/2 support +- Automatic HTTP β†’ HTTPS redirects +- Custom URL redirects and rewrites + +## Prerequisites + +This guide assumes you already have a Hugo project to deploy. If you need a project, use the [Quick Start](/getting-started/quick-start/) to get started or fork 21YunBox's [Hugo Example](https://gitee.com/eryiyunbox-examples/hello-hugo) before continuing. + +## Setup + +You can set up a Hugo site on 21YunBox in two quick steps: + +1. Create a new web service on 21YunBox, and give 21YunBox permission to access your GitHub or Gitee 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 21YunBox URL (which looks like `yoursite.21yunbox.com`) as soon as the build is done. + +## Continuous deploys + +Now that 21YunBox is connected to your repo, it will automatically build and publish your site any time you push to GitHub. + +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 21YunBox's [custom domains](https://www.21yunbox.com/docs/#/custom-domains) guide. + +## Support +Click [here](https://www.21yunbox.com/docs/#/contact) to contact with 21YunBox' experts if you need help. diff --git a/content/en/hosting-and-deployment/hosting-on-azure-static-web-apps.md b/content/en/hosting-and-deployment/hosting-on-azure-static-web-apps.md new file mode 100644 index 000000000..9d9daa578 --- /dev/null +++ b/content/en/hosting-and-deployment/hosting-on-azure-static-web-apps.md @@ -0,0 +1,23 @@ +--- +title: Hosting on Azure Static Web Apps +linktitle: Hosting on Azure Static Web Apps +description: Learn how to deploy a Hugo application to Azure Static Web Apps. +date: 2022-05-09 +publishdate: 2022-05-09 +categories: [hosting and deployment] +keywords: [hosting,Azure Static Web Apps] +authors: [Azure Static Web Apps] +menu: + docs: + parent: "hosting-and-deployment" + weight: 200 +weight: 200 +sections_weight: 200 +draft: false +toc: true +aliases: [] +--- + +You can create and deploy a Hugo web application to Azure Static Web Apps. The final result is a new Azure Static Web App with associated GitHub Actions that give you control over how the app is built and published. You'll learn how to create a Hugo app, setup an Azure Static Web App and deploy the Hugo app to Azure. + +Here's the tutorial on how to [Publish a Hugo site to Azure Static Web Apps](https://docs.microsoft.com/en-us/azure/static-web-apps/publish-hugo). diff --git a/content/en/hosting-and-deployment/hosting-on-github.md b/content/en/hosting-and-deployment/hosting-on-github.md index ae30ce44a..22acca568 100644 --- a/content/en/hosting-and-deployment/hosting-on-github.md +++ b/content/en/hosting-and-deployment/hosting-on-github.md @@ -47,7 +47,7 @@ As mentioned in the [GitHub Pages documentation][ghorgs], you can host a user/or ## Build Hugo With GitHub Action -GitHub executes your software development workflows. Everytime you push your code on the Github repository, Github Actions will build the site automatically. +GitHub executes your software development workflows. Everytime you push your code on the GitHub repository, Github Actions will build the site automatically. Create a file in `.github/workflows/gh-pages.yml` containing the following content (based on [actions-hugo](https://github.com/marketplace/actions/hugo-setup)): @@ -62,9 +62,9 @@ on: jobs: deploy: - runs-on: ubuntu-20.04 + runs-on: ubuntu-22.04 steps: - - uses: actions/checkout@v2 + - uses: actions/checkout@v3 with: submodules: true # Fetch Hugo themes (true OR recursive) fetch-depth: 0 # Fetch all history for .GitInfo and .Lastmod @@ -88,10 +88,12 @@ jobs: For more advanced settings [actions-hugo](https://github.com/marketplace/actions/hugo-setup) and [actions-gh-pages](https://github.com/marketplace/actions/github-pages-action). -## Github pages setting +## GitHub pages setting + By default, the GitHub action pushes the generated content to the `gh-pages` branch. This means GitHub has to serve your `gh-pages` branch as a GitHub Pages branch. You can change this setting by going to Settings > GitHub Pages, and change the source branch to `gh-pages`. ## Change baseURL in config.toml + Don't forget to rename your `baseURL` in `config.toml` with the value `https://.github.io` for your user repository or `https://.github.io/` for a project repository. Unless this is present in your `config.toml`, your website won't work. diff --git a/content/en/hugo-pipes/babel.md b/content/en/hugo-pipes/babel.md index 76a1d441d..7cf931f65 100755 --- a/content/en/hugo-pipes/babel.md +++ b/content/en/hugo-pipes/babel.md @@ -65,6 +65,10 @@ compact [bool] verbose [bool] : Log everything +sourceMap [string] +: Output `inline` or `external` sourcemap from the babel compile. External sourcemaps will be written to the target with the output file name + ".map". Input sourcemaps can be read from js.Build and node modules and combined into the output sourcemaps. + + ### Examples ```go-html-template diff --git a/content/en/hugo-pipes/js.md b/content/en/hugo-pipes/js.md index 63bd8bdd9..ff29ca958 100644 --- a/content/en/hugo-pipes/js.md +++ b/content/en/hugo-pipes/js.md @@ -70,6 +70,10 @@ With the above, these imports should work in both scenarios: import * as React from 'react' import * as ReactDOM from 'react-dom'; ``` +sourceMap [string, bool] {{< new-in "0.75.0" >}} +: Let `js.Build` output sourceMap. Current only inline is supported. true defaults to inline. + One of: '`inline`, `external` + Default is "" (disabled) target [string] : The language target. @@ -93,7 +97,7 @@ format [string] {{< new-in "0.74.3" >}} Default is `iife`, a self-executing function, suitable for inclusion as a