--- /dev/null
+{
+ "version": "0.2",
+ "allowCompoundWords": true,
+ "files": [
+ "**/*.md"
+ ],
+ "flagWords": [
+ "alot",
+ "hte",
+ "langauge",
+ "reccommend",
+ "seperate",
+ "teh"
+ ],
+ "ignorePaths": [
+ "**/emojis.md",
+ "**/commands/*",
+ "**/showcase/*",
+ "**/tools/*"
+ ],
+ "ignoreRegExpList": [
+ "# cspell: ignore fenced code blocks",
+ "^(\\s*`{3,}).*[\\s\\S]*?^\\1",
+ "# cspell: ignore words joined with dot",
+ "\\w+\\.\\w+",
+ "# cspell: ignore strings within backticks",
+ "`.+`",
+ "# cspell: ignore strings within single quotes",
+ "'.+'",
+ "# cspell: ignore strings within double quotes",
+ "\".+\"",
+ "# cspell: ignore strings within brackets",
+ "\\[.+\\]",
+ "# cspell: ignore strings within parentheses",
+ "\\(.+\\)",
+ "# cspell: ignore words that begin with a slash",
+ "/\\w+",
+ "# cspell: ignore everything within action delimiters",
+ "\\{\\{.+\\}\\}",
+ "# cspell: ignore everything after a right arrow",
+ "\\s+→\\s+.+"
+ ],
+ "language": "en",
+ "words": [
+ "antialiasing",
+ "codeowners",
+ "composability",
+ "configurators",
+ "defang",
+ "deindent",
+ "downscale",
+ "downscaled",
+ "downscaling",
+ "exif",
+ "geolocalized",
+ "grayscale",
+ "marshal",
+ "marshaling",
+ "multihost",
+ "performantly",
+ "preconfigured",
+ "prerendering",
+ "redirection",
+ "redirections",
+ "shortcode",
+ "shortcodes",
+ "subexpression",
+ "subexpressions",
+ "suppressable",
+ "templating",
+ "transpile",
+ "transpiles",
+ "unmarshal",
+ "unmarshals",
+ "unmarshaling",
+ "# ----------------------------------------------------------------------",
+ "# cspell: ignore foreign language words",
+ "# ----------------------------------------------------------------------",
+ "bezpieczeństwo",
+ "dokumentation",
+ "libros",
+ "miesiąc",
+ "miesiąc",
+ "miesięcy",
+ "miesięcy",
+ "misérables",
+ "projekt",
+ "régime",
+ "# ----------------------------------------------------------------------",
+ "# cspell: ignore proper nouns",
+ "# ----------------------------------------------------------------------",
+ "Eliott",
+ "Gregor",
+ "Jaco",
+ "Noll",
+ "Pastorius",
+ "Samsa",
+ "# ----------------------------------------------------------------------",
+ "# cspell: ignore operating systems and software packages",
+ "# ----------------------------------------------------------------------",
+ "asciidoctor",
+ "brotli",
+ "corejs",
+ "disqus",
+ "doas",
+ "eopkg",
+ "gitee",
++ "gohugoio",
+ "goldmark",
+ "KaTeX",
+ "kubuntu",
+ "lubuntu",
+ "MathJax",
+ "nosql",
+ "pandoc",
+ "pkgin",
+ "rclone",
+ "xubuntu",
+ "# ----------------------------------------------------------------------",
+ "# cspell: ignore miscellaneous",
+ "# ----------------------------------------------------------------------",
+ "dring",
+ "getenv",
+ "gohugo",
+ "inor",
+ "jdoe",
+ "milli",
+ "rgba",
+ "rsmith",
+ "stringifier",
+ "struct",
+ "tdewolff",
+ "tjones",
+ "toclevels",
+ "vals",
+ "xfeff",
+ "zgotmplz"
+ ]
+}
--- /dev/null
- uses: github/codeql-action/init@v2
+name: "CodeQL"
+
+on:
+ schedule:
+ - cron: "0 0 1 * *"
+
+jobs:
+ analyze:
+ name: Analyze
+ runs-on: ubuntu-latest
+ permissions:
+ actions: read
+ contents: read
+ security-events: write
+
+ steps:
+ - name: Checkout repository
+ uses: actions/checkout@v4
+
+ - name: Initialize CodeQL
- uses: github/codeql-action/analyze@v2
++ uses: github/codeql-action/init@v3
+ with:
+ languages: "javascript"
+
+ - name: Perform CodeQL Analysis
++ uses: github/codeql-action/analyze@v3
--- /dev/null
- uses: super-linter/super-linter/slim@v5
+name: Super Linter
+
+on:
+ workflow_dispatch:
+
+permissions:
+ contents: read # to fetch code (actions/checkout)
+
+jobs:
+ build:
+ permissions:
+ contents: read # to fetch code (actions/checkout)
+ statuses: write # to mark status of each linter run (github/super-linter/slim)
+
+ name: Lint Code Base
+ runs-on: ubuntu-latest
+ if: ${{ github.actor != 'dependabot[bot]' }}
+
+ steps:
+ - name: Checkout Code
+ uses: actions/checkout@v4
+
+ - name: Lint Code Base
++ uses: super-linter/super-linter/slim@v6
+ env:
+ DEFAULT_BRANCH: master
+ GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+ IGNORE_GITIGNORED_FILES: true
+ LINTER_RULES_PATH: /
+ LOG_LEVEL: NOTICE
+ MARKDOWN_CONFIG_FILE: .markdownlint.yaml
+ SUPPRESS_POSSUM: true
+ VALIDATE_CSS: false
+ VALIDATE_EDITORCONFIG: false
+ VALIDATE_GITLEAKS: false
+ VALIDATE_HTML: false
+ VALIDATE_JAVASCRIPT_STANDARD: false
+ VALIDATE_JSCPD: false
+ VALIDATE_NATURAL_LANGUAGE: false
+ VALIDATE_SHELL_SHFMT: false
+ VALIDATE_XML: false
--- /dev/null
- [](https://app.netlify.com/sites/gohugoio/deploys)
- [](https://gohugo.io/contribute/documentation/)
-
- # Hugo Docs
-
- Documentation site for [Hugo](https://github.com/gohugoio/hugo), the very fast and flexible static site generator built with love in Go.
-
- ## Contributing
-
- We welcome contributions to Hugo of any kind including documentation, suggestions, bug reports, pull requests etc. Also check out our [contribution guide](https://gohugo.io/contribute/documentation/). We would love to hear from you.
-
- Note that this repository contains solely the documentation for Hugo. For contributions that aren't documentation-related please refer to the [hugo](https://github.com/gohugoio/hugo) repository.
-
- *Pull requests shall **only** contain changes to the actual documentation. However, changes on the codebase of Hugo **and** the documentation shall be a single, atomic pull request in the [hugo](https://github.com/gohugoio/hugo) repository.*
++<a href="https://gohugo.io/"><img src="https://raw.githubusercontent.com/gohugoio/gohugoioTheme/master/static/images/hugo-logo-wide.svg?sanitize=true" alt="Hugo" width="565"></a>
+
- Spelling fixes are most welcomed, and if you want to contribute longer sections to the documentation, it would be great if you had the following criteria in mind when writing:
++A fast and flexible static site generator built with love by [bep], [spf13], and [friends] in [Go].
+
- * Short is good. People go to the library to read novels. If there is more than one way to _do a thing_ in Hugo, describe the current _best practice_ (avoid "… but you can also do …" and "… in older versions of Hugo you had to …".
- * For 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:
-
- ```sh
- 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.
- * The `next` branch is where we store changes that are related to the next Hugo release. This can be previewed here: https://next--gohugoio.netlify.com/
-
- ## Build
-
- To view the documentation site locally, you need to clone this repository:
++[](https://app.netlify.com/sites/gohugoio/deploys)
++[](https://gohugo.io/contribute/documentation/)
+
- ```sh
- git clone https://github.com/gohugoio/hugoDocs.git
- ```
++This is the repository for the [Hugo](https://github.com/gohugoio/hugo) documentation site.
+
- Also note that the documentation version for a given version of Hugo can also be found in the `/docs` sub-folder of the [Hugo source repository](https://github.com/gohugoio/hugo).
++Please see the [contributing] section for guidelines, examples, and process.
+
- Then to view the docs in your browser, run Hugo and open up the link:
+
- ```sh
- ▶ hugo server
+
- Started building sites ...
- .
- .
- Serving pages from memory
- Web Server is available at http://localhost:1313/ (bind address 127.0.0.1)
- Press Ctrl+C to stop
- ```
++[bep]: https://github.com/bep
++[spf13]: https://github.com/spf13
++[friends]: https://github.com/gohugoio/hugo/graphs/contributors
++[go]: https://go.dev/
++[contributing]: https://gohugo.io/contribute/documentation
--- /dev/null
- <!DOCTYPE html>
++<!doctype html>
+<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 />
+
+ <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>
+
+ <meta name="viewport" content="width=device-width,minimum-scale=1" />
+ {{ hugo.Generator }}
+
+ {{ 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 -}}
+
+ {{ $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" . -}}
+
+ {{ if hugo.IsProduction }}
+ {{ partial "gtag.html" . }}
+ {{ end }}
+
- {{ if .Param "math" }}
++ {{ $hasMath := .Param "math" }}
++ {{ if $hasMath }}
+ {{ partialCached "math.html" . }}
+ {{ end }}
+
+ </head>
+
+ <body
+ class="ma0 sans-serif bg-primary-color-light{{ with getenv "HUGO_ENV" }}
+ {{ . }}
- {{ end }}">
++ {{ end }} {{ if $hasMath }}{{ print " dn" }}{{ end }}">
+ {{ partial "hooks/after-body-start.html" . }}
+ {{ 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.html" . }}
+
+ </body>
+</html>
--- /dev/null
- {{ $urlPre := "https://api.github.com" }}
- {{ $user_json := getJSON $urlPre "/users/" $author }}
+{{ $author := .context.Params.author }}
+{{ if $author }}
+ <aside class="mw5 center bg-white br3 pa3 pa4-ns mv3 ba b--black-10 nested-links">
- <div class="tc">
-
- {{ if $user_json.avatar_url }}
- <a href="{{ $user_json.html_url }}" class="link hover-bg-light-gray pa1 br-100">
- <img src="{{ $user_json.avatar_url }}&size={{ .size }}" alt="" class="br-100 ba b--light-gray">
- </a>
+
- {{ if $user_json.name }}
- <h3 class="f4">
- <a href="{{ $user_json.html_url }}" class="link dim">
- {{ $user_json.name }}
++ {{ $data := "" }}
++ {{ $url := urls.JoinPath "https://api.github.com/users" $author }}
++ {{ with resources.GetRemote $url }}
++ {{ with .Err }}
++ {{ errorf "%s" . }}
++ {{ else }}
++ {{ $data = . | transform.Unmarshal }}
+ {{ end }}
++ {{ else }}
++ {{ errorf "Unable to get remote resource %q" $url }}
++ {{ end }}
++
++ <div class="tc">
++ {{ with $data }}
+
- </h3>
- <hr class="mw3 bb bw1 b--black-10">
- {{ end }}
++ {{ with .avatar_url }}
++ <a href="{{ . }}" class="link hover-bg-light-gray pa1 br-100">
++ <img src="{{ . }}&size={{ $.size }}" alt="" class="br-100 ba b--light-gray">
+ </a>
- {{ if $user_json.bio }}
- <p class="lh-copy measure center f6 black-70">
- {{ $user_json.bio }}
- </p>
++ {{ end }}
++ {{ with .name }}
++ <h3 class="f4">
++ <a href="{{ $data.html_url }}" class="link dim">
++ {{ . | htmlEscape }}
++ </a>
++ </h3>
++ <hr class="mw3 bb bw1 b--black-10">
++ {{ end }}
++ {{ with .bio }}
++ <p class="lh-copy measure center f6 black-70">
++ {{ . | htmlEscape }}
++ </p>
++ {{ end }}
+
-
+ {{ end }}
+ </div>
+
+ </aside>
+{{ end }}
--- /dev/null
- {{ $urlPre := "https://api.github.com" }}
- {{ $user_json := getJSON $urlPre "/users/" $author }}
- {{ if $user_json.name }}
+{{ $author := .context.Params.author }}
+{{ if $author }}
+ <aside class="mw5 br3 mv3 nested-links">
- {{ $user_json.name | htmlEscape }}
++
++ {{ $data := "" }}
++ {{ $url := urls.JoinPath "https://api.github.com/users" $author }}
++ {{ with resources.GetRemote $url }}
++ {{ with .Err }}
++ {{ errorf "%s" . }}
++ {{ else }}
++ {{ $data = . | transform.Unmarshal }}
++ {{ end }}
++ {{ else }}
++ {{ errorf "Unable to get remote resource %q" $url }}
++ {{ end }}
++
++ {{ with $data }}
++ {{ with .name }}
+ <h3 class="f4 dib">
-
++ {{ . | htmlEscape }}
+ </h3>
- {{ if $user_json.bio }}
+ {{ end }}
- {{ $user_json.bio | htmlEscape }}
++ {{ with .bio }}
+ <p class="lh-copy measure center mt0 f6 black-60">
- <a href="{{ $user_json.html_url }}" class="link dim v-mid dib">
- {{ partial "svg/github-squared.svg" (dict "fill" "gray" "width" "16" "height" "18") }}
- </a>
++ {{ . | htmlEscape }}
+ </p>
+ {{ end }}
++ {{ with .html_url }}
++ <a href="{{ . }}" class="link dim v-mid dib">
++ {{ partial "svg/github-squared.svg" (dict "fill" "gray" "width" "16" "height" "18") }}
++ </a>
++ {{ end }}
++ {{ end }}
++
+ </aside>
+{{ end }}
--- /dev/null
- <a href="{{.Site.Params.ghrepo}}blob/master/content/{{.Lang }}/{{.File.Path}}">
+<table class="collapse ba br2 b--black-10 pv2 ph3">
+ <thead>
+ <tr>
+ <th class="pv2 ph3 tl f6 fw6 ttu">LastMod</th>
+ <th class="pv2 ph3 tl f6 fw6 ttu">Link</th>
+ <th class="pv2 ph3 tl f6 fw6 ttu">GitHub</th>
+ </tr>
+ </thead>
+ <tbody>
+ {{ range . }}
+ <tr class="striped--light-gray">
+ <td class="pv2 ph3">{{ .Lastmod.Format "2006-01-02" }}</td>
+ <td class="pv2 ph3">
+ <a href="{{ .Permalink }}">{{ .Title }}</a>
+ </td>
+ <td class="pv2 ph3">
- </table>
++ <a href="{{ .Site.Params.ghrepo }}blob/master/content/{{ .Language.Lang }}/{{ .File.Path }}">
+ {{ with .GitInfo }}{{ .Subject }}{{ else }}Source{{ end }}
+ </a>
+ </td>
+ </tr>
+ {{ end }}
+ </tbody>
++</table>
--- /dev/null
- displayMath: [['\\[', '\\]'], ['$$', '$$']], // block
- inlineMath: [['\\(', '\\)']] // inline
+<script id="MathJax-script" async src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-chtml.js"></script>
+<script>
+ MathJax = {
+ tex: {
++ inlineMath: [['$', '$'], ['\\(', '\\)']], // inline
++ displayMath: [['$$', '$$'], ['\\[', '\\]']] // block
++ },
++ startup: {
++ pageReady: () => {
++ return MathJax.startup.defaultPageReady().then(() => {
++ document.body.classList.remove("dn");
++ });
++ }
+ }
+ };
+</script>
--- /dev/null
- <a href="{{.Site.Params.ghrepo}}edit/master/content/{{ .Lang }}/{{.File.Path}}" class="
++<a href="{{.Site.Params.ghrepo }}edit/master/content/{{ .Language.Lang }}/{{ .File.Path }}" class="
+f6 ph3 pv1 br2 dib tc ttu mv3 bg-primary-color white hover-bg-green link
+">Improve this page</a>
--- /dev/null
- # github.com/gohugoio/gohugoioTheme v0.0.0-20240126181647-31e47d550511
++# github.com/gohugoio/gohugoioTheme v0.0.0-20240201183016-8e648a3b5342
--- /dev/null
- taxonomies
- : Field name of the *plural* form of the index. See `tags` and `categories` in the above front matter examples. *Note that the plural form of user-defined taxonomies cannot be the same as any of the predefined front matter variables.*
-
+---
+title: Front matter
+description: Hugo allows you to add front matter in yaml, toml, or json to your content files.
+categories: [content management]
+keywords: [front matter,yaml,toml,json,metadata,archetypes]
+menu:
+ docs:
+ parent: content-management
+ weight: 60
+weight: 60
+toc: true
+aliases: [/content/front-matter/]
+---
+
+**Front matter** allows you to keep metadata attached to an instance of a [content type]---i.e., embedded inside a content file---and is one of the many features that gives Hugo its strength.
+
+{{< youtube Yh2xKRJGff4 >}}
+
+## Front matter formats
+
+Hugo supports four formats for front matter, each with their own identifying tokens.
+
+TOML
+: identified by opening and closing `+++`.
+
+YAML
+: identified by opening and closing `---`.
+
+JSON
+: a single JSON object surrounded by '`{`' and '`}`', followed by a new line.
+
+ORG
+: a group of Org mode keywords in the format '`#+KEY: VALUE`'. Any line that does not start with `#+` ends the front matter section.
+ Array values can either be separated into multiple lines (`#+KEY: VALUE_1` and `#+KEY: VALUE_2`) or a whitespace separated list of strings (`#+KEY[]: VALUE_1 VALUE_2`).
+
+### Example
+
+{{< code-toggle >}}
+title = "spf13-vim 3.0 release and new website"
+description = "spf13-vim is a cross platform distribution of vim plugins and resources for Vim."
+tags = [ ".vimrc", "plugins", "spf13-vim", "vim" ]
+date = "2012-04-06"
+categories = [
+ "Development",
+ "VIM"
+]
+slug = "spf13-vim-3-0-release-and-new-website"
+{{< /code-toggle >}}
+
+## Front matter variables
+
+### Predefined
+
+There are a few predefined variables that Hugo is aware of. See [Page Variables][pagevars] for how to call many of these predefined variables in your templates.
+
+aliases
+: An array of one or more aliases (e.g., old published paths of renamed content) that will be created in the output directory structure . See [Aliases][aliases] for details.
+
+audio
+: An array of paths to audio files related to the page; used by the `opengraph` [internal template](/templates/internal) to populate `og:audio`.
+
+cascade
+: A map of front matter keys whose values are passed down to the page's descendants unless overwritten by self or a closer ancestor's cascade. See [Front Matter Cascade](#front-matter-cascade) for details.
+
+date
+: The datetime assigned to this page. This is usually fetched from the `date` field in front matter, but this behavior is configurable.
+
+description
+: The description for the content.
+
+draft
+: If `true`, the content will not be rendered unless the `--buildDrafts` flag is passed to the `hugo` command.
+
+expiryDate
+: The datetime at which the content should no longer be published by Hugo; expired content will not be rendered unless the `--buildExpired` flag is passed to the `hugo` command.
+
+headless
+: If `true`, sets a leaf bundle to be [headless][headless-bundle].
+
+images
+: An array of paths to images related to the page; used by [internal templates](/templates/internal) such as `_internal/twitter_cards.html`.
+
+isCJKLanguage
+: If `true`, Hugo will explicitly treat the content as a CJK language; both `.Summary` and `.WordCount` work properly in CJK languages.
+
+keywords
+: The meta keywords for the content.
+
+layout
+: The layout Hugo should select from the [lookup order][lookup] when rendering the content. If a `type` is not specified in the front matter, Hugo will look for the layout of the same name in the layout directory that corresponds with a content's section. See [Content Types][content type].
+
+lastmod
+: The datetime at which the content was last modified.
+
+linkTitle
+: Used for creating links to content; if set, Hugo defaults to using the `linkTitle` before the `title`.
+
+markup
+: **experimental**; specify `"rst"` for reStructuredText (requires`rst2html`) or `"md"` (default) for Markdown.
+
+outputs
+: Allows you to specify output formats specific to the content. See [output formats][outputs].
+
+publishDate
+: If in the future, content will not be rendered unless the `--buildFuture` flag is passed to `hugo`.
+
+resources
+: Used for configuring page bundle resources. See [Page Resources][page-resources].
+
+series
+: An array of series this page belongs to, as a subset of the `series` [taxonomy](/content-management/taxonomies/); used by the `opengraph` [internal template](/templates/internal) to populate `og:see_also`.
+
+slug
+: Overrides the last segment of the URL path. Not applicable to section pages. See [URL Management](/content-management/urls/#slug) for details.
+
+summary
+: Text used when providing a summary of the article in the `.Summary` page variable; details available in the [content-summaries](/content-management/summaries/) section.
+
+title
+: The title for the content.
+
+type
+: The type of the content; this value will be automatically derived from the directory (i.e., the [section]) if not specified in front matter.
+
+url
+: Overrides the entire URL path. Applicable to regular pages and section pages. See [URL Management](/content-management/urls/#url) for details.
+
+videos
+: An array of paths to videos related to the page; used by the `opengraph` [internal template](/templates/internal) to populate `og:video`.
+
+weight
+: used for [ordering your content in lists][ordering]. Lower weight gets higher precedence. So content with lower weight will come first. If set, weights should be non-zero, as 0 is interpreted as an *unset* weight.
+
- If you instea define a `[[cascade]]` in front matter for multiple languages, an `content/XX/foo/_index.md` file needs to be made on a per-language basis, with `XX` the glob pattern matching the Page's language. In this case, the **lang** keyword is ignored.
+{{% note %}}
+If neither `slug` nor `url` is present and [permalinks are not configured otherwise in your site configuration file](/content-management/urls/#permalinks), Hugo will use the file name of your content to create the output URL. See [Content Organization](/content-management/organization) for an explanation of paths in Hugo and [URL Management](/content-management/urls/) for ways to customize Hugo's default behaviors.
+{{% /note %}}
+
+### User-defined
+
+You can add fields to your front matter arbitrarily to meet your needs. These user-defined key-values are placed into a single `.Params` variable for use in your templates.
+
+The following fields can be accessed via `.Params.include_toc` and `.Params.show_comments`, respectively. The [Variables] section provides more information on using Hugo's page- and site-level variables in your templates.
+
+{{< code-toggle >}}
+include_toc: true
+show_comments: false
+{{</ code-toggle >}}
+
+## Front matter cascade
+
+Any node or section can pass down to descendants a set of front matter values as long as defined underneath the reserved `cascade` front matter key.
+
+### Target specific pages
+
+The `cascade` block can be a slice with a optional `_target` keyword, allowing for multiple `cascade` values targeting different page sets.
+
+{{< code-toggle >}}
+title ="Blog"
+[[cascade]]
+background = "yosemite.jpg"
+[cascade._target]
+path="/blog/**"
+lang="en"
+kind="page"
+[[cascade]]
+background = "goldenbridge.jpg"
+[cascade._target]
+kind="section"
+{{</ code-toggle >}}
+
+Keywords available for `_target`:
+
+path
+: A [Glob](https://github.com/gobwas/glob) pattern matching the content path below /content. Expects Unix-styled slashes. Note that this is the virtual path, so it starts at the mount root. The matching supports double-asterisks so you can match for patterns like `/blog/*/**` to match anything from the third level and down.
+
+kind
+: A Glob pattern matching the Page's Kind(s), e.g. "{home,section}".
+
+lang
+: A Glob pattern matching the Page's language, e.g. "{en,sv}".
+
+environment
+: A Glob pattern matching the build environment, e.g. "{production,development}"
+
+Any of the above can be omitted.
+
+{{% note %}}
+When making a site that supports multiple languages, defining a `[[cascade]]` is recommended to be done in [Site Config](../../getting-started/configuration/#cascade) to prevent duplication.
+
++If you instead define a `[[cascade]]` in front matter for multiple languages, an `content/XX/foo/_index.md` file needs to be made on a per-language basis, with `XX` the glob pattern matching the Page's language. In this case, the **lang** keyword is ignored.
+{{% /note %}}
+
+### Example
+
+In `content/blog/_index.md`
+
+{{< code-toggle >}}
+title: Blog
+cascade:
+ banner: images/typewriter.jpg
+{{</ code-toggle >}}
+
+With the above example the Blog section page and its descendants will return `images/typewriter.jpg` when `.Params.banner` is invoked unless:
+
+- Said descendant has its own `banner` value set
+- Or a closer ancestor node has its own `cascade.banner` value set.
+
+## Order content through front matter
+
+You can assign content-specific `weight` in the front matter of your content. These values are especially useful for [ordering][ordering] in list views. You can use `weight` for ordering of content and the convention of [`<TAXONOMY>_weight`][taxweight] for ordering content within a taxonomy. See [Ordering and Grouping Hugo Lists][lists] to see how `weight` can be used to organize your content in list views.
+
+## Override global markdown configuration
+
+It's possible to set some options for Markdown rendering in a content's front matter as an override to the [rendering options set in your project configuration][config].
+
+## Front matter format specs
+
+- [TOML Spec][toml]
+- [YAML Spec][yaml]
+- [JSON Spec][json]
+
+[variables]: /variables/
+[aliases]: /content-management/urls/#aliases
+[archetype]: /content-management/archetypes/
+[config]: /getting-started/configuration/
+[content type]: /content-management/types/
+[contentorg]: /content-management/organization/
+[headless-bundle]: /content-management/page-bundles/#headless-bundle
+[json]: https://www.ecma-international.org/publications/files/ECMA-ST/ECMA-404.pdf
+[lists]: /templates/lists/#sort-content
+[lookup]: /templates/lookup-order/
+[ordering]: /templates/lists/
+[outputs]: /templates/output-formats/
+[page-resources]: /content-management/page-resources/
+[pagevars]: /variables/page/
+[section]: /content-management/sections/
+[taxweight]: /content-management/taxonomies/
+[toml]: https://toml.io/
+[urls]: /content-management/urls/
+[variables]: /variables/
+[yaml]: https://yaml.org/spec/
--- /dev/null
- description: Include mathematical equations and expressions in your markdown using LaTeX or TeX typsetting syntax.
+---
+title: Mathematics in markdown
+linkTitle: Mathematics
- keywords: [chemical,chemistry,latex,math,mathjax,tex,typsetting]
++description: Include mathematical equations and expressions in your markdown using LaTeX or TeX typesetting syntax.
+categories: [content management]
- Follow these instructions to include mathematical equations and expressions in your markdown using LaTeX or TeX typsetting syntax.
++keywords: [chemical,chemistry,latex,math,mathjax,tex,typesetting]
+menu:
+ docs:
+ parent: content-management
+ weight: 250
+weight: 250
+toc: true
+math: true
+---
+
+{{< new-in 0.122.0 >}}
+
+\[
+\begin{aligned}
+KL(\hat{y} || y) &= \sum_{c=1}^{M}\hat{y}_c \log{\frac{\hat{y}_c}{y_c}} \\
+JS(\hat{y} || y) &= \frac{1}{2}(KL(y||\frac{y+\hat{y}}{2}) + KL(\hat{y}||\frac{y+\hat{y}}{2}))
+\end{aligned}
+\]
+
+## Overview
+
+Mathematical equations and expressions authored in [LaTeX] or [TeX] are common in academic and scientific publications. Your browser typically renders this mathematical markup using an open-source JavaScript display engine such as [MathJax] or [KaTeX].
+
+For example, this is the mathematical markup for the equations displayed at the top of this page:
+
+```text
+\[
+\begin{aligned}
+KL(\hat{y} || y) &= \sum_{c=1}^{M}\hat{y}_c \log{\frac{\hat{y}_c}{y_c}} \\
+JS(\hat{y} || y) &= \frac{1}{2}(KL(y||\frac{y+\hat{y}}{2}) + KL(\hat{y}||\frac{y+\hat{y}}{2}))
+\end{aligned}
+\]
+```
+
+Equations and expressions can be displayed inline with other text, or as standalone blocks. Block presentation is also known as "display" mode.
+
+Whether an equation or expression appears inline, or as a block, depends on the delimiters that surround the mathematical markup. Delimiters are defined in pairs, where each pair consists of an opening and closing delimiter. The opening and closing delimiters may be the same, or different. Common delimiter pairs are shown in [Step 1].
+
+The approach described below avoids reliance on platform-specific features like shortcodes or code block render hooks. Instead, it utilizes a standardized markup format for mathematical equations and expressions, compatible with the rendering engines used by GitHub, GitLab, [Microsoft VS Code], [Obsidian], [Typora], and others.
+
+## Setup
+
- Include mathematical equations and expressions in your markdown using LaTeX or TeX typsetting syntax.
++Follow these instructions to include mathematical equations and expressions in your markdown using LaTeX or TeX typesetting syntax.
+
+###### Step 1
+
+Enable and configure the Goldmark [passthrough extension] in your site configuration. The passthrough extension preserves raw markdown within delimited snippets of text, including the delimiters themselves.
+
+{{< code-toggle file=hugo copy=true >}}
+[markup.goldmark.extensions.passthrough]
+enable = true
+
+[markup.goldmark.extensions.passthrough.delimiters]
+block = [['\[', '\]'], ['$$', '$$']]
+inline = [['\(', '\)']]
+
+[params]
+math = true
+{{< /code-toggle >}}
+
+The configuration above enables mathematical rendering on every page unless you set the `math` parameter to `false` in front matter. To enable mathematical rendering as needed, set the `math` parameter to `false` in your site configuration, and set the `math` parameter to `true` in front matter. Use this parameter in your base template as shown in [Step 3].
+
+{{% note %}}
+The configuration above precludes the use of the `$...$` delimiter pair for inline equations. Although you can add this delimiter pair to the configuration and JavaScript, you will need to double-escape the `$` symbol when used outside of math contexts to avoid unintended formatting.
+
+See the [inline delimiters](#inline-delimiters) section for details.
+{{% /note %}}
+
+To disable passthrough of inline snippets, omit the `inline` key from the configuration:
+
+{{< code-toggle file=hugo >}}
+[markup.goldmark.extensions.passthrough.delimiters]
+block = [['\[', '\]'], ['$$', '$$']]
+{{< /code-toggle >}}
+
+You can define your own opening and closing delimiters, provided they match the delimiters that you set in [Step 2].
+
+{{< code-toggle file=hugo >}}
+[markup.goldmark.extensions.passthrough.delimiters]
+block = [['@@', '@@']]
+inline = [['@', '@']]
+{{< /code-toggle >}}
+
+###### Step 2
+
+Create a partial template to load MathJax or KaTeX. The example below loads MathJax, or you can use KaTeX as described in the [engines](#engines) section.
+
+{{< code file=layouts/partials/math.html copy=true >}}
+<script id="MathJax-script" async src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-chtml.js"></script>
+<script>
+ MathJax = {
+ tex: {
+ displayMath: [['\\[', '\\]'], ['$$', '$$']], // block
+ inlineMath: [['\\(', '\\)']] // inline
+ }
+ };
+</script>
+{{< /code >}}
+
+The delimiters above must match the delimiters in your site configuration.
+
+###### Step 3
+
+Conditionally call the partial template from the base template.
+
+{{< code file=layouts/_default/baseof.html >}}
+<head>
+ ...
+ {{ if .Param "math" }}
+ {{ partialCached "math.html" . }}
+ {{ end }}
+ ...
+</head>
+{{< /code >}}
+
+The example above loads the partial template if you have set the `math` parameter in front matter to `true`. If you have not set the `math` parameter in front matter, the conditional statement falls back to the `math` parameter in your site configuration.
+
+###### Step 4
+
++Include mathematical equations and expressions in your markdown using LaTeX or TeX typesetting syntax.
+
+{{< code file=content/math-examples.md copy=true >}}
+This is an inline \(a^*=x-b^*\) equation.
+
+These are block equations:
+
+\[a^*=x-b^*\]
+
+\[ a^*=x-b^* \]
+
+\[
+a^*=x-b^*
+\]
+
+These are block equations using alternate delimiters:
+
+$$a^*=x-b^*$$
+
+$$ a^*=x-b^* $$
+
+$$
+a^*=x-b^*
+$$
+{{< /code >}}
+
+If you set the `math` parameter to `false` in your site configuration, you must set the `math` parameter to `true` in front matter. For example:
+
+{{< code-toggle file=content/math-examples.md fm=true >}}
+title = 'Math examples'
+math = true
+date = 2024-01-24T18:09:49-08:00
+{{< /code-toggle >}}
+
+## Inline delimiters
+
+The configuration, JavaScript, and examples above use the `\(...\)` delimiter pair for inline equations. The `$...$` delimiter pair is a common alternative, but using it may result in unintended formatting if you use the `$` symbol outside of math contexts.
+
+If you add the `$...$` delimiter pair to your configuration and JavaScript, you must double-escape the `$` when outside of math contexts, regardless of whether mathematical rendering is enabled on the page. For example:
+
+```text
+A \\$5 bill _saved_ is a \\$5 bill _earned_.
+```
+
+{{% note %}}
+If you use the `$...$` delimiter pair for inline equations, and occasionally use the `$` symbol outside of math contexts, you must use MathJax instead of KaTeX to avoid unintended formatting caused by [this KaTeX limitation](https://github.com/KaTeX/KaTeX/issues/437).
+{{% /note %}}
+
+## Engines
+
+MathJax and KaTeX are open-source JavaScript display engines. Both engines are fast, but at the time of this writing MathJax v3.2.2 is slightly faster than KaTeX v0.16.9.
+
+{{% note %}}
+If you use the `$...$` delimiter pair for inline equations, and occasionally use the `$` symbol outside of math contexts, you must use MathJax instead of KaTeX to avoid unintended formatting caused by [this KaTeX limitation](https://github.com/KaTeX/KaTeX/issues/437).
+
+See the [inline delimiters](#inline-delimiters) section for details.
+{{% /note %}}
+
+To use KaTeX instead of MathJax, replace the partial template from [Step 2] with this:
+
+{{< code file=layouts/partials/math.html copy=true >}}
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.16.9/dist/katex.min.css" integrity="sha384-n8MVd4RsNIU0tAv4ct0nTaAbDJwPJzDEaqSD1odI+WdtXRGWt2kTvGFasHpSy3SV" crossorigin="anonymous">
+<script defer src="https://cdn.jsdelivr.net/npm/katex@0.16.9/dist/katex.min.js" integrity="sha384-XjKyOOlGwcjNTAIQHIpgOno0Hl1YQqzUOEleOLALmuqehneUG+vnGctmUb0ZY0l8" crossorigin="anonymous"></script>
+<script defer src="https://cdn.jsdelivr.net/npm/katex@0.16.9/dist/contrib/auto-render.min.js" integrity="sha384-+VBxd3r6XgURycqtZ117nYw44OOcIax56Z4dCRWbxyPt0Koah1uHoK0o4+/RRE05" crossorigin="anonymous"></script>
+<script>
+ document.addEventListener("DOMContentLoaded", function() {
+ renderMathInElement(document.body, {
+ delimiters: [
+ {left: '\\[', right: '\\]', display: true}, // block
+ {left: '$$', right: '$$', display: true}, // block
+ {left: '\\(', right: '\\)', display: false}, // inline
+ ],
+ throwOnError : false
+ });
+ });
+</script>
+{{< /code >}}
+
+The delimiters above must match the delimiters in your site configuration.
+
+## Chemistry
+
+Both MathJax and KaTeX provide support for chemical equations. For example:
+
+```text
+$$C_p[\ce{H2O(l)}] = \pu{75.3 J // mol K}$$
+```
+
+$$C_p[\ce{H2O(l)}] = \pu{75.3 J // mol K}$$
+
+As shown in [Step 2] above, MathJax supports chemical equations without additional configuration. To add chemistry support to KaTeX, enable the mhchem extension as described in the KaTeX [documentation](https://katex.org/docs/libs).
+
+[KaTeX]: https://katex.org/
+[LaTeX]: https://www.latex-project.org/
+[MathJax]: https://www.mathjax.org/
+[Microsoft VS Code]: https://code.visualstudio.com/
+[Obsidian]: https://obsidian.md/
+[Step 1]: #step-1
+[Step 2]: #step-2
+[Step 3]: #step-3
+[TeX]: https://en.wikipedia.org/wiki/TeX
+[Typora]: https://typora.io/
+[passthrough extension]: https://github.com/gohugoio/hugo-goldmark-extensions
--- /dev/null
- ## Introduction
-
- Hugo is an open-source project and lives by the work of its [contributors]. There are plenty of [open issues][issues], and we need your help to make Hugo even more awesome. You don't need to be a Go guru to contribute to the project's development.
-
- ## Assumptions
-
- This contribution guide takes a step-by-step approach in hopes of helping newcomers. Therefore, we only assume the following:
-
- * You are new to Git or open-source projects in general
- * You are a fan of Hugo and enthusiastic about contributing to the project
-
- {{% note %}}
- If you're struggling at any point in this contribution guide, reach out to the Hugo community in [Hugo's Discussion forum](https://discourse.gohugo.io).
- {{% /note %}}
-
- ## Install Go
-
- The installation of Go should take only a few minutes. You have more than one option to get Go up and running on your machine.
-
- If you are having trouble following the installation guides for Go, check out [Go Bootcamp, which contains setups for every platform][gobootcamp] or reach out to the Hugo community in the [Hugo Discussion Forums][forums].
-
- ### Install Go from source
-
- [Download the latest stable version of Go][godl] and follow the official [Go installation guide][goinstall].
-
- Once you're finished installing Go, let's confirm everything is working correctly. Open a terminal---or command line under Windows--and type the following:
-
- ```txt
- go version
- ```
-
- You should see something similar to the following written to the console. Note that the version here reflects the most recent version of Go as of the last update for this page:
-
- ```txt
- go version go1.12 darwin/amd64
- ```
-
- Next, make sure that you set up your `GOPATH` [as described in the installation guide][setupgopath].
-
- You can print the `GOPATH` with `echo $GOPATH`. You should see a non-empty string containing a valid path to your Go workspace; for example:
-
- ```txt
- /Users/<yourusername>/Code/go
- ```
-
- ### Install Go with Homebrew
-
- If you are a macOS user and have [Homebrew](https://brew.sh/) installed on your machine, installing Go is as simple as the following command:
-
- {{< code file=install-go.sh >}}
- brew install go
- {{< /code >}}
-
- ### Install Go via GVM
-
- More experienced users can use the [Go Version Manager][gvm] (GVM). GVM allows you to switch between different Go versions *on the same machine*. If you're a beginner, you probably don't need this feature. However, GVM makes it easy to upgrade to a new released Go version with just a few commands.
-
- GVM comes in especially handy if you follow the development of Hugo over a longer period of time. Future versions of Hugo will usually be compiled with the latest version of Go. Sooner or later, you will have to upgrade if you want to keep up.
-
- ## Create a GitHub account
-
- If you're going to contribute code, you'll need to have an account on GitHub. Go to [www.github.com/join](https://github.com/join) and set up a personal account.
-
- ## Install Git on your system
-
- You will need to have Git installed on your computer to contribute to Hugo development. Teaching Git is outside the scope of the Hugo docs, but if you're looking for an excellent reference to learn the basics of Git, we recommend the [Git book][gitbook] if you are not sure where to begin. We will include short explanations of the Git commands in this document.
-
- Git is a [version control system](https://en.wikipedia.org/wiki/Version_control) to track the changes of source code. Hugo depends on smaller third-party packages that are used to extend the functionality. We use them because we don't want to reinvent the wheel.
-
- Go ships with a sub-command called `get` that will download these packages for us when we set up our working environment. The source code of the packages is tracked with Git. `get` will interact with the Git servers of the package hosters in order to fetch all dependencies.
-
- Move back to the terminal and check if Git is already installed. Type in `git version` and press enter. You can skip the rest of this section if the command returned a version number. Otherwise [download](https://git-scm.com/downloads) the latest version of Git and follow this [installation guide](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git).
+---
+title: Development
+description: Contribute to the development of Hugo.
+categories: [contribute]
+keywords: [development]
+menu:
+ docs:
+ parent: contribute
+ weight: 20
+weight: 20
+toc: true
+---
+
- Finally, check again with `git version` if Git was installed successfully.
+
- ### Git graphical front ends
+
- There are several [GUI clients](https://git-scm.com/downloads/guis) that help you to operate Git. Not all are available for all operating systems and maybe differ in their usage. Because of this we will document how to use the command-line, since the commands are the same everywhere.
++## Introduction
+
- ### Install Hub on your system (optional)
++You can contribute to the Hugo project by:
+
- Hub is a great tool for working with GitHub. The main site for it is [hub.github.com](https://hub.github.com/). Feel free to install this little Git wrapper.
++- Answering questions on the [forum]
++- Improving the [documentation]
++- Monitoring the [issue queue]
++- Creating or improving [themes]
++- Squashing [bugs]
+
- On a Mac, you can install [Hub](https://github.com/github/hub) using [Homebrew](https://brew.sh):
++Please submit documentation issues and pull requests to the [documentation repository].
+
- ```txt
- brew install hub
- ```
++If you have an idea for an enhancement or new feature, create a new topic on the [forum] in the "Feature" category. This will help you to:
+
- Now we'll create an [alias in Bash](https://tldp.org/LDP/abs/html/aliases.html) so that typing `git` actually runs `Hub`:
++- Determine if the capability already exists
++- Measure interest
++- Refine the concept
+
- ```txt
- echo "alias git='hub'" >> ~/.bash_profile
- ```
++If there is sufficient interest, [create a proposal]. Do not submit a pull request until the project lead accepts the proposal.
+
- Confirm the installation:
-
- ```txt
- git version 2.21.0
- hub version 2.10.0
- ```
++For a complete guide to contributing to Hugo, see the [Contribution Guide].
+
- ## Set up your working copy
++[bugs]: https://github.com/gohugoio/hugo/issues?q=is%3Aopen+is%3Aissue+label%3ABug
++[contributing]: CONTRIBUTING.md
++[create a proposal]: https://github.com/gohugoio/hugo/issues/new?labels=Proposal%2C+NeedsTriage&template=feature_request.md
++[documentation repository]: https://github.com/gohugoio/hugoDocs
++[documentation]: https://gohugo.io/documentation
++[forum]: https://discourse.gohugo.io
++[issue queue]: https://github.com/gohugoio/hugo/issues
++[themes]: https://themes.gohugo.io/
++[contribution guide]: https://github.com/gohugoio/hugo/blob/master/CONTRIBUTING.md
+
- You set up the working copy of the repository locally on your computer. Your local copy of the files is what you'll edit, compile, and end up pushing back to GitHub. The main steps are cloning the repository and creating your fork as a remote.
++## Prerequisites
+
- ### Clone the repository
++To build the extended edition of Hugo from source you must:
+
- We assume that you've set up your `GOPATH` (see the section above if you're unsure about this). You should now copy the Hugo repository down to your computer. You'll hear this called "clone the repo". GitHub's [help pages](https://help.github.com/articles/cloning-a-repository/) give us a short explanation:
++1. Install [Git]
++1. Install [Go] version 1.20 or later
++1. Install a C compiler, either [GCC] or [Clang]
++1. Update your `PATH` environment variable as described in the [Go documentation]
+
- When you create a repository on GitHub, it exists as a remote repository. You can create a local clone of your repository on your computer and sync between the two locations.
++[Clang]: https://clang.llvm.org/
++[GCC]: https://gcc.gnu.org/
++[Git]: https://git-scm.com/book/en/v2/Getting-Started-Installing-Git
++[Go documentation]: https://go.dev/doc/code#Command
++[Go]: https://go.dev/doc/install
+
+{{% note %}}
- We're going to clone the [master Hugo repository](https://github.com/gohugoio/hugo). That seems counter-intuitive, since you won't have commit rights on it. But it's required for the Go workflow. You'll work on a copy of the master and push your changes to your own repository on GitHub.
-
- So, let's make a new directory and clone that master repository:
-
- ```txt
- mkdir $HOME/src
- cd $HOME/src
- git clone https://github.com/gohugoio/hugo.git
- ```
-
- Since Hugo 0.48, Hugo uses the Go Modules support built into Go 1.11 to build. The easiest is to clone Hugo in a directory outside of GOPATH
-
- And then, install dependencies of Hugo by running the following in the cloned directory:
-
- ```txt
- cd $HOME/src/hugo
- go install
- ```
-
- Hugo relies on [mage](https://github.com/magefile/mage) for some convenient build and test targets. If you don't already have it, get it:
-
- ```txt
- go install github.com/magefile/mage@latest
- ```
-
- ### Fork the repository
-
- If you're not familiar with this term, GitHub's [help pages](https://help.github.com/articles/fork-a-repo/) provide again a simple explanation:
++See these [detailed instructions](https://discourse.gohugo.io/t/41370) to install GCC on Windows.
+{{% /note %}}
+
- A fork is a copy of a repository. Forking a repository allows you to freely experiment with changes without affecting the original project.
++## GitHub workflow
+
+{{% note %}}
- #### Fork by hand
++This section assumes that you have a working knowledge of Go, Git and GitHub, and are comfortable working on the command line.
+{{% /note %}}
+
- Open the [Hugo repository](https://github.com/gohugoio/hugo) on GitHub and click on the "Fork" button in the top right.
++Use this workflow to create and submit pull requests.
+
- 
++Step 1
++: Fork the [project repository].
+
- Now open your fork repository on GitHub and copy the remote URL of your fork. You can choose between HTTPS and SSH as protocol that Git should use for the following operations. HTTPS works always [if you're not sure](https://help.github.com/articles/which-remote-url-should-i-use/).
++[project repository]: https://github.com/gohugoio/hugo/
+
- 
++Step 2
++: Clone your fork.
+
- Switch back to the terminal and move into the directory of the cloned master repository from the last step.
++Step 3
++: Create a new branch with a descriptive name that includes the corresponding issue number.
+
- ```txt
- cd $HOME/src/hugo
++For a new feature:
+
- Now Git needs to know that our fork exists by adding the copied remote url:
++```sh
++git checkout -b feat/implement-some-feature-99999
+```
+
- ```txt
- git remote add <YOUR-GITHUB-USERNAME> <COPIED REMOTE-URL>
++For a bug fix:
+
- #### Fork with Hub
++```sh
++git checkout -b fix/fix-some-bug-99999
+```
+
- Alternatively, you can use the Git wrapper Hub. Hub makes forking a repository easy:
++Step 4
++: Make changes.
+
- ```txt
- git fork
++Step 5
++: Compile and install:
+
- That command will log in to GitHub using your account, create a fork of the repository that you're currently working in, and add it as a remote to your working copy.
-
- #### Trust, but verify
++```text
++CGO_ENABLED=1 go install -tags extended
+```
+
- Let's check if everything went right by listing all known remotes:
-
- ```txt
- git remote -v
++Step 6
++: Test your changes:
+
- The output should look similar:
-
- ```txt
- digitalcraftsman git@github.com:digitalcraftsman/hugo.git (fetch)
- digitalcraftsman git@github.com:digitalcraftsman/hugo.git (push)
- origin https://github.com/gohugoio/hugo (fetch)
- origin https://github.com/gohugoio/hugo (push)
- ```
-
- ## The Hugo Git contribution workflow
-
- ### Create a new branch
-
- You should never develop against the "master" branch. The development team will not accept a pull request against that branch. Instead, create a descriptive named branch and work on it.
-
- First, you should always pull the latest changes from the master repository:
-
- ```txt
- git checkout master
- git pull
- ```
-
- Now we can create a new branch for your additions:
-
- ```txt
- git checkout -b <BRANCH-NAME>
- ```
-
- You can check on which branch you are with `git branch`. You should see a list of all local branches. The current branch is indicated with a little asterisk.
-
- ### Contribute to documentation
-
- Perhaps you want to start contributing to the Hugo docs. If so, you can ignore most of the following steps and focus on the `/docs` directory within your newly cloned repository. You can change directories into the Hugo docs using `cd docs`.
-
- You can start Hugo's built-in server via `hugo server`. Browse the documentation by entering [http://localhost:1313](http://localhost:1313) in the address bar of your browser. The server automatically updates the page whenever you change content.
-
- We have developed a [separate Hugo documentation contribution guide][docscontrib] for more information on how the Hugo docs are built, organized, and improved by the generosity of people like you.
++```text
++go test ./...
+```
+
- ### Build Hugo
++Step 7
++: Commit your changes with a descriptive commit message:
+
- While making changes in the codebase it's a good idea to build the binary to test them:
-
- ```txt
- mage hugo
- ```
-
- This command generates the binary file at the root of the repository.
-
- If you want to install the binary in `$GOPATH/bin`, run
-
- ```txt
- mage install
- ```
-
- ### Test
-
- Sometimes changes on the codebase can cause unintended side effects. Or they don't work as expected. Most functions have their own test cases. You can find them in files ending with `_test.go`.
-
- Make sure the commands
-
- ```txt
- mage -v check
- ```
-
- passes.
-
- ### Formatting
-
- The Go code style guide maybe is opinionated but it ensures that the codebase looks the same, regardless who wrote the code. Go comes with its own formatting tool. Let's apply the style guide to our additions:
-
- ```txt
- mage fmt
- ```
-
- Once you made your additions commit your changes. Make sure that you follow our [code contribution guidelines](https://github.com/gohugoio/hugo/blob/master/CONTRIBUTING.md):
-
- ```txt
- # Add all changed files
- git add --all
- git commit --message "YOUR COMMIT MESSAGE"
- ```
-
- The commit message should describe what the commit does (e.g. add feature XYZ), not how it is done.
-
- ### Modify commits
-
- You noticed some commit messages don't fulfill the code contribution guidelines or you just forget something to add some files? No problem. Git provides the necessary tools to fix such problems. The next two methods cover all common cases.
-
- If you are unsure what a command does leave the commit as it is. We can fix your commits later in the pull request.
-
- #### Modify the last commit
-
- Let's say you want to modify the last commit message. Run the following command and replace the current message:
-
- ```txt
- git commit --amend -m"YOUR NEW COMMIT MESSAGE"
- ```
-
- Take a look at the commit log to see the change:
-
- ```txt
- git log
- # Exit with q
- ```
-
- After making the last commit you may have forgotten something. There is no need to create a new commit. Just add the latest changes and merge them into the intended commit:
-
- ```txt
- git add --all
- git commit --amend
- ```
-
- #### Modify multiple commits
-
- {{% note %}}
- Modifications such as those described in this section can have serious unintended consequences. Skip this section if you're not sure!
- {{% /note %}}
-
- This is a bit more advanced. Git allows you to [rebase](https://git-scm.com/docs/git-rebase) commits interactively. In other words: it allows you to rewrite the commit history.
-
- ```txt
- git rebase --interactive @~6
- ```
-
- The `6` at the end of the command represents the number of commits that should be modified. An editor should open and present a list of last six commit messages:
-
- ```txt
- pick 80d02a1 tpl: Add hasPrefix to template function smoke test"
- pick aaee038 tpl: Sort the smoke tests
- pick f0dbf2c tpl: Add the other test case for hasPrefix
- pick 911c35b Add "How to contribute to Hugo" tutorial
- pick 33c8973 Begin workflow
- pick 3502f2e Refactoring and typo fixes
- ```
-
- In the case above we should merge the last two commits in the commit of this tutorial (`Add "How to contribute to Hugo" tutorial`). You can "squash" commits, i.e. merge two or more commits into a single one.
-
- All operations are written before the commit message. Replace "pick" with an operation. In this case `squash` or `s` for short:
-
- ```txt
- pick 80d02a1 tpl: Add hasPrefix to template function smoke test"
- pick aaee038 tpl: Sort the smoke tests
- pick f0dbf2c tpl: Add the other test case for hasPrefix
- pick 911c35b Add "How to contribute to Hugo" tutorial
- squash 33c8973 Begin workflow
- squash 3502f2e Refactoring and typo fixes
- ```
-
- We also want to rewrite the commits message of the third last commit. We forgot "docs:" as prefix according to the code contribution guidelines. The operation to rewrite a commit is called `reword` (or `r` as shortcut).
-
- You should end up with a similar setup:
-
- ```txt
- pick 80d02a1 tpl: Add hasPrefix to template function smoke test"
- pick aaee038 tpl: Sort the smoke tests
- pick f0dbf2c tpl: Add the other test case for hasPrefix
- reword 911c35b Add "How to contribute to Hugo" tutorial
- squash 33c8973 Begin workflow
- squash 3502f2e Refactoring and typo fixes
- ```
-
- Close the editor. It should open again with a new tab. A text is instructing you to define a new commit message for the last two commits that should be merged (aka "squashed"). Save the file with <kbd>CTRL</kbd>+<kbd>S</kbd> and close the editor again.
-
- A last time a new tab opens. Enter a new commit message and save again. Your terminal should contain a status message. Hopefully this one:
-
- ```txt
- Successfully rebased and updated refs/heads/<BRANCHNAME>.
- ```
++- Provide a summary on the first line, typically 50 characters or less, followed by a blank line.
++- Optionally, provide a detailed description where each line is 80 characters or less, followed by a blank line.
++- Add one or more "Fixes" or "Closes" keywords, each on its own line, referencing the [issues] addressed by this change.
+
- Check the commit log if everything looks as expected. Should an error occur you can abort this rebase with `git rebase --abort`.
++[issues]: https://github.com/gohugoio/hugo/issues
+
- ### Push commits
++For example:
+
- To push our commits to the fork on GitHub we need to specify a destination. A destination is defined by the remote and a branch name. Earlier, the defined that the remote URL of our fork is the same as our GitHub handle, in my case `digitalcraftsman`. The branch should have the same as our local one. This makes it easy to identify corresponding branches.
++```sh
++git commit -m "tpl/strings: Create wrap function
+
- ```txt
- git push --set-upstream <YOUR-GITHUB-USERNAME> <BRANCHNAME>
++The strings.Wrap function wraps a string into one or more lines,
++splitting the string after the given number of characters, but not
++splitting in the middle of a word.
+
- Now Git knows the destination. Next time when you to push commits you just need to enter `git push`.
-
- If you modified your commit history in the last step GitHub will reject your try to push. This is a safety-feature because the commit history isn't the same and new commits can't be appended as usual. You can enforce this push explicitly with `git push --force`.
-
- ## Open a pull request
-
- We made a lot of progress. Good work. In this step we finally open a pull request to submit our additions. Open the [Hugo master repository](https://github.com/gohugoio/hugo/) on GitHub in your browser.
-
- You should find a green button labeled with "New pull request". But GitHub is clever and probably suggests you a pull request like in the beige box below:
-
- 
-
- The new page summaries the most important information of your pull request. Scroll down and you find the additions of all your commits. Make sure everything looks as expected and click on "Create pull request".
++Fixes #99998
++Closes #99999"
+```
+
- ### Accept the contributor license agreement
++See the [commit message guidelines] for details.
+
- Last but not least you should accept the contributor license agreement (CLA). A new comment should be added automatically to your pull request. Click on the yellow badge, accept the agreement and authenticate yourself with your GitHub account. It just takes a few clicks and only needs to be done once.
++[commit message guidelines]: https://github.com/gohugoio/hugo/blob/master/CONTRIBUTING.md#git-commit-message-guidelines
+
- 
++Step 8
++: Push the new branch to your fork of the documentation repository.
+
- ### Automatic builds
-
- We use a GitHub Actions workflow to build and test. This is a matrix build across combinations of operating system (macOS, Windows, and Ubuntu) and Go versions. The workflow is triggered by the submission of a pull request. If you are a first-time contributor, the workflow requires approval from a project maintainer.
-
- ## Where to start?
-
- Thank you for reading through this contribution guide. Hopefully, we will see you again soon on GitHub. There are plenty of [open issues][issues] for you to help with.
-
- Feel free to [open an issue][newissue] if you think you found a bug or you have a new idea to improve Hugo. We are happy to hear from you.
-
- ## Additional references for learning Git and Go
-
- * [Codecademy's Free "Learn Git" Course][codecademy] (Free)
- * [Code School and GitHub's "Try Git" Tutorial][trygit] (Free)
- * [The Git Book][gitbook] (Free)
- * [Go Bootcamp][gobootcamp]
-
- [codecademy]: https://www.codecademy.com/learn/learn-git
- [contributors]: https://github.com/gohugoio/hugo/graphs/contributors
- [docscontrib]: /contribute/documentation/
- [forums]: https://discourse.gohugo.io
- [gitbook]: https://git-scm.com/
- [gobootcamp]: https://www.golang-book.com/guides/machine_setup
- [godl]: https://go.dev/dl/
- [goinstall]: https://go.dev/doc/install
- [gvm]: https://github.com/moovweb/gvm
- [issues]: https://github.com/gohugoio/hugo/issues
- [newissue]: https://github.com/gohugoio/hugo/issues/new
- [releases]: /getting-started/
- [setupgopath]: https://go.dev/doc/code#Workspaces
- [trygit]: https://try.github.io/levels/1/challenges/1
++Step 9
++: Visit the [project repository] and create a pull request (PR).
+
++Step 10
++: A project maintainer will review your PR and may request changes. You may delete your branch after the maintainer merges your PR.
--- /dev/null
- : Create a new branch with a descriptive name.
+---
+title: Documentation
+description: Help us to improve the documentation by identifying issues and suggesting changes.
+categories: [contribute]
+keywords: [documentation]
+menu:
+ docs:
+ parent: contribute
+ weight: 30
+weight: 30
+toc: true
+aliases: [/contribute/docs/]
+---
+
+## Introduction
+
+We welcome corrections and improvements to the documentation. Please note that the documentation resides in its own repository, separate from the project repository.
+
+For corrections and improvements to the current documentation, please submit issues and pull requests to the [documentation repository].
+
+For documentation related to a new feature, please include the documentation changes when you submit a pull request to the [project repository].
+
+## Guidelines
+
+### Markdown
+
+Please follow these markdown guidelines:
+
+- Use [ATX] headings, not [setext] headings, levels 2 through 4
+- Use [fenced code blocks], not [indented code blocks]
+- Use hyphens, not asterisks, with unordered [list items]
+- Use the [note shortcode] instead of blockquotes
+- Do not mix [raw HTML] within markdown
+- Do not use bold text instead of a heading or description term (`dt`)
+- Remove consecutive blank lines (maximum of two)
+- Remove trailing spaces
+
+### Style
+
+Although we do not strictly adhere to the [Microsoft Writing Style Guide], it is an excellent resource for questions related to style, grammar, and voice.
+
+#### Terminology
+
+Please link to the [glossary of terms] when necessary, and use the terms consistently throughout the documentation. Of special note:
+
+- The term "front matter" is two words unless you are referring to the configuration key
+- Use the word "map" instead of "dictionary"
+- Use the word "flag" instead of "option" when referring to a command line flag
+
+#### Page titles and headings
+
+Please follow these guidelines for page titles and headings:
+
+- Use sentence-style capitalization
+- Avoid markdown in headings and page titles
+- Shorter is better
+
+#### Use active voice with present tense
+
+In software documentation, passive voice is unavoidable in some cases. Please use active voice when possible.
+
+No → With Hugo you can build a static site.\
+Yes → Build a static site with Hugo.
+
+No → This will cause Hugo to generate HTML files in the public directory.\
+Yes → Hugo generates HTML files in the public directory.
+
+#### Use second person instead of third person
+
+No → Users should exercise caution when deleting files.\
+Better → You must be cautious when deleting files.\
+Best → Be cautious when deleting files.
+
+#### Avoid adverbs when possible
+
+No → Hugo is extremely fast.\
+Yes → Hugo is fast.
+
+{{% note %}}
+"It's an adverb, Sam. It's a lazy tool of a weak mind." (Outbreak, 1995).
+{{% /note %}}
+
+#### Miscellaneous
+
+Other guidelines to consider:
+
+- Do not place list items directly under a heading; include an introductory sentence or phrase before the list.
+- Avoid use of **bold** text. Use the [note shortcode] to draw attention to important content.
+- Do not place description terms (`dt`) within backticks unless required for syntactic clarity.
+- Do not use Hugo's `ref` or `relref` shortcodes. We use a link render hook to resolve and validate link destinations, including fragments.
+- Shorter is better. If there is more than one way to do something, describe the current best practice. For example, avoid phrases such as "you can also do..." and "in older versions you had to..."
+- When including code samples, use short snippets that demonstrate the concept.
+- The Hugo user community is global; use [basic english](https://simple.wikipedia.org/wiki/Basic_English) when possible.
+
+#### Level 6 markdown headings
+
+Level 6 markdown headings are styled as `dt` elements. This was implemented to support a [glossary] with linkable terms.
+
+[glossary]: /getting-started/glossary
+
+## Code examples
+
+Indent code by two spaces. With examples of template code, include a space after opening action delimiters, and include a space before closing action delimiters.
+
+### Fenced code blocks
+
+Always include the language code when using a fenced code block:
+
+````text
+```go-html-template
+{{ if eq $foo "bar" }}
+ {{ print "foo is bar" }}
+{{ end }}
+```
+````
+
+Rendered:
+
+```go-html-template
+{{ if eq $foo "bar" }}
+ {{ print "foo is bar" }}
+{{ end }}
+```
+
+### Shortcode calls
+
+Use this syntax to include shortcodes calls within your code examples:
+
+```text
+{{</*/* foo */*/>}}
+{{%/*/* foo */*/%}}
+```
+
+Rendered:
+
+```text
+{{</* foo */>}}
+{{%/* foo */%}}
+```
+
+### Site configuration
+
+Use the [code-toggle shortcode] to include site configuration examples:
+
+```text
+{{</* code-toggle file=hugo */>}}
+baseURL = 'https://example.org/'
+languageCode = 'en-US'
+title = 'My Site'
+{{</* /code-toggle */>}}
+```
+
+Rendered:
+
+{{< code-toggle file=hugo >}}
+baseURL = 'https://example.org/'
+languageCode = 'en-US'
+title = 'My Site'
+{{< /code-toggle >}}
+
+### Front matter
+
+Use the [code-toggle shortcode] to include front matter examples:
+
+```text
+{{</* code-toggle file=content/posts/my-first-post.md fm=true */>}}
+title = 'My first post'
+date = 2023-11-09T12:56:07-08:00
+draft = false
+{{</* /code-toggle */>}}
+```
+
+Rendered:
+
+{{< code-toggle file=content/posts/my-first-post.md fm=true >}}
+title = 'My first post'
+date = 2023-11-09T12:56:07-08:00
+draft = false
+{{< /code-toggle >}}
+
+### Other code examples
+
+Use the [code shortcode] for other code examples that require a file name:
+
+```text
+{{</* code file=layouts/_default/single.html */>}}
+{{ range .Site.RegularPages }}
+ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
+{{ end }}
+{{</* /code */>}}
+```
+
+Rendered:
+
+{{< code file=layouts/_default/single.html >}}
+{{ range .Site.RegularPages }}
+ <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
+{{ end }}
+{{< /code >}}
+
+## Shortcodes
+
+These shortcodes are commonly used throughout the documentation. Other shortcodes are available for specialized use.
+
+### deprecated-in
+
+Use the “deprecated-in” shortcode to indicate that a feature is deprecated:
+
+```text
+{{%/* deprecated-in 0.120.0 */%}}
+Use [`hugo.IsServer`] instead.
+
+[`hugo.IsServer`]: /functions/hugo/isserver
+{{%/* /deprecated-in */%}}
+```
+
+Rendered:
+
+{{% deprecated-in 0.120.0 %}}
+Use [`hugo.IsServer`] instead.
+
+[`hugo.IsServer`]: /functions/hugo/isserver
+{{% /deprecated-in %}}
+
+### code
+
+Use the "code" shortcode for other code examples that require a file name. See the [code examples] above. This shortcode takes these arguments:
+
+copy
+: (`bool`) Whether to display a copy-to-clipboard button. Default is `false`.
+
+file
+: (`string`) The file name to display.
+
+lang
+: (`string`) The code language. If you do not provide a `lang` argument, the code language is determined by the file extension. If the file extension is "html", sets the code language to `go-html-template`. Default is `text`.
+
+### code-toggle
+
+Use the "code-toggle" shortcode to display examples of site configuration, front matter, or data files. See the [code examples] above. This shortcode takes these arguments:
+
+copy
+: (`bool`) Whether to display a copy-to-clipboard button. Default is `false`.
+
+file
+: (`string`) The file name to display. Omit the file extension for site configuration examples.
+
+fm
+: (`bool`) Whether the example is front matter. Default is `false`.
+
+### new-in
+
+Use the "new-in" shortcode to indicate a new feature:
+
+```text
+{{</* new-in 0.120.0 */>}}
+```
+
+Rendered:
+
+{{< new-in 0.120.0 >}}
+
+### note
+
+Use the "note" shortcode with `{{%/* */%}}` delimiters to call attention to important content:
+
+```text
+{{%/* note */%}}
+Use the [`math.Mod`] function to control...
+
+[`math.Mod`]: /functions/math/mod/
+{{%/* /note */%}}
+```
+
+Rendered:
+
+{{% note %}}
+Use the [`math.Mod`] function to control...
+
+[`math.Mod`]: /functions/math/mod/
+{{% /note %}}
+
+## New features
+
+Use the "new-in" shortcode to indicate a new feature:
+
+{{< code file=content/something/foo.md lang=text >}}
+{{</* new-in 0.120.0 */>}}
+{{< /code >}}
+
+The "new in" label will be hidden if the specified version is older than a predefined threshold, based on differences in major and minor versions. See [details](https://github.com/gohugoio/hugoDocs/blob/master/layouts/shortcodes/new-in.html).
+
+## Deprecated features
+
+Use the "deprecated-in" shortcode to indicate that a feature is deprecated:
+
+{{< code file=content/something/foo.md >}}
+{{%/* deprecated-in 0.120.0 */%}}
+Use [`hugo.IsServer`] instead.
+
+[`hugo.IsServer`]: /functions/hugo/isserver
+{{%/* /deprecated-in */%}}
+{{< /code >}}
+
+When deprecating a function or method, add this to front matter:
+
+{{< code-toggle file=content/something/foo.md fm=true >}}
+expiryDate: 2024-10-30
+{{< /code-toggle >}}
+
+Set the `expiryDate` to one year from the date of deprecation, and add a brief front matter comment to explain the setting.
+
+## GitHub workflow
+
+{{% note %}}
+This section assumes that you have a working knowledge of Git and GitHub, and are comfortable working on the command line.
+{{% /note %}}
+
+Use this workflow to create and submit pull requests.
+
+Step 1
+: Fork the [documentation repository].
+
+Step 2
+: Clone your fork.
+
+Step 3
- git checkout -b fix/typos-shortcode-templates
++: Create a new branch with a descriptive name that includes the corresponding issue number, if any:
+
+```sh
- : Commit your changes with a descriptive commit message, typically 50 characters or less. Add the "Closes" keyword if your change addresses one or more open [issues].
++git checkout -b restructure-foo-page-99999
+```
+
+Step 4
+: Make changes.
+
+Step 5
- git commit -m "Fix typos on the shortcode templates page
++: Build the site locally to preview your changes.
++
++Step 6
++: Commit your changes with a descriptive commit message:
++
++- Provide a summary on the first line, typically 50 characters or less, followed by a blank line.
++- Optionally, provide a detailed description where each line is 80 characters or less, followed by a blank line.
++- Optionally, add one or more "Fixes" or "Closes" keywords, each on its own line, referencing the [issues] addressed by this change.
++
++For example:
+
+```sh
- Closes #1234
- Closes #5678"
++git commit -m "Restructure the taxonomy page
++
++This restructures the taxonomy page by splitting topics into logical
++sections, each with one or more examples.
+
- Step 6
++Fixes #9999
++Closes #9998"
+```
+
- Step 7
++Step 7
+: Push the new branch to your fork of the documentation repository.
+
- Step 8
++Step 8
+: Visit the [documentation repository] and create a pull request (PR).
+
++Step 9
+: A project maintainer will review your PR and may request changes. You may delete your branch after the maintainer merges your PR.
+
+[ATX]: https://spec.commonmark.org/0.30/#atx-headings
+[Microsoft Writing Style Guide]: https://learn.microsoft.com/en-us/style-guide/welcome/
+[basic english]: https://simple.wikipedia.org/wiki/Basic_English
+[code examples]: #code-examples
+[code shortcode]: #code
+[code-toggle shortcode]: #code-toggle
+[documentation repository]: https://github.com/gohugoio/hugoDocs/
+[fenced code blocks]: https://spec.commonmark.org/0.30/#fenced-code-blocks
+[glossary of terms]: /getting-started/glossary/
+[indented code blocks]: https://spec.commonmark.org/0.30/#indented-code-blocks
+[issues]: https://github.com/gohugoio/hugoDocs/issues
+[list items]: https://spec.commonmark.org/0.30/#list-items
+[note shortcode]: #note
+[project repository]: https://github.com/gohugoio/hugo
+[raw HTML]: https://spec.commonmark.org/0.30/#raw-html
+[setext]: https://spec.commonmark.org/0.30/#setext-heading
--- /dev/null
+---
+title: math.Add
+description: Adds two or more numbers.
+categories: []
+keywords: []
+action:
+ aliases: [add]
+ related:
+ - functions/math/Div
+ - functions/math/Mul
+ - functions/math/Product
+ - functions/math/Sub
+ - functions/math/Sum
+ returnType: any
+ signatures: [math.Add VALUE VALUE...]
+---
+
+If one of the numbers is a [`float`], the result is a `float`.
+
+```go-html-template
+{{ add 12 3 2 }} → 17
+```
+
+[`float`]: /getting-started/glossary/#float
++
++You can also use the `add` function to concatenate strings.
++
++```go-html-template
++{{ add "hu" "go" }} → hugo
++```
--- /dev/null
-
- For more information on using `readDir` and `readFile` in your templates, see [Local File Templates](/templates/files).
+---
+title: os.ReadDir
+description: Returns an array of FileInfo structures sorted by file name, one element for each directory entry.
+categories: []
+keywords: []
+action:
+ aliases: [readDir]
+ related:
+ - functions/os/FileExists
+ - functions/os/Getenv
+ - functions/os/ReadFile
+ - functions/os/Stat
+ returnType: os.FileInfo
+ signatures: [os.ReadDir PATH]
+aliases: [/functions/readdir]
+---
+
+The `os.ReadDir` function resolves the path relative to the root of your project directory. A leading path separator (`/`) is optional.
+
+With this directory structure:
+
+```text
+content/
+├── about.md
+├── contact.md
+└── news/
+ ├── article-1.md
+ └── article-2.md
+```
+
+This template code:
+
+```go-html-template
+{{ range readDir "content" }}
+ {{ .Name }} → {{ .IsDir }}
+{{ end }}
+```
+
+Produces:
+
+```html
+about.md → false
+contact.md → false
+news → true
+```
+
+Note that `os.ReadDir` is not recursive.
+
+Details of the `FileInfo` structure are available in the [Go documentation](https://pkg.go.dev/io/fs#FileInfo).
--- /dev/null
-
- For more information on using `readDir` and `readFile` in your templates, see [Local File Templates](/templates/files).
+---
+title: os.ReadFile
+description: Returns the contents of a file.
+categories: []
+keywords: []
+action:
+ aliases: [readFile]
+ related:
+ - functions/os/FileExists
+ - functions/os/Getenv
+ - functions/os/ReadDir
+ - functions/os/Stat
+ returnType: string
+ signatures: [os.ReadFile PATH]
+aliases: [/functions/readfile]
+---
+
+The `os.ReadFile` function attempts to resolve the path relative to the root of your project directory. If a matching file is not found, it will attempt to resolve the path relative to the [`contentDir`](/getting-started/configuration#contentdir). A leading path separator (`/`) is optional.
+
+With a file named README.md in the root of your project directory:
+
+```text
+This is **bold** text.
+```
+
+This template code:
+
+```go-html-template
+{{ readFile "README.md" }}
+```
+
+Produces:
+
+```html
+This is **bold** text.
+```
+
+Note that `os.ReadFile` returns raw (uninterpreted) content.
--- /dev/null
+---
+title: resources.GetRemote
+description: Returns a remote resource from the given URL, or nil if none found.
+categories: []
+keywords: []
+action:
+ aliases: []
+ related:
+ - functions/data/GetCSV
+ - functions/data/GetJSON
+ - functions/resources/ByType
+ - functions/resources/Get
+ - functions/resources/GetMatch
+ - functions/resources/Match
+ - methods/page/Resources
+ returnType: resource.Resource
+ signatures: ['resources.GetRemote URL [OPTIONS]']
+toc: true
+---
+
+```go-html-template
+{{ $url := "https://example.org/images/a.jpg" }}
+{{ with resources.GetRemote $url }}
+ {{ with .Err }}
+ {{ errorf "%s" . }}
+ {{ else }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+ {{ end }}
+{{ else }}
+ {{ errorf "Unable to get remote resource %q" $url }}
+{{ end }}
+```
+
+## Options
+
+The `resources.GetRemote` function takes an optional map of options.
+
+```go-html-template
+{{ $url := "https://example.org/api" }}
+{{ $opts := dict
+ "headers" (dict "Authorization" "Bearer abcd")
+}}
+{{ $resource := resources.GetRemote $url $opts }}
+```
+
+If you need multiple values for the same header key, use a slice:
+
+```go-html-template
+{{ $url := "https://example.org/api" }}
+{{ $opts := dict
+ "headers" (dict "X-List" (slice "a" "b" "c"))
+}}
+{{ $resource := resources.GetRemote $url $opts }}
+```
+
+You can also change the request method and set the request body:
+
+```go-html-template
+{{ $url := "https://example.org/api" }}
+{{ $opts := dict
+ "method" "post"
+ "body" `{"complete": true}`
+ "headers" (dict "Content-Type" "application/json")
+}}
+{{ $resource := resources.GetRemote $url $opts }}
+```
+
+## Remote data
+
+When retrieving remote data, use the [`transform.Unmarshal`] function to [unmarshal] the response.
+
+[`transform.Unmarshal`]: /functions/transform/unmarshal
+[unmarshal]: /getting-started/glossary/#unmarshal
+
+```go-html-template
+{{ $data := "" }}
+{{ $url := "https://example.org/books.json" }}
+{{ with resources.GetRemote $url }}
+ {{ with .Err }}
+ {{ errorf "%s" . }}
+ {{ else }}
+ {{ $data = . | transform.Unmarshal }}
+ {{ end }}
+{{ else }}
+ {{ errorf "Unable to get remote resource %q" $url }}
+{{ end }}
+```
+
+## Error handling
+
+The [`Err`] method on a resource returned by the `resources.GetRemote` function returns an error message if the HTTP request fails, else nil. If you do not handle the error yourself, Hugo will fail the build.
+
+[`Err`]: /methods/resource/err
+
+```go-html-template
+{{ $url := "https://broken-example.org/images/a.jpg" }}
+{{ with resources.GetRemote $url }}
+ {{ with .Err }}
+ {{ errorf "%s" . }}
+ {{ else }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+ {{ end }}
+{{ else }}
+ {{ errorf "Unable to get remote resource %q" $url }}
+{{ end }}
+```
+
+To log an error as a warning instead of an error:
+
+```go-html-template
+{{ $url := "https://broken-example.org/images/a.jpg" }}
+{{ with resources.GetRemote $url }}
+ {{ with .Err }}
+ {{ warnf "%s" . }}
+ {{ else }}
+ <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+ {{ end }}
+{{ else }}
+ {{ errorf "Unable to get remote resource %q" $url }}
+{{ end }}
+```
+
+## HTTP response
+
+The [`Data`] method on a resource returned by the `resources.GetRemote` function returns information from the HTTP response.
+
+[`Data`]: /methods/resource/data
+
+```go-html-template
+{{ $url := "https://example.org/images/a.jpg" }}
+{{ with resources.GetRemote $url }}
+ {{ with .Err }}
+ {{ errorf "%s" . }}
+ {{ else }}
+ {{ with .Data }}
+ {{ .ContentLength }} → 42764
+ {{ .ContentType }} → image/jpeg
+ {{ .Status }} → 200 OK
+ {{ .StatusCode }} → 200
+ {{ .TransferEncoding }} → []
+ {{ end }}
+ {{ end }}
+{{ else }}
+ {{ errorf "Unable to get remote resource %q" $url }}
+{{ end }}
+```
+
+ContentLength
+: (`int`) The content length in bytes.
+
+ContentType
+: (`string`) The content type.
+
+Status
+: (`string`) The HTTP status text.
+
+StatusCode
+: (`int`) The HTTP status code.
+
+TransferEncoding
+: (`string`) The transfer encoding.
+
+## Caching
+
+Resources returned from `resources.GetRemote` are cached to disk. See [configure file caches] for details.
+
+By default, Hugo derives the cache key from the arguments passed to the function, the URL and the options map, if any.
+
+Override the cache key by setting a `key` in the options map. Use this approach to have more control over how often Hugo fetches a remote resource.
+
+```go-html-template
+{{ $url := "https://example.org/images/a.jpg" }}
+{{ $cacheKey := print $url (now.Format "2006-01-02") }}
+{{ $resource := resource.GetRemote $url (dict "key" $cacheKey) }}
+```
+
+[configure file caches]: /getting-started/configuration/#configure-file-caches
++
++## Security
++
++To protect against malicious intent, the `resources.GetRemote` function inspects the server response including:
++
++- The [Content-Type] in the response header
++- The file extension, if any
++- The content itself
++
++If Hugo is unable to resolve the media type to an entry in its [allowlist], the function throws an error:
++
++```text
++ERROR error calling resources.GetRemote: failed to resolve media type...
++```
++
++For example, you will see the error above if you attempt to download an executable.
++
++Although the allowlist contains entries for common media types, you may encounter situations where Hugo is unable to resolve the media type of a file that you know to be safe. In these situations, edit your site configuration to add the media type to the allowlist. For example:
++
++```text
++[security.http]
++mediaTypes=['application/vnd\.api\+json']
++```
++
++Note that the entry above is:
++
++- An _addition_ to the allowlist; it does not _replace_ the allowlist
++- An array of regular expressions
++
++For example, to add two entries to the allowlist:
++
++```text
++[security.http]
++mediaTypes=['application/vnd\.api\+json','image/avif']
++```
++
++[allowlist]: https://en.wikipedia.org/wiki/Whitelist
++[Content-Type]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Type
--- /dev/null
+---
+title: Glossary of terms
+description: Terms commonly used throughout the documentation.
+categories: [getting started]
+keywords: [glossary]
+menu:
+ docs:
+ parent: getting-started
+ weight: 60
+weight: 60
+# Use level 6 headings for each term in the glossary.
+---
+
++[A](#action)
++[B](#bool)
++[C](#cache)
++[D](#default-sort-order)
++[E](#environment)
++[F](#field)
++[G](#global-resource)
++[I](#identifier)
++[K](#kind)
++[L](#layout)
++[M](#map)
++[O](#object)
++[P](#page-bundle)
++[R](#regular-page)
++[S](#scalar)
++[T](#taxonomic-weight)
++[U](#unmarshal)
++[V](#variable)
++[W](#walk)
++
+###### action
+
+See [template action](#template-action).
+
+###### archetype
+
+A template for new content. See [details](/content-management/archetypes/).
+
+###### argument
+
+A [scalar](#scalar), [array](#array), [slice](#slice), [map](#map), or [object](#object) passed to a [function](#function), [method](#method), or [shortcode](#shortcode).
+
+###### array
+
+A numbered sequence of elements. Unlike Go's [slice](#slice) data type, an array has a fixed length. [Elements](#element) within an array can be [scalars](#scalar), slices, [maps](#map), pages, or other arrays. See the [Go documentation](https://go.dev/ref/spec#Array_types) for details.
+
+###### bool
+
+See [boolean](#boolean).
+
+###### boolean
+
+A data type with two possible values, either `true` or `false`.
+
+###### branch bundle
+
+A [page bundle](#page-bundle) with an _index.md file and zero or more [resources](#resource). Analogous to a physical branch, a branch bundle may have descendants including regular pages, [leaf bundles](/getting-started/glossary/#leaf-bundle), and other branch bundles. See [details](/content-management/page-bundles/).
+
+###### build
+
+To generate a static site that includes HTML files and assets such as images, CSS, and JavaScript. The build process includes rendering and resource transformations.
+
+###### bundle
+
+See [page bundle](#page-bundle).
+
+###### cache
+
+A software component that stores data so that future requests for the same data are faster.
+
+###### chain
+
+Within a template, to connect one or more [identifiers](#identifier) with a dot. An identifier can represent a method, object, or field. For example, `.Site.Params.author.name` or `.Date.UTC.Hour`.
+
+###### collection
+
+An [array](#array), [slice](#slice), or [map](#map).
+
+###### content format
+
+A markup language for creating content. Typically markdown, but may also be HTML, AsciiDoc, Org, Pandoc, or reStructuredText. See [details](/content-management/formats/).
+
+###### content type
+
+A classification of content inferred from the top-level directory name or the `type` set in [front matter](#front-matter). Pages in the root of the content directory, including the home page, are of type "page". Accessed via `.Page.Type` in [templates](#template). See [details](/content-management/types/).
+
+###### content view
+
+A template called with the `.Page.Render` method. See [details](/templates/views/).
+
+###### context
+
+Represented by a dot "." within a [template action](#template-action), context is the current location in a data structure. For example, while iterating over a [collection](#collection) of pages, the context within each iteration is the page's data structure. The context received by each template depends on template type and/or how it was called. See [details](/templates/introduction/#the-dot).
+
+###### default sort order
+
+The default sort order for page collections. Hugo sorts by [weight](#weight), then by date (descending), then by link title, and then by file path.
+
+###### element
+
+A member of a slice or array.
+
+###### environment
+
+Typically one of `development`, `staging`, or `production`, each environment may exhibit different behavior depending on configuration and template logic. For example, in a production environment you might minify and fingerprint CSS, but that probably doesn't make sense in a development environment.
+
+When running the built-in development server with the `hugo server` command, the environment is set to `development`. When building your site with the `hugo` command, the environment is set to `production`. To override the environment value, use the `--environment` command line flag.
+
+To determine the current environment within a template, use the [`hugo.Environment`] function.
+
+[`hugo.Environment`]: /functions/hugo/environment
+
+###### field
+
+A predefined key/value pair in front matter such as `date` or `title`. See also [parameter](#parameter).
+
+
+###### flag
+
+An option passed to a command-line program, beginning with one or two hyphens. See [details](/commands/hugo/).
+
+###### float
+
+See [floating point](#floating-point).
+
+###### floating point
+
+A numeric data type with a fractional component. For example, `3.14159`.
+
+###### fragment
+
+The final segment of a URL, beginning with a hash (`#`) mark, that references an `id` attribute of an HTML element on the page.
+
+###### front matter
+
+Metadata at the beginning of each content page, separated from the content by format-specific delimiters. See [details](/content-management/front-matter/).
+
+###### function
+
+Used within a [template action](#template-action), a function takes one or more [arguments](#argument) and returns a value. Unlike [methods](#method), functions are not associated with an [object](#object). See [details](/functions/).
+
+###### global resource
+
+A file within the assets directory, or within any directory [mounted](/hugo-modules/configuration/#module-configuration-mounts) to the assets directory. Capture one or more global resources using the [`resources.Get`], [`resources.GetMatch`], [`resources.Match`], or [`resources.ByType`] functions.
+
+[`resources.Get`]: /functions/resources/get
+[`resources.GetMatch`]: /functions/resources/getmatch
+[`resources.Match`]: /functions/resources/match
+[`resources.ByType`]: /functions/resources/byType
+
+###### identifier
+
+A string that represents a variable, method, object, or field. It must conform to Go's [language specification](https://go.dev/ref/spec#Identifiers), beginning with a letter or underscore, followed by zero or more letters, digits, or underscores.
+
+###### int
+
+See [integer](#integer).
+
+###### integer
+
+A numeric data type without a fractional component. For example, `42`.
+
+###### internationalization
+
+Software design and development efforts that enable [localization](#localization). See the [W3C definition](https://www.w3.org/International/questions/qa-i18n). Abbreviated i18n.
+
+###### interval
+
+An [interval](https://en.wikipedia.org/wiki/Interval_(mathematics)) is a range of numbers between two endpoints: closed, open, or half-open.
+
+- A _closed_ interval, denoted by brackets, includes its endpoints. For example, [0, 1] is the interval where `0 <= x <= 1`.
+
+- An _open_ interval, denoted by parentheses, excludes its endpoints. For example, (0, 1) is the interval where `0 < x < 1`.
+
+- A _half-open_ interval includes only one of its endpoints. For example, (0, 1] is the _left-open_ interval where `0 < x <= 1`, while [0, 1) is the _right-open_ interval where `0 <= x < 1`.
+
+###### kind
+
+See [page kind](#page-kind).
+
+###### layout
+
+See [template](#template).
+
+###### leaf bundle
+
+A [page bundle](#page-bundle) with an index.md file and zero or more [resources](#resource). Analogous to a physical leaf, a leaf bundle is at the end of a branch. Hugo ignores content (but not resources) beneath the leaf bundle. See [details](/content-management/page-bundles/).
+
+###### list page
+
+Any [page kind](#page-kind) that receives a page [collection](#collection) in [context](#context). This includes the home page, [section pages](#section-page), [taxonomy pages](#taxonomy-page), and [term pages](#term-page).
+
+###### localization
+
+Adaptation of a site to meet language and regional requirements. This includes translations, language-specific media, date and currency formats, etc. See [details](/content-management/multilingual/) and the [W3C definition](https://www.w3.org/International/questions/qa-i18n). Abbreviated l10n.
+
+###### map
+
+An unordered group of elements, each indexed by a unique key. See the [Go documentation](https://go.dev/ref/spec#Map_types) for details.
+
+###### markdown attribute
+
+A list of attributes, containing one or more key/value pairs, separated by spaces or commas, and wrapped by braces. Apply markdown attributes to images and block-level elements including blockquotes, fenced code blocks, headings, horizontal rules, lists, paragraphs, and tables. See [details](/getting-started/configuration-markup/#goldmark).
+
+###### marshal
+
+To transform a data structure into a serialized object. For example, transforming a [map](#map) into a JSON string. See [unmarshal](#unmarshal).
+
+###### method
+
+Used within a [template action](#template-action) and associated with an [object](#object), a method takes zero or more [arguments](#argument) and either returns a value or performs an action. For example, `.IsHome` is a method on the `.Page` object which returns `true` if the current page is the home page. See also [function](#function).
+
+###### module
+
+Like a [theme](#theme), a module is a packaged combination of [archetypes](#archetype), assets, content, data, [templates](#template), translation tables, static files, or configuration settings. A module may serve as the basis for a new site, or to augment an existing site. See [details](/hugo-modules/).
+
+###### object
+
+A data structure with or without associated [methods](#method).
+
+###### ordered taxonomy
+
+Created by invoking the [`Alphabetical`] or [`ByCount`] method on a [taxonomy object](#taxonomy-object), which is a [map](#map), an ordered taxonomy is a [slice](#slice), where each element is an object that contains the [term](#term) and a slice of its [weighted pages](#weighted-page).
+
+[`Alphabetical`]: /methods/taxonomy/alphabetical
+[`ByCount`]: /methods/taxonomy/bycount
+
+###### output format
+
+{{% include "methods/page/_common/output-format-definition.md" %}}
+
+###### page bundle
+
+A directory that encapsulates both content and associated [resources](#resource). There are two types of page bundles: [leaf bundles](#leaf-bundle) and [branch bundles](#branch-bundle). See [details](/content-management/page-bundles/).
+
+###### page collection
+
+A slice of page objects.
+
+###### page kind
+
+A classification of pages, one of `home`, `page`, `section`, `taxonomy`, or `term`. See [details](/templates/section-templates/#page-kinds).
+
+Note that there are also `RSS`, `sitemap`, `robotsTXT`, and `404` page kinds, but these are only available during the rendering of each of these respective page's kind and therefore *not* available in any of the `Pages` collections.
+
+###### page resource
+
+A file within a [page bundle](#page-bundle). Capture one or more page resources using any of the [`Resources`] methods on a `Page` object.
+
+[`Resources`]: /methods/page/resources/#methods
+
+###### pager
+
+Created during [pagination](#pagination), a pager contains a subset of a section list, and navigation links to other pagers.
+
+###### paginate
+
+To split a [section](#section) list into two or more [pagers](#pager) See [details](/templates/pagination/).
+
+###### pagination
+
+The process of [paginating](#paginate) a [section](#section) list.
+
+###### parameter
+
+Typically, a user-defined key/value pair at the site or page level, but may also refer to a configuration setting or an [argument](#argument). See also [field](#field).
+
+###### partial
+
+A [template](#template) called from any other template including [shortcodes](#shortcode), [render hooks](#render-hook), and other partials. A partial either renders something or returns something. A partial can also call itself, for example, to [walk](#walk) a data structure.
+
+###### permalink
+
+The absolute URL of a published resource or a rendered page, including scheme and host.
+
+###### pipe
+
+See [pipeline](#pipeline).
+
+###### pipeline
+
+Within a [template action](#template-action), a pipeline is a possibly chained sequence of values, [function](#function) calls, or [method](#method) calls. Functions and methods in the pipeline may take multiple [arguments](#argument).
+
+A pipeline may be *chained* by separating a sequence of commands with pipeline characters "|". In a chained pipeline, the result of each command is passed as the last argument to the following command. The output of the final command in the pipeline is the value of the pipeline. See the [Go documentation](https://pkg.go.dev/text/template#hdr-Pipelines) for details.
+
+###### publish
+
+See [build](#build).
+
+###### regular page
+
+Content with the "page" [page kind](#page-kind). See also [section page](#section-page).
+
+###### relative permalink
+
+The host-relative URL of a published resource or a rendered page.
+
+###### render hook
+
+A [template](#template) that overrides standard markdown rendering. See [details](/templates/render-hooks/).
+
+###### remote resource
+
+A file on a remote server, accessible via HTTP or HTTPS with the [`resources.GetRemote`](/functions/resources/getremote) function.
+
+###### resource
+
+Any file consumed by the build process to augment or generate content, structure, behavior, or presentation. For example: images, videos, content snippets, CSS, Sass, JavaScript, and data.
+
+Hugo supports three types of resources: [global](#global-resource), [page](#page-resource), and [remote](#remote-resource)
+
+###### scalar
+
+A single value, one of [string](#string), [integer](#integer), [floating point](#floating-point), or [boolean](#boolean).
+
+###### scratch pad
+
+Conceptually, a [map](#map) with [methods](#method) to set, get, update, and delete values. Attach the data structure to a `Page` object using the [`Scratch`] or [`Store`] methods, or created a locally scoped scratch pad using the [`newScratch`] function.
+
+[`Scratch`]: /methods/page/scratch
+[`Store`]: /methods/page/store
+[`newScratch`]: /functions/collections/newscratch
+
+###### section
+
+A top-level content directory, or any content directory with an _index.md file. A content directory with an _index.md file is also known as a [branch bundle](/getting-started/glossary/#branch-bundle). Section templates receive one or more page [collections](#collection) in [context](#context). See [details](/content-management/sections/).
+
+###### section page
+
+Content with the "section" [page kind](#page-kind). Typically a listing of [regular pages](#regular-page) and/or [section pages](#section-page) within the current [section](#section). See also [regular page](#regular-page).
+
+###### shortcode
+
+A [template](#template) called from within markdown, taking zero or more [arguments](#argument). See [details](/content-management/shortcodes/).
+
+###### slice
+
+A numbered sequence of elements. Unlike Go's [array](#array) data type, slices are dynamically sized. [Elements](#element) within a slice can be [scalars](#scalar), [arrays](#array), [maps](#map), pages, or other slices. See the [Go documentation](https://go.dev/ref/spec#Slice_types) for details.
+
+###### string
+
+A sequence of bytes. For example, `"What is 6 times 7?"` .
+
+###### taxonomic weight
+
+Defined in front matter and unique to each taxonomy, this [weight](#weight) determines the sort order of page collections contained within a [taxonomy object](#taxonomy-object). See [details](/templates/taxonomy-templates/#assign-weight).
+
+###### taxonomy
+
+A group of related [terms](#term) used to classify content. For example, a "colors" taxonomy might include the terms "red", "green", and "blue". See [details](/content-management/taxonomies/).
+
+###### taxonomy object
+
+A [map](#map) of [terms](#term) and the [weighted pages](#weighted-page) associated with each term.
+
+###### taxonomy page
+
+Content with the "taxonomy" [page kind](#page-kind). Typically a listing of [terms](#term) within a given [taxonomy](#taxonomy).
+
+###### template
+
+A file with [template actions](#template-action), located within the layouts directory of a project, theme, or module. See [details](/templates/).
+
+###### template action
+
+A data evaluation or control structure within a [template](#template), delimited by "{{" and "}}". See the [Go documentation](https://pkg.go.dev/text/template#hdr-Actions) for details.
+
+###### term
+
+A member of a [taxonomy](#taxonomy), used to classify content. See [details](/content-management/taxonomies/).
+
+###### term page
+
+Content with the "term" [page kind](#page-kind). Typically a listing of [regular pages](#regular-page) and [section pages](#section-page) with a given [term](#term).
+
+###### theme
+
+A packaged combination of [archetypes](#archetype), assets, content, data, [templates](#template), translation tables, static files, or configuration settings. A theme may serve as the basis for a new site, or to augment an existing site. See also [module](#module).
+
+###### token
+
+An identifier within a format string, beginning with a colon and replaced with a value when rendered. For example, use tokens in format strings for both [permalinks](/content-management/urls/#permalinks) and [dates](/functions/time/format/#localization).
+
+###### type
+
+See [content type](#content-type).
+
+###### unmarshal
+
+To transform a serialized object into a data structure. For example, transforming a JSON file into a [map](#map) that you can access within a template. See [marshal](#marshal).
+
+###### variable
+
+A user-defined [identifier](#identifier) prefaced with a `$` symbol, representing a value of any data type, initialized or assigned within a [template action](#template-action). For example, `$foo` and `$bar` are variables.
+
+###### walk
+
+To recursively traverse a nested data structure. For example, rendering a multilevel menu.
+
+###### weight
+
+Used to position an element within a collection sorted by weight. Assign weights using non-zero integers. Lighter items float to the top, while heavier items sink to the bottom. Unweighted or zero-weighted elements are placed at the end of the collection. Weights are typically assigned to pages, menu entries, languages, and output formats.
+
+###### weighted page
+
+Contained within a [taxonomy object](#taxonomy-object), a weighted page is a [map](#map) with two elements: a `Page` object, and its [taxonomic weight](#taxonomic-weight) as defined in front matter. Access the elements using the `Page` and `Weight` keys.
--- /dev/null
- [params.author]
+---
+title: Params
+description: Returns a map of custom parameters as defined in the front matter of the given page.
+categories: []
+keywords: []
+action:
+ related:
+ - functions/collections/IndexFunction
+ - methods/site/Params
+ - methods/page/Param
+ returnType: maps.Params
+ signatures: [PAGE.Params]
+---
+
+With this front matter:
+
+{{< code-toggle file=content/news/annual-conference.md >}}
+title = 'Annual conference'
+date = 2023-10-17T15:11:37-07:00
+display_related = true
++[author]
+ email = 'jsmith@example.org'
+ name = 'John Smith'
+{{< /code-toggle >}}
+
+The `title` and `date` fields are standard parameters---the other fields are user-defined.
+
+Access the custom parameters by [chaining] the [identifiers]:
+
+```go-html-template
+{{ .Params.display_related }} → true
+{{ .Params.author.name }} → John Smith
+```
+
+In the template example above, each of the keys is a valid identifier. For example, none of the keys contains a hyphen. To access a key that is not a valid identifier, use the [`index`] function:
+
+```go-html-template
+{{ index .Params "key-with-hyphens" }} → 2023
+```
+
+[`index`]: /functions/collections/indexfunction
+[chaining]: /getting-started/glossary/#chain
+[identifiers]: /getting-started/glossary/#identifier
--- /dev/null
- - methods/time/After
+---
+title: After
+description: Reports whether TIME1 is after TIME2.
+categories: []
+keywords: []
+action:
+ related:
+ - methods/time/Before
++ - methods/time/Equal
+ - functions/time/AsTime
+ returnType: bool
+ signatures: [TIME1.After TIME2]
+---
+
+```go-html-template
+{{ $t1 := time.AsTime "2023-01-01T17:00:00-08:00" }}
+{{ $t2 := time.AsTime "2010-01-01T17:00:00-08:00" }}
+
+{{ $t1.After $t2 }} → true
+```
--- /dev/null
- name
- : the output format identifier. This is used to define what output format(s) you want for your pages.
-
+---
+title: Custom output formats
+description: Hugo can output content in multiple formats, including calendar events, e-book formats, Google AMP, and JSON search indexes, or any custom text format.
+categories: [templates,fundamentals]
+keywords: ["amp", "outputs", "rss"]
+menu:
+ docs:
+ parent: templates
+ weight: 210
+weight: 210
+toc: true
+aliases: [/templates/outputs/,/extras/output-formats/,/content-management/custom-outputs/]
+---
+
+This page describes how to properly configure your site with the media types and output formats, as well as where to create your templates for your custom outputs.
+
+## Media types
+
+A [media type] (formerly known as a MIME type) is a two-part identifier for file formats and format contents transmitted on the internet.
+
+This is the full set of built-in media types in Hugo:
+
+{{< datatable "config" "mediaTypes" "_key" "suffixes" >}}
+
+**Note:**
+
+- It is possible to add custom media types or change the defaults; e.g., if you want to change the suffix for `text/html` to `asp`.
+- `Suffixes` are the values that will be used for URLs and file names for that media type in Hugo.
+- The `Type` is the identifier that must be used when defining new/custom `Output Formats` (see below).
+- The full set of media types will be registered in Hugo's built-in development server to make sure they are recognized by the browser.
+
+To add or modify a media type, define it in a `mediaTypes` section in your [site configuration], either for all sites or for a given language.
+
+{{< code-toggle file=hugo >}}
+[mediaTypes]
+ [mediaTypes."text/enriched"]
+ suffixes = ["enr"]
+ [mediaTypes."text/html"]
+ suffixes = ["asp"]
+{{</ code-toggle >}}
+
+The above example adds one new media type, `text/enriched`, and changes the suffix for the built-in `text/html` media type.
+
+**Note:** these media types are configured for **your output formats**. If you want to redefine one of Hugo's default output formats (e.g. `HTML`), you also need to redefine the media type. So, if you want to change the suffix of the `HTML` output format from `html` (default) to `htm`:
+
+{{< code-toggle file=hugo >}}
+[mediaTypes]
+ [mediaTypes."text/html"]
+ suffixes = ["htm"]
+
+[outputFormats]
+ [outputFormats.html]
+ mediaType = "text/html"
+{{</ code-toggle >}}
+
+{{% note %}}
+For the above to work, you also need to add an `outputs` definition in your site configuration.
+{{% /note %}}
+
+## Output format definitions
+
+Given a media type and some additional configuration, you get an **Output Format**.
+
+This is the full set of Hugo's built-in output formats:
+
+{{< datatable "config" "outputFormats" "name" "mediaType" "path" "baseName" "rel" "protocol" "isPlainText" "isHTML" "noUgly" "permalinkable" >}}
+
+- A page can be output in as many output formats as you want, and you can have an infinite amount of output formats defined **as long as they resolve to a unique path on the file system**. In the above table, the best example of this is `amp` vs. `html`. `amp` has the value `amp` for `path` so it doesn't overwrite the `html` version; e.g. we can now have both `/index.html` and `/amp/index.html`.
+- The `mediaType` must match a defined media type.
+- You can define new output formats or redefine built-in output formats; e.g., if you want to put `amp` pages in a different path.
+
+To add or modify an output format, define it in an `outputFormats` section in your site's [configuration file](/getting-started/configuration/), either for all sites or for a given language.
+
+{{< code-toggle file=hugo >}}
+[outputFormats.MyEnrichedFormat]
+mediaType = "text/enriched"
+baseName = "myindex"
+isPlainText = true
+protocol = "bep://"
+{{</ code-toggle >}}
+
+The above example is fictional, but if used for the homepage on a site with `baseURL` `https://example.org`, it will produce a plain text homepage with the URL `bep://example.org/myindex.enr`.
+
+### Configure output formats
+
+The following is the full list of configuration options for output formats and their default values:
+
+mediaType
+: this must match the `Type` of a defined media type.
+
+path
+: sub path to save the output files.
+
+baseName
+: the base file name for the list file names (homepage, etc.). **Default:** `index`.
+
+rel
+: can be used to create `rel` values in `link` tags. **Default:** `alternate`.
+
+protocol
+: will replace the "http://" or "https://" in your `baseURL` for this output format.
+
+isPlainText
+: use Go's plain text templates parser for the templates. **Default:** `false`.
+
+isHTML
+: used in situations only relevant for `HTML`-type formats; e.g., page aliases. **Default:** `false`.
+
+noUgly
+: used to turn off ugly URLs If `uglyURLs` is set to `true` in your site. **Default:** `false`.
+
+notAlternative
+: enable if it doesn't make sense to include this format in an `AlternativeOutputFormats` format listing on `Page` (e.g., with `CSS`). Note that we use the term _alternative_ and not _alternate_ here, as it does not necessarily replace the other format. **Default:** `false`.
+
+permalinkable
+: make `.Permalink` and `.RelPermalink` return the rendering Output Format rather than main ([see below](#link-to-output-formats)). This is enabled by default for `HTML` and `AMP`. **Default:** `false`.
+
+weight
+: Setting this to a non-zero value will be used as the first sort criteria.
+
+## Output formats for pages
+
+A `Page` in Hugo can be rendered to multiple _output formats_ on the file
+system.
+
+### Default output formats
+
+Every `Page` has a [`Kind`][page_kinds] attribute, and the default Output
+Formats are set based on that.
+
+{{< code-toggle config=outputs />}}
+
+### Customizing output formats
+
+This can be changed by defining an `outputs` list of output formats in either
+the `Page` front matter or in the site configuration (either for all sites or
+per language).
+
+Example from site configuration file:
+
+{{< code-toggle file=hugo >}}
+[outputs]
+ home = ["html", "amp", "rss"]
+ page = ["html"]
+{{</ code-toggle >}}
+
+Note that in the above examples, the _output formats_ for `section`,
+`taxonomy` and `term` will stay at their default value `['html','rss']`.
+
+* The `outputs` definition is per page [`Kind`][page_kinds].
+* The names (e.g. `html`, `amp`) must match the `name` of a defined output format, and can be overridden per page in front matter.
+
+The following is an example of front matter in a content file that defines output formats for the rendered `Page`:
+
+{{< code-toggle file=content/example.md fm=true >}}
+title: Example
+outputs:
+- html
+- amp
+- json
+{{< /code-toggle >}}
+
+## List output formats
+
+Each `Page` has both an `.OutputFormats` (all formats, including the current) and an `.AlternativeOutputFormats` variable, the latter of which is useful for creating a `link rel` list in your site's `<head>`:
+
+```go-html-template
+{{ range .AlternativeOutputFormats -}}
+ <link rel="{{ .Rel }}" type="{{ .MediaType.Type }}" href="{{ .Permalink | safeURL }}">
+{{ end }}
+```
+
+## Link to output formats
+
+`.Permalink` and `.RelPermalink` on `Page` will return the first output format defined for that page (usually `HTML` if nothing else is defined). This is regardless of the template file they are being called from.
+
+__from `single.json.json`:__
+```go-html-template
+{{ .RelPermalink }} → /that-page/
+{{ with .OutputFormats.Get "json" }}
+ {{ .RelPermalink }} → /that-page/index.json
+{{ end }}
+```
+
+In order for them to return the output format of the current template file instead, the given output format should have its `permalinkable` setting set to true.
+
+**Same template file as above with json output format's `permalinkable` set to true:**
+
+```go-html-template
+{{ .RelPermalink }} → /that-page/index.json
+{{ with .OutputFormats.Get "html" }}
+ {{ .RelPermalink }} → /that-page/
+{{ end }}
+```
+
+From content files, you can use the [`ref` or `relref` shortcodes](/content-management/shortcodes/#ref-and-relref):
+
+```go-html-template
+[Neat]({{</* ref "blog/neat.md" "amp" */>}})
+[Who]({{</* relref "about.md#who" "amp" */>}})
+```
+
+## Templates for your output formats
+
+Each output format requires a corresponding template conforming to the [template lookup order](/templates/lookup-order/). Hugo considers both output format and suffix when selecting a template.
+
+For example, to generate a JSON file for the home page, the template with highest specificity is `layouts/index.json.json`.
+
+Hugo will now also detect the media type and output format of partials, if possible, and use that information to decide if the partial should be parsed as a plain text template or not.
+
+Hugo will look for the name given, so you can name it whatever you want. But if you want it treated as plain text, you should use the file suffix and, if needed, the name of the Output Format. The pattern is as follows:
+
+```go-html-template
+[partial name].[OutputFormat].[suffix]
+```
+
+The partial below is a plain text template . The output format is `csv`, and since this is the only output format with the suffix `csv`, we don't need to include the output format `name`):
+
+```go-html-template
+{{ partial "mytextpartial.csv" . }}
+```
+
+[base]: /templates/base/
+[site configuration]: /getting-started/configuration/
+[lookup order]: /templates/lookup-order/
+[media type]: https://en.wikipedia.org/wiki/Media_type
+[partials]: /templates/partials/
+[page_kinds]: /templates/section-templates/#page-kinds
--- /dev/null
- <h{{ .Level }} id="{{ .Anchor | safeURL }}">{{ .Text | safeHTML }} <a href="#{{ .Anchor | safeURL }}">¶</a></h{{ .Level }}>
+---
+title: Markdown render hooks
+linkTitle: Render hooks
+description: Render Hooks allow custom templates to override markdown rendering functionality.
+categories: [templates]
+keywords: [markdown]
+toc: true
+menu:
+ docs:
+ parent: templates
+ weight: 200
+weight: 200
+---
+
+Note that this is only supported with the [Goldmark](/getting-started/configuration-markup#goldmark) renderer.
+
+You can override certain parts of the default Markdown rendering to HTML by creating templates with base names `render-{kind}` in `layouts/_default/_markup`.
+
+You can also create type/section specific hooks in `layouts/[type/section]/_markup`, e.g.: `layouts/blog/_markup`.
+
+The hook kinds currently supported are:
+
+* `image`
+* `link`
+* `heading`
+* `codeblock`{{< new-in 0.93.0 >}}
+
+You can define [Output-Format-](/templates/output-formats) and [language-](/content-management/multilingual/)specific templates if needed. Your `layouts` folder may look like this:
+
+```text
+layouts/
+└── _default/
+ └── _markup/
+ ├── render-codeblock-bash.html
+ ├── render-codeblock.html
+ ├── render-heading.html
+ ├── render-image.html
+ ├── render-image.rss.xml
+ └── render-link.html
+```
+
+Some use cases for the above:
+
+* Resolve link references using `.GetPage`. This would make links portable as you could translate `./my-post.md` (and similar constructs that would work on GitHub) into `/blog/2019/01/01/my-post/` etc.
+* Add `target=_blank` to external links.
+* Resolve and [process](/content-management/image-processing/) images.
+* Add [header links](https://remysharp.com/2014/08/08/automatic-permalinks-for-blog-posts).
+
+## Render hooks for headings, links and images
+
+### Context passed to `render-link` and `render-image`
+
+The `render-link` and `render-image` templates will receive this context:
+
+Page
+: The [Page](/variables/page/) being rendered.
+
+Destination
+: The URL.
+
+Title
+: The title attribute.
+
+Text
+: The rendered (HTML) link text.
+
+PlainText
+: The plain variant of the above.
+
+### Context passed to `render-heading`
+
+The `render-heading` template will receive this context:
+
+Page
+: The [Page](/variables/page/) being rendered.
+
+Level
+: The header level (1--6)
+
+Anchor
+: An auto-generated html id unique to the header within the page
+
+Text
+: The rendered (HTML) text.
+
+PlainText
+: The plain variant of the above.
+
+Attributes (map)
+: A map of attributes (e.g. `id`, `class`). Note that this will currently always be empty for links.
+
+The `render-image` templates will also receive:
+
+IsBlock {{< new-in 0.108.0 >}}
+: Returns true if this is a standalone image and the configuration option [markup.goldmark.parser.wrapStandAloneImageWithinParagraph](/getting-started/configuration-markup/#goldmark) is disabled.
+
+Ordinal {{< new-in 0.108.0 >}}
+: Zero-based ordinal for all the images in the current document.
+
+### Link with title markdown example
+
+```md
+[Text](https://www.gohugo.io "Title")
+```
+
+Here is a code example for how the render-link.html template could look:
+
+{{< code file=layouts/_default/_markup/render-link.html >}}
+<a href="{{ .Destination | safeURL }}"{{ with .Title }} title="{{ . }}"{{ end }}{{ if strings.HasPrefix .Destination "http" }} target="_blank" rel="noopener"{{ end }}>{{ .Text | safeHTML }}</a>
+{{< /code >}}
+
+### Image markdown example
+
+```md
+
+```
+
+Here is a code example for how the render-image.html template could look:
+
+{{< code file=layouts/_default/_markup/render-image.html >}}
+<p class="md__image">
+ <img src="{{ .Destination | safeURL }}" alt="{{ .Text }}" {{ with .Title }} title="{{ . }}"{{ end }} />
+</p>
+{{< /code >}}
+
+### Heading link example
+
+Given this template file
+
+{{< code file=layouts/_default/_markup/render-heading.html >}}
++<h{{ .Level }} id="{{ .Anchor }}">{{ .Text | safeHTML }} <a href="#{{ .Anchor | safeURL }}">¶</a></h{{ .Level }}>
+{{< /code >}}
+
+And this markdown
+
+```md
+### Section A
+```
+
+The rendered html will be
+
+```html
+<h3 id="section-a">Section A <a href="#section-a">¶</a></h3>
+```
+
+## Render hooks for code blocks
+
+{{< new-in 0.93.0 >}}
+
+You can add a hook template for either all code blocks or for a specific type/language (`bash` in the example below):
+
+```goat { class="black f7" }
+layouts
+└── _default
+ └── _markup
+ └── render-codeblock.html
+ └── render-codeblock-bash.html
+```
+
+The default behavior for these code blocks is to do [Code Highlighting](/content-management/syntax-highlighting/#highlighting-in-code-fences), but since you can pass attributes to these code blocks, they can be used for almost anything. One example would be the built-in [GoAT Diagrams](/content-management/diagrams/#goat-diagrams-ascii) or this [Mermaid Diagram Code Block Hook](/content-management/diagrams/#mermaid-diagrams) example.
+
+The context (the ".") you receive in a code block template contains:
+
+Type (string)
+: The type of code block. This will be the programming language, e.g. `bash`, when doing code highlighting.
+
+Attributes (map)
+: Attributes passed in from Markdown (e.g. `{ attrName1=attrValue1 attrName2="attr Value 2" }`).
+
+Options (map)
+: Chroma highlighting processing options. This will only be filled if `Type` is a known [Chroma Lexer](/content-management/syntax-highlighting/#list-of-chroma-highlighting-languages).
+
+Inner (string)
+: The text between the code fences.
+
+Ordinal (integer)
+: Zero-based ordinal for all code blocks in the current document.
+
+Page
+: The owning `Page`.
+
+Position
+: Useful in error logging as it prints the file name and position (linenumber, column), e.g. `{{ errorf "error in code block: %s" .Position }}`.
--- /dev/null
- require github.com/gohugoio/gohugoioTheme v0.0.0-20240126181647-31e47d550511 // indirect
+module github.com/gohugoio/hugoDocs
+
+go 1.16
+
++require github.com/gohugoio/gohugoioTheme v0.0.0-20240201183016-8e648a3b5342 // indirect
--- /dev/null
- github.com/gohugoio/gohugoioTheme v0.0.0-20240126181647-31e47d550511 h1:dJLsByAuk9RnZmjL6QxQzHTJ63dr7Cwx6Dj8KAm7uEI=
- github.com/gohugoio/gohugoioTheme v0.0.0-20240126181647-31e47d550511/go.mod h1:GOYeAPQJ/ok8z7oz1cjfcSlsFpXrmx6VkzQ5RpnyhZM=
++github.com/gohugoio/gohugoioTheme v0.0.0-20240201183016-8e648a3b5342 h1:jQaO+i2osHeIZ+V7Dvo7CPqN6jPwMRjt7b9QaX7HXE4=
++github.com/gohugoio/gohugoioTheme v0.0.0-20240201183016-8e648a3b5342/go.mod h1:GOYeAPQJ/ok8z7oz1cjfcSlsFpXrmx6VkzQ5RpnyhZM=
--- /dev/null
--- /dev/null
++<!doctype html>
++<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 />
++
++ <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>
++
++ <meta name="viewport" content="width=device-width,minimum-scale=1" />
++ {{ hugo.Generator }}
++
++ {{ 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 -}}
++
++ {{ $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" . -}}
++
++ {{ if hugo.IsProduction }}
++ {{ partial "gtag.html" . }}
++ {{ end }}
++
++ {{ $hasMath := .Param "math" }}
++ {{ if $hasMath }}
++ {{ partialCached "math.html" . }}
++ {{ end }}
++
++ </head>
++
++ <body
++ class="ma0 sans-serif bg-primary-color-light{{ with getenv "HUGO_ENV" }}
++ {{ . }}
++ {{ end }} {{ if $hasMath }}{{ print " dn" }}{{ end }}">
++ {{ partial "hooks/after-body-start.html" . }}
++ {{ 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.html" . }}
++
++ </body>
++</html>
--- /dev/null
--- /dev/null
++<script id="MathJax-script" async src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-chtml.js"></script>
++<script>
++ MathJax = {
++ tex: {
++ inlineMath: [['$', '$'], ['\\(', '\\)']], // inline
++ displayMath: [['$$', '$$'], ['\\[', '\\]']] // block
++ },
++ startup: {
++ pageReady: () => {
++ return MathJax.startup.defaultPageReady().then(() => {
++ document.body.classList.remove("dn");
++ });
++ }
++ }
++ };
++</script>
projects / brevno-suite / hugo / commitdiff