diff options
30 files changed, 243 insertions, 567 deletions
diff --git a/docs/README.md b/docs/README.md index 072714a02..730ad5fc8 100644 --- a/docs/README.md +++ b/docs/README.md @@ -19,6 +19,15 @@ Spelling fixes are most welcomed, and if you want to contribute longer sections * For example, try to find short snippets that teaches people about the concept. If the example is also useful as-is (copy and paste), then great. Don't list long and similar examples just so people can use them on their sites. * Hugo has users from all over the world, so easy to understand and [simple English](https://simple.wikipedia.org/wiki/Basic_English) is good. + +## Edit the theme + +If you want to do docs-related theme changes, the simplest way is to have both `hugoDocs` and `gohugoioTheme` cloned as sibling directories, and then run: + +``` +HUGO_MODULE_WORKSPACE=hugo.work hugo server --ignoreVendorPaths "**" +``` + ## Branches * The `master` branch is where the site is automatically built from, and is the place to put changes relevant to the current Hugo version. diff --git a/docs/_vendor/github.com/gohugoio/gohugoioTheme/data/sponsors.toml b/docs/_vendor/github.com/gohugoio/gohugoioTheme/data/sponsors.toml index 1e46fc07c..adf26ecdb 100644 --- a/docs/_vendor/github.com/gohugoio/gohugoioTheme/data/sponsors.toml +++ b/docs/_vendor/github.com/gohugoio/gohugoioTheme/data/sponsors.toml @@ -5,18 +5,19 @@ utm_campaign = "hugosponsor" [[banners]] - name = "eSolia" - link = "https://esolia.com/post/why-did-esolia-choose-hugo/" - logo = "/images/sponsors/esolia-logo.svg" - utm_campaign = "hugosponsor" - -[[banners]] name = "ButterCMS" link = "https://buttercms.com/hugo-cms/" logo = "/images/sponsors/butter-light.svg" utm_campaign = "sponsorship" bgcolor = "#131A3E" +[[banners]] + name = "Your Company?" + link = "https://bep.is/en/hugo-sponsor-2023-01/" + logo = "/images/sponsors/your-company.svg" + utm_campaign = "hugosponsor" + bgcolor = "#004887" + #hugohome #hugofooter #hugogithub diff --git a/docs/_vendor/github.com/gohugoio/gohugoioTheme/layouts/_default/baseof.html b/docs/_vendor/github.com/gohugoio/gohugoioTheme/layouts/_default/baseof.html index 04261a886..5767f078b 100644 --- a/docs/_vendor/github.com/gohugoio/gohugoioTheme/layouts/_default/baseof.html +++ b/docs/_vendor/github.com/gohugoio/gohugoioTheme/layouts/_default/baseof.html @@ -1,75 +1,119 @@ <!DOCTYPE html> -<html class="no-js" lang="{{ with $.Site.LanguageCode }}{{ . }}{{ else }}en-us{{ end }}"> +<html + class="no-js" + lang="{{ with $.Site.LanguageCode }} + {{ . }} + {{ else }} + en-us + {{ end }} + "> + <head> + <meta charset="utf-8" /> + {{/* https://www.zachleat.com/web/preload/ */}} + <link + rel="preload" + href="{{ "fonts/muli-latin-200.woff2" | absURL }}" + as="font" + type="font/woff2" + crossorigin /> + <link + rel="preload" + href="{{ "fonts/muli-latin-400.woff2" | absURL }}" + as="font" + type="font/woff2" + crossorigin /> + <link + rel="preload" + href="{{ "fonts/muli-latin-800.woff2" | absURL }}" + as="font" + type="font/woff2" + crossorigin /> -<head> - <meta charset="utf-8"> - {{/* https://www.zachleat.com/web/preload/ */}} - <link rel="preload" href="{{ "fonts/muli-latin-200.woff2" | absURL }}" as="font" type="font/woff2" crossorigin> - <link rel="preload" href="{{ "fonts/muli-latin-400.woff2" | absURL }}" as="font" type="font/woff2" crossorigin> - <link rel="preload" href="{{ "fonts/muli-latin-800.woff2" | absURL }}" as="font" type="font/woff2" crossorigin> + <meta http-equiv="X-UA-Compatible" content="IE=edge" /> + {{/* NOTE: the Site's title, and if there is a page title, that is set too */}} + <title> + {{ block "title" . }} + {{ with .Title }}{{ . }} | {{ end }}{{ .Site.Title }} + {{ end }} - <meta http-equiv="X-UA-Compatible" content="IE=edge"> - {{/* NOTE: the Site's title, and if there is a page title, that is set too */}} - <title>{{ block "title" . }}{{ with .Title }}{{ . }} | {{ end }}{{ .Site.Title }}{{ end }}</title> + </title> - <meta name="viewport" content="width=device-width,minimum-scale=1"> - {{ hugo.Generator }} + <meta name="viewport" content="width=device-width,minimum-scale=1" /> + {{ hugo.Generator }} - {{ if eq (getenv "HUGO_ENV") "production" | or (eq .Site.Params.env "production") }} - <meta name="robots" content="index, follow"> - {{ else }} - <meta name="robots" content="noindex, nofollow"> - {{ end }} + {{ if hugo.IsProduction }} + <meta name="robots" content="index, follow" /> + {{ else }} + <meta name="robots" content="noindex, nofollow" /> + {{ end }} - {{ range .AlternativeOutputFormats -}} - <link rel="{{ .Rel }}" type="{{ .MediaType.Type }}" href="{{ .Permalink | safeURL }}"> - {{ end -}} + {{ range .AlternativeOutputFormats -}} + <link + rel="{{ .Rel }}" + type="{{ .MediaType.Type }}" + href="{{ .Permalink | safeURL }}" /> + {{ end -}} - {{ $isDev := eq hugo.Environment "development" }} - {{ $stylesheet := resources.Get "output/css/app.css" }} - {{ if not $isDev }} - {{ $stylesheet = $stylesheet | minify | fingerprint }} - {{ end }} - {{ with $stylesheet }} - {{ if $isDev }} - <link rel="stylesheet" href="{{ .RelPermalink }}" crossorigin="anonymous"> - {{ else }} - <link rel="stylesheet" href="{{ .RelPermalink }}" integrity="{{ .Data.Integrity }}" crossorigin="anonymous"> - {{ end }} - {{ $.Scratch.Set "stylesheet" . }} - {{end}} + {{ $isDev := eq hugo.Environment "development" }} + {{ $stylesheet := resources.Get "output/css/app.css" }} + {{ if not $isDev }} + {{ $stylesheet = $stylesheet | minify | fingerprint }} + {{ end }} + {{ with $stylesheet }} + {{ if $isDev }} + <link + rel="stylesheet" + href="{{ .RelPermalink }}" + crossorigin="anonymous" /> + {{ else }} + <link + rel="stylesheet" + href="{{ .RelPermalink }}" + integrity="{{ .Data.Integrity }}" + crossorigin="anonymous" /> + {{ end }} + {{ $.Scratch.Set "stylesheet" . }} + {{ end }} - <meta name="description" - content="{{ with .Description }}{{ . }}{{ else }}{{ with .Site.Params.description }}{{ . }}{{ end }}{{ end }}"> - {{ block "scripts" . }} - {{- partial "site-scripts.html" . -}} - {{ end }} - {{ partial "site-manifest.html" . }} - {{- partial "head-additions.html" . -}} - {{- partial "opengraph/opengraph.html" . -}} - {{- template "_internal/schema.html" . -}} - {{- partial "opengraph/twitter_cards.html" . -}} + <meta + name="description" + content="{{ with .Description }} + {{ . }} + {{ else }} + {{ with .Site.Params.description }}{{ . }}{{ end }} + {{ end }} + " /> - {{ if eq (getenv "HUGO_ENV") "production" | or (eq .Site.Params.env "production") }} - {{ partial "gtag" . }} - {{ end }} + {{ block "scripts" . }} + {{- partial "site-scripts.html" . -}} + {{ end }} + {{ partial "site-manifest.html" . }} + {{- partial "head-additions.html" . -}} + {{- partial "opengraph/opengraph.html" . -}} + {{- template "_internal/schema.html" . -}} + {{- partial "opengraph/twitter_cards.html" . -}} + + {{ if hugo.IsProduction }} + {{ partial "gtag" . }} + {{ end }} -</head> + </head> -<body class="ma0 sans-serif bg-primary-color-light{{ with getenv "HUGO_ENV" }} {{ . }}{{ end }}"> - {{ partial "hooks/after-body-start" . }} - {{ block "nav" . }}{{ partial "site-nav.html" . }}{{ end }} - {{ block "header" . }}{{ end }} - <main role="main" class="content-with-sidebar min-vh-100 pb7 pb0-ns"> - {{ block "main" . }}{{ end }} - </main> + <body + class="ma0 sans-serif bg-primary-color-light{{ with getenv "HUGO_ENV" }} + {{ . }} + {{ end }}"> + {{ partial "hooks/after-body-start" . }} + {{ block "nav" . }}{{ partial "site-nav.html" . }}{{ end }} + {{ block "header" . }}{{ end }} + <main role="main" class="content-with-sidebar min-vh-100 pb7 pb0-ns"> + {{ block "main" . }}{{ end }} + </main> - {{ block "footer" . }}{{ partialCached "site-footer.html" . }}{{ end }} - - {{ partial "hooks/before-body-end" . }} - + {{ block "footer" . }}{{ partialCached "site-footer.html" . }}{{ end }} -</body> + {{ partial "hooks/before-body-end" . }} + </body> </html> diff --git a/docs/_vendor/modules.txt b/docs/_vendor/modules.txt index 787da8ac2..21e85264c 100644 --- a/docs/_vendor/modules.txt +++ b/docs/_vendor/modules.txt @@ -1 +1 @@ -# github.com/gohugoio/gohugoioTheme v0.0.0-20221217122332-1c1752ad8f14 +# github.com/gohugoio/gohugoioTheme v0.0.0-20230109120406-12694c4a9456 diff --git a/docs/config/_default/config.toml b/docs/config/_default/config.toml index f4965dff1..731233310 100644 --- a/docs/config/_default/config.toml +++ b/docs/config/_default/config.toml @@ -1,7 +1,7 @@ baseURL = "https://gohugo.io/" defaultContentLanguage = "en" enableEmoji = true -googleAnalytics = "UA-7131036-4" +googleAnalytics = "G-MBZGKNMDWC" ignoreErrors = ["error-remote-getjson", "error-missing-instagram-accesstoken"] languageCode = "en-us" paginate = 100 diff --git a/docs/config/_default/languages.toml b/docs/config/_default/languages.toml index c9914d84d..cfddb5398 100644 --- a/docs/config/_default/languages.toml +++ b/docs/config/_default/languages.toml @@ -1,10 +1,4 @@ - - [en] - contentDir = "content/en" - languageName = "English" - weight = 1 - - [zh] - contentDir = "content/zh" - languageName = "中文" - weight = 2 +[en] +contentDir = "content/en" +languageName = "English" +weight = 1 diff --git a/docs/config/_default/menus/menus.zh.toml b/docs/config/_default/menus/menus.zh.toml deleted file mode 100644 index 2f68be67b..000000000 --- a/docs/config/_default/menus/menus.zh.toml +++ /dev/null @@ -1,121 +0,0 @@ - -# Chinese menus - -[[docs]] - name = "关于 Hugo" - weight = 1 - identifier = "about" - url = "/zh/about/" - -[[docs]] - name = "入门" - weight = 5 - identifier = "getting-started" - url = "/zh/getting-started/" - -[[docs]] - name = "主题" - weight = 15 - identifier = "themes" - post = "break" - url = "/zh/themes/" - -# Core languages.zh.menus - -[[docs]] - name = "内容管理" - weight = 20 - identifier = "content-management" - post = "expanded" - url = "/zh/content-management/" - -[[docs]] - name = "模板" - weight = 25 - identifier = "templates" - url = "/zh/templates/" - -[[docs]] - name = "函数" - weight = 30 - identifier = "functions" - url = "/zh/functions/" - -[[docs]] - name = "变量" - weight = 35 - identifier = "variables" - url = "/zh/variables/" - -[[docs]] - name = "CLI" - weight = 40 - post = "break" - identifier = "commands" - url = "/commands/" - -# LOW LEVEL ITEMS -[[docs]] - name = "故障排除" - weight = 60 - identifier = "troubleshooting" - url = "/zh/troubleshooting/" - -[[docs]] - name = "工具" - weight = 70 - identifier = "tools" - url = "/zh/tools/" - -[[docs]] - name = "托管与部署" - weight = 80 - identifier = "hosting-and-deployment" - url = "/zh/hosting-and-deployment/" - -[[docs]] - name = "贡献" - weight = 100 - post = "break" - identifier = "contribute" - url = "/zh/contribute/" - -[[global]] - name = "新闻" - weight = 1 - identifier = "news" - url = "/zh/news/" - -[[global]] - name = "文档" - weight = 5 - identifier = "docs" - url = "/zh/documentation/" - -[[global]] - name = "主题" - weight = 10 - identifier = "themes" - url = "https://themes.gohugo.io/" - -[[global]] - name = "作品展示" - weight = 20 - identifier = "showcase" - url = "/zh/showcase/" - -# Anything with a weight > 100 gets an external icon -[[global]] - name = "社区" - weight = 150 - icon = true - identifier = "community" - post = "external" - url = "https://discourse.gohugo.io/" - -[[global]] - name = "GitHub" - weight = 200 - identifier = "github" - post = "external" - url = "https://github.com/gohugoio/hugo" diff --git a/docs/content/en/functions/images/index.md b/docs/content/en/functions/images/index.md index 0cf45b6ee..e7fc50f7e 100644 --- a/docs/content/en/functions/images/index.md +++ b/docs/content/en/functions/images/index.md @@ -60,7 +60,7 @@ You can load a custom font if needed. Load the font as a Hugo `Resource` and set ```go-html-template -{{ $font := resources.Get "https://github.com/google/fonts/raw/main/apache/roboto/static/Roboto-Black.ttf" }} +{{ $font := resources.GetRemote "https://github.com/google/fonts/raw/main/apache/roboto/static/Roboto-Black.ttf" }} {{ $img := resources.Get "/images/background.png"}} {{ $img = $img.Filter (images.Text "Hugo rocks!" (dict "font" $font diff --git a/docs/content/en/functions/param.md b/docs/content/en/functions/param.md index 5387647d2..4f1764814 100644 --- a/docs/content/en/functions/param.md +++ b/docs/content/en/functions/param.md @@ -1,40 +1,47 @@ --- title: .Param -description: Calls page or site variables into your template. -date: 2017-02-01 -publishdate: 2017-02-01 -lastmod: 2017-04-30 -keywords: ["front matter"] +description: Returns a page parameter, falling back to a site parameter if present. +signature: ['.Param KEY'] categories: [functions] +keywords: ['front matter', 'params'] menu: docs: - parent: "functions" -toc: -signature: [".Param KEY"] -workson: [] -hugoversion: -relatedfuncs: [default] -deprecated: false -draft: false + parent: 'functions' aliases: [] --- -In Hugo, you can declare [site-wide params][sitevars] (i.e. in your [configuration]), as well as params for [individual pages][pagevars]. +The `.Param` method on `.Page` looks for the given `KEY` in page parameters, and returns the corresponding value. If it cannot find the `KEY` in page parameters, it looks for the `KEY` in site parameters. If it cannot find the `KEY` in either location, the `.Param` method returns `nil`. -A common use case is to have a general value for the site and a more specific value for some of the pages (e.g., an image). +Site and theme developers commonly set parameters at the site level, allowing content authors to override those parameters at the page level. -You can use the `.Param` method to call these values into your template. The following will first look for an `image` param in a specific content's [front matter]. If not found, Hugo will look for an `image` param in your site's configuration: +For example, to show a table of contents on every page, but allow authors to hide the table of contents as needed: -``` -$.Param "image" -``` +**Configuration** -{{% note %}} -The `Param` method may not consider empty strings in a content's front matter as "not found." If you are setting preconfigured front matter fields to empty strings using Hugo's archetypes, it may be best to use the [`default` function](/functions/default/) instead of `Param`. See the [related issue on GitHub](https://github.com/gohugoio/hugo/issues/3366). -{{% /note %}} +{{< code-toggle file="config" copy=false >}} +[params] +display_toc = true +{{< /code-toggle >}} +**Content** -[configuration]: /getting-started/configuration/ -[front matter]: /content-management/front-matter/ -[pagevars]: /variables/page/ -[sitevars]: /variables/site/ +{{< code-toggle file="content/about.md" fm=true copy=false >}} +title = 'About' +date = 2023-01-01 +draft = false +display_toc = false +{{< /code-toggle >}} + +**Template** + +{{< code file="layouts/_default/single.html" copy="false" >}} +{{ if .Param "display_toc" }} + {{ .TableOfContents }} +{{ end }} +{{< /code >}} + +The `.Param` method returns the value associated with the given `KEY`, regardless of whether the value is truthy or falsy. If you need to ignore falsy values, use this construct instead: + +{{< code file="layouts/_default/single.html" copy="false" >}} +{{ or .Params.foo site.Params.foo }} +{{< /code >}} diff --git a/docs/content/en/getting-started/configuration-markup.md b/docs/content/en/getting-started/configuration-markup.md index 4694bd439..b55bd79c4 100644 --- a/docs/content/en/getting-started/configuration-markup.md +++ b/docs/content/en/getting-started/configuration-markup.md @@ -32,6 +32,9 @@ For details on the extensions, refer to [this section](https://github.com/yuin/g Some settings explained: +hardWrap +: By default, Goldmark ignores newlines within a paragraph. Set to `true` to render newlines as `<br>` elements. + unsafe : By default, Goldmark does not render raw HTMLs and potentially dangerous links. If you have lots of inline HTML and/or JavaScript, you may need to turn this on. diff --git a/docs/content/en/getting-started/configuration.md b/docs/content/en/getting-started/configuration.md index 39f27453f..3c9b42678 100644 --- a/docs/content/en/getting-started/configuration.md +++ b/docs/content/en/getting-started/configuration.md @@ -173,6 +173,12 @@ Pass down default configuration values (front matter) to pages in the content tr Enable to turn relative URLs into absolute. +### cleanDestinationDir + +**Default value:** false + +When building, removes files from destination not found in static directories. + ### contentDir **Default value:** "content" @@ -231,7 +237,7 @@ Disable automatic live reloading of browser window. **Default value:** false -: Do not convert the url/path to lowercase. +Do not convert the url/path to lowercase. ### enableEmoji diff --git a/docs/content/en/getting-started/usage.md b/docs/content/en/getting-started/usage.md index edf3e82a5..15cf46cbf 100644 --- a/docs/content/en/getting-started/usage.md +++ b/docs/content/en/getting-started/usage.md @@ -120,7 +120,7 @@ hugo server --navigateToChanged As noted above, Hugo does not clear the public directory before building your site. Manually clear the contents of the public directory before each build to remove draft, expired, and future content. {{% /note %}} -When are ready to deploy your site, run: +When you are ready to deploy your site, run: ```bash hugo diff --git a/docs/content/en/hugo-modules/use-modules.md b/docs/content/en/hugo-modules/use-modules.md index 8870307b3..977a52bd6 100644 --- a/docs/content/en/hugo-modules/use-modules.md +++ b/docs/content/en/hugo-modules/use-modules.md @@ -135,3 +135,33 @@ 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](/getting-started/configuration/#configure-file-caches). Also see the [CLI Doc](/commands/hugo_mod_clean/). + +## Module Workspaces + +{{< new-in "0.109.0" >}} + +Workspace support was added in [Go 1.18](https://go.dev/blog/get-familiar-with-workspaces) and Hugo got solid support for it in the `v0.109.0` version. + +A common use case for a workspace is to simplify local development of a site with its theme modules. + +A workspace can be configured in a `*.work` file and activated with the [module.workspace](/hugo-modules/configuration/) setting, which for this use is commonly controlled via the `HUGO_MODULE_WORKSPACE` OS environment variable. + +See the [hugo.work](https://github.com/gohugoio/hugo/blob/master/hugo.work) file in the Hugo Docs repo for an example: + +``` +go 1.19 + +use . +use ../gohugoioTheme +``` + +Using the `use` directive, list all the modules you want to work on, pointing to its relative location. As in the example above, it's recommended to always include the main project (the ".") in the list. + +With that you can start the Hugo server with that workspace enabled: + +``` +HUGO_MODULE_WORKSPACE=hugo.work hugo server --ignoreVendorPaths "**" +``` + +The `--ignoreVendorPaths` flag is added above to ignore any of the vendored dependencies inside `_vendor`. If you don't use vendoring, you don't need that flag. But now the server is set up watching the files and directories in the workspace and you can see your local edits reloaded. + diff --git a/docs/content/en/hugo-pipes/introduction.md b/docs/content/en/hugo-pipes/introduction.md index 116523fd5..e83741f74 100755 --- a/docs/content/en/hugo-pipes/introduction.md +++ b/docs/content/en/hugo-pipes/introduction.md @@ -133,6 +133,18 @@ You can also change the request method and set the request body: Remote resources fetched with `resources.GetRemote` will be cached on disk. See [Configure File Caches](/getting-started/configuration/#configure-file-caches) for details. + +## Copy a Resource + +{{< new-in "0.100.0" >}} + +`resources.Copy` allows you to copy almost any Hugo `Resource` (the one exception is the `Page`), possibly most useful for renaming things: + +```go-html-template +{{ $resized := $image.Resize "400x400" | resources.Copy "images/mynewname.jpg" }} +<img src="{{ $resized.RelPermalink }}"> +``` + ## Asset directory Asset files must be stored in the asset directory. This is `/assets` by default, but can be configured via the configuration file's `assetDir` key. diff --git a/docs/content/en/hugo-pipes/scss-sass.md b/docs/content/en/hugo-pipes/scss-sass.md index 169c473d2..4e39207fa 100755 --- a/docs/content/en/hugo-pipes/scss-sass.md +++ b/docs/content/en/ |