Centralize and elevate multilingual documentation

Partial implementaiton of gohugoio#1888

archetypes/default.md

@@ -0,0 +1,11 @@
+---
+title: {{ replace .File.ContentBaseName "-" " " | strings.FirstUpper }}
+description:
+categories: []
+keywords: []
+menu:
+  docs:
+    parent:
+    weight:
+weight:
+---

config/_default/menus/menus.en.toml

@@ -11,64 +11,70 @@ identifier = 'installation'
 pageRef = '/installation/'
 
 [[docs]]
-name = 'Getting started'
+name = 'Configuration'
 weight = 30
+identifier = 'configuration'
+pageRef = '/configuration/'
+
+[[docs]]
+name = 'Getting started'
+weight = 40
 identifier = 'getting-started'
 pageRef = '/getting-started/'
 
 [[docs]]
 name = 'Quick reference'
-weight = 40
+weight = 50
 identifier = 'quick-reference'
 pageRef = '/quick-reference/'
 post = 'break'
 
 [[docs]]
 name = 'Content management'
-weight = 50
+weight = 60
 identifier = 'content-management'
 post = 'expanded'
 pageRef = '/content-management/'
 
 [[docs]]
 name = 'Templates'
-weight = 60
+weight = 70
 identifier = 'templates'
 pageRef = '/templates/'
 
 [[docs]]
 name = 'Functions'
-weight = 70
+weight = 80
 identifier = 'functions'
 pageRef = '/functions/'
 
 [[docs]]
 name = 'Methods'
-weight = 80
+weight = 90
 identifier = 'methods'
 pageRef = '/methods/'
 
 [[docs]]
 name = 'Render hooks'
-weight = 90
+weight = 100
 identifier = 'render-hooks'
 pageRef = '/render-hooks/'
 
 [[docs]]
 name = 'Shortcodes'
-weight = 100
+weight = 110
 identifier = 'shortcodes'
 pageRef = '/shortcodes/'
 
 [[docs]]
 name = 'Hugo Modules'
-weight = 110
+weight = 120
 identifier = 'modules'
 pageRef = '/hugo-modules/'
 
 [[docs]]
 name = 'Hugo Pipes'
-weight = 120
+weight = 125
 identifier = 'hugo-pipes'
 pageRef = '/hugo-pipes/'
 

content/en/_common/cascade.md

@@ -0,0 +1,72 @@
+---
+_comment: Do not remove front matter.
+---
+
+## This is content/en/_common/cascade.md
+
+????
+
+## Cascade
+
+Any [node](g) can pass down to its descendants a set of front matter values.
+
+### Target specific pages
+
+The `cascade` block can be an array with an optional `_target` keyword, allowing you to target different page sets while cascading values.
+
+{{< code-toggle file=content/_index.md fm=true >}}
+title ="Home"
+[[cascade]]
+[cascade.params]
+background = "yosemite.jpg"
+[cascade._target]
+path="/articles/**"
+lang="en"
+kind="page"
+[[cascade]]
+[cascade.params]
+background = "goldenbridge.jpg"
+[cascade._target]
+kind="section"
+{{</ code-toggle >}}
+
+Use any combination of these keywords to target a set of pages:
+
+###### path {#cascade-path}
+
+(`string`) 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 {#cascade-kind}
+
+(`string`) A Glob pattern matching the Page's Kind(s), e.g. "{home,section}".
+
+###### lang {#cascade-lang}
+
+(`string`) A Glob pattern matching the Page's language, e.g. "{en,sv}".
+
+###### environment {#cascade-environment}
+
+(`string`) A Glob pattern matching the build environment, e.g. "{production,development}"
+
+Any of the above can be omitted.
+
+{{% note %}}
+With a multilingual site it may be more efficient to define the `cascade` values in your site configuration to avoid duplicating the `cascade` values on the section, taxonomy, or term page for each language.
+
+With a multilingual site, if you choose to define the `cascade` values in front matter, you must create a section, taxonomy, or term page for each language; the `lang` keyword is ignored.
+{{% /note %}}
+
+### Example
+
+{{< code-toggle file=content/posts/_index.md fm=true >}}
+date = 2024-02-01T21:25:36-08:00
+title = 'Posts'
+[cascade]
+  [cascade.params]
+    banner = 'images/typewriter.jpg'
+{{</ code-toggle >}}
+
+With the above example the posts 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.

content/en/_common/ref-links-config-behavior.md

@@ -0,0 +1,10 @@
+---
+_comment: Do not remove front matter.
+---
+
+By default, Hugo will throw an error and fail the build if it cannot resolve the path. You can change this to a warning in your site configuration, and specify a URL to return when the path cannot be resolved.
+
+{{< code-toggle file=hugo >}}
+refLinksErrorLevel = 'warning'
+refLinksNotFoundURL = '/some/other/url'
+{{< /code-toggle >}}

content/en/_common/syntax-highlighting-options.md

@@ -0,0 +1,81 @@
+---
+_comment: Do not remove front matter.
+---
+
+###### anchorLineNos
+
+(`bool`) Whether to render each line number as an HTML anchor element, setting the `id` attribute of the surrounding `span` element to the line number. Irrelevant if `lineNos` is `false`. Default is `false`.
+
+###### codeFences
+
+(`bool`) Whether to highlight fenced code blocks. Default is `true`.
+
+###### guessSyntax
+
+(`bool`) Whether to automatically detect the language if the `LANG` argument is blank or set to a language for which there is no corresponding [lexer](g). Falls back to a plain text lexer if unable to automatically detect the language. Default is `false`.
+
+{{% note %}}
+The Chroma syntax highlighter includes lexers for approximately 250 languages, but only 5 of these have implemented automatic language detection.
+{{% /note %}}
+
+###### hl_Lines
+
+(`string`) A space-delimited list of lines to emphasize within the highlighted code. To emphasize lines 2, 3, 4, and 7, set this value to `2-4 7`. This option is independent of the `lineNoStart` option.
+
+###### hl_inline
+
+(`bool`) Whether to render the highlighted code without a wrapping container. Default is `false`.
+
+###### lineAnchors
+
+(`string`) When rendering a line number as an HTML anchor element, prepend this value to the `id` attribute of the surrounding `span` element. This provides unique `id` attributes when a page contains two or more code blocks. Irrelevant if `lineNos` or `anchorLineNos` is `false`.
+
+###### lineNoStart
+
+(`int`) The number to display at the beginning of the first line. Irrelevant if `lineNos` is `false`. Default is `1`.
+
+###### lineNos
+
+(`bool`) Whether to display a number at the beginning of each line. Default is `false`.
+
+###### lineNumbersInTable
+
+(`bool`) Whether to render the highlighted code in an HTML table with two cells. The left table cell contains the line numbers, while the right table cell contains the code. Irrelevant if `lineNos` is `false`. Default is `true`.
+
+###### noClasses
+
+(`bool`) Whether to use inline CSS styles instead of an external CSS file. Default is `true`. To use an external CSS file, set this value to `false` and generate the CSS file from the command line:
+
+```text
+hugo gen chromastyles --style=monokai > syntax.css
+```
+
+###### style
+
+(`string`) The CSS styles to apply to the highlighted code. Case-sensitive. Default is `monokai`. See style galleries:
+
+- [Short snippets]
+- [Long snippets]
+
+[Short snippets]: https://xyproto.github.io/splash/docs/all.html
+[Long snippets]: https://xyproto.github.io/splash/docs/longer/all.html
+
+###### tabWidth
+
+(`int`) Substitute this number of spaces for each tab character in your highlighted code. Irrelevant if `noClasses` is `false`. Default is `4`.
+
+###### wrapperClass
+
+{{< new-in 0.140.2 />}}
+
+(`string`) The class or classes to use for the outermost element of the highlighted code. Default is `highlight`.
+
+{{% note %}}
+Instead of specifying both `lineNos` and `lineNumbersInTable`, you can use the following shorthand notation:
+
+lineNos=inline
+: equivalent to `lineNos=true` and `lineNumbersInTable=false`
+
+lineNos=table
+: equivalent to `lineNos=true` and `lineNumbersInTable=true`
+{{% /note %}}

content/en/about/features.md

@@ -118,7 +118,7 @@ toc: true
 [CommonMark]: https://spec.commonmark.org/current/
 [GitHub Flavored Markdown]: https://github.github.com/gfm/
 [Markdown attributes]: /content-management/markdown-attributes/
-[Markdown extensions]: /getting-started/configuration-markup/#goldmark-extensions
+[Markdown extensions]: /configuration/markup/#goldmark-extensions
 [Markdown render hooks]: /render-hooks/introduction/
 [Diagrams]: /content-management/diagrams/
 [Mathematics]: /content-management/mathematics/

content/en/about/security.md

@@ -69,4 +69,4 @@ This is why you sometimes need to use the _safe_ functions, such as `safeHTML`,
 There is one exception to the above, as noted in the documentation: If you enable inline shortcodes, you also say that the shortcodes and data handling in content files are trusted, as those macros are treated as pure text.
 It may be worth adding that Hugo is a static site generator with no concept of dynamic user input.
 
-For content, the default Markdown renderer is [configured](/getting-started/configuration-markup) to remove or escape potentially unsafe content. This behavior can be reconfigured if you trust your content.
+For content, the default Markdown renderer is [configured](/configuration/markup) to remove or escape potentially unsafe content. This behavior can be reconfigured if you trust your content.