content: Various dimension improvements

jmooring · jmooring · commit 12a9fe44d373 · 2026-02-21T12:52:14.000-08:00
diff --git a/content/en/configuration/languages.md b/content/en/configuration/languages.md
@@ -56,7 +56,7 @@ languageCode
   Access this value from a template using the [`Language.LanguageCode`][] method on a `Site` or `Page` object.
 
 languageDirection
-: (`string`) The language direction, either left-to-right (`ltr`) or right-to-left (`rtl`). Use this value in your templates with the global [`dir`][] HTML attribute. Access this value from a template using the [`Language.LanguageDirection`][] method on a `Site` or `Page` object.
+: (`string`) The language direction, either left-to-right (`ltr`) or right-to-left (`rtl`). Use this value in your templates with the global [`dir`][] HTML attribute. Access this value from a template using the [`Language.LanguageDirection`][] method on a `Site` or `Page` object. Default is `ltr`.
 
 languageName
 : (`string`) The language name, typically used when rendering a language switcher. Access this value from a template using the [`Language.LanguageName`][] method on a `Site` or `Page` object.
@@ -67,6 +67,10 @@ title
 weight
 : (`int`) The language [weight](g). When set to a non-zero value, this is the primary sort criteria for this language. Access this value from a template using the [`Language.Weight`][] method on a `Site` or `Page` object.
 
+## Sort order
+
+Hugo sorts languages by weight in ascending order, then lexicographically in ascending order. This affects build order and complement selection.
+
 ## Localized settings
 
 Some configuration settings can be defined separately for each language. For example:
diff --git a/content/en/configuration/roles.md b/content/en/configuration/roles.md
@@ -12,13 +12,24 @@ This is the default configuration:
 
 {{< code-toggle config=roles />}}
 
-To define "guest" and "member" roles:
+## Settings
+
+Use the following setting to define how Hugo orders roles.
+
+weight
+: (`int`) The role [weight](g).
+
+## Sort order
+
+Hugo sorts roles by weight in ascending order, then lexicographically in ascending order. This affects build order and complement selection.
+
+## Example
+
+The following configuration demonstrates how to define multiple roles with specific weights.
 
 {{< code-toggle >}}
 [roles.guest]
 weight = 20
 [roles.member]
 weight = 10
 {{< /code-toggle >}}
-
-Roles are sorted by their [weight](g) in descending order, then by their name in descending order. This affects build order and complement selection.
diff --git a/content/en/configuration/versions.md b/content/en/configuration/versions.md
@@ -12,15 +12,26 @@ This is the default configuration:
 
 {{< code-toggle config=versions />}}
 
-To define "v1.0.0" and "v2.0.0" versions:
+## Settings
+
+Use the following setting to define how Hugo orders versions.
+
+weight
+: (`int`) The language [weight](g).
+
+## Sort order
+
+Hugo sorts versions by weight in ascending order, then by their [semantic version][] in descending order. This affects build order and complement selection.
+
+## Example
+
+The following configuration demonstrates how to define multiple versions with specific weights.
 
 {{< code-toggle >}}
 [versions."v1.0.0"]
-weight = 0
+weight = 20
 [versions."v2.0.0"]
-weight = 0
+weight = 10
 {{< /code-toggle >}}
 
-Versions are sorted by their [weight](g) in ascending order, then by their [semantic version] in descending order. This affects build order and complement selection.
-
 [semantic version]: https://semver.org/
diff --git a/content/en/methods/page/Language.md b/content/en/methods/page/Language.md
@@ -1,6 +1,6 @@
 ---
 title: Language
-description: Returns the language object for the given page.
+description: Returns the Language object for the given page.
 categories: []
 keywords: []
 params:
@@ -9,13 +9,13 @@ params:
     signatures: [PAGE.Language]
 ---
 
-The `Language` method on a `Page` object returns the language object for the given page. The language object is derived from the language definition in the site configuration.
+The `Language` method on a `Page` object returns the `Language` object for the given page, derived from the language definition in your project configuration.
 
-You can also use the `Language` method on a `Site` object. See&nbsp;[details].
+You can also use the `Language` method on a `Site` object. See&nbsp;[details][].
 
 ## Methods
 
-The examples below assume the following in the site configuration:
+The examples below assume the following in your project configuration:
 
 {{< code-toggle file=hugo >}}
 [languages.de]
@@ -29,60 +29,66 @@ weight = 2
 
 {{< new-in 0.153.0 />}}
 
-(`bool`) Reports whether this is the default language object as defined by the [`defaultContentLanguage`][] setting in the site configuration.
+(`bool`) Reports whether this is the [default language][].
 
 ```go-html-template
 {{ .Language.IsDefault }} → true
 ```
 
 ### Lang
 
-(`string`) The language tag as defined by [RFC 5646]. This is the lower cased key from the site configuration.
+(`string`) Returns the language tag as defined by [RFC 5646][]. This is the lowercased key from your project configuration.
 
 ```go-html-template
 {{ .Language.Lang }} → de
 ```
 
 ### LanguageCode
 
-(`string`) The language code from the site configuration. Falls back to `Lang` if not defined.
+(`string`) Returns the [`languageCode`][] from your project configuration. Falls back to `Lang` if not defined.
 
 ```go-html-template
 {{ .Language.LanguageCode }} → de-DE
 ```
 
 ### LanguageDirection
 
-(`string`) The language direction from the site configuration, either `ltr` or `rtl`.
+(`string`) Returns the [`languageDirection`][] from your project configuration.
 
 ```go-html-template
 {{ .Language.LanguageDirection }} → ltr
 ```
 
 ### LanguageName
 
-(`string`) The language name from the site configuration.
+(`string`) Returns the [`languageName`][] from your project configuration.
 
 ```go-html-template
 {{ .Language.LanguageName }} → Deutsch
 ```
 
 ### Name
 
-(`string`) The language tag as defined by [RFC 5646]. This is the lower cased key used in the site configuration. This is an alias for `Lang`.
+{{< new-in 0.153.0 />}}
+
+(`string`) Returns the language tag as defined by [RFC 5646][]. This is the lowercased key from your project configuration. This is an alias for `Lang`.
 
 ```go-html-template
-{{ .Site.Language.Name }} → de
+{{ .Language.Name }} → de
 ```
 
 ### Weight
 
-(`int`) The language weight from the site configuration which determines its order in the slice of languages returned by the `Languages` method on a `Site` object.
+(`int`) Returns the language [`weight`][] from your project configuration.
 
 ```go-html-template
 {{ .Language.Weight }} → 2
 ```
 
-[`defaultContentLanguage`]: /configuration/all/#defaultcontentlanguage
-[details]: /methods/site/language/
+[`languageCode`]: /configuration/languages/#languagecode
+[`languageDirection`]: /configuration/languages/#languagedirection
+[`languageName`]: /configuration/languages/#languagename
+[`weight`]: /configuration/languages/#weight
+[default language]: /quick-reference/glossary/#default-language
+[details]: /methods/page/language/
 [RFC 5646]: https://datatracker.ietf.org/doc/html/rfc5646
diff --git a/content/en/methods/site/Language.md b/content/en/methods/site/Language.md
@@ -1,6 +1,6 @@
 ---
 title: Language
-description: Returns the language object for the given site.
+description: Returns the Language object for the given site.
 categories: []
 keywords: []
 params:
@@ -9,13 +9,13 @@ params:
     signatures: [SITE.Language]
 ---
 
-The `Language` method on a `Page` object returns the language object for the given page. The language object is derived from the language definition in the site configuration.
+The `Language` method on a `Site` object returns the `Language` object for the given site, derived from the language definition in your project configuration.
 
-You can also use the `Language` method on a `Page` object. See&nbsp;[details].
+You can also use the `Language` method on a `Page` object. See&nbsp;[details][].
 
 ## Methods
 
-The examples below assume the following in the site configuration:
+The examples below assume the following in your project configuration:
 
 {{< code-toggle file=hugo >}}
 [languages.de]
@@ -29,55 +29,57 @@ weight = 1
 
 {{< new-in 0.153.0 />}}
 
-(`bool`) Reports whether this is the default language object as defined by the [`defaultContentLanguage`][] setting in the site configuration.
+(`bool`) Reports whether this is the [default language][].
 
 ```go-html-template
 {{ .Site.Language.IsDefault }} → true
 ```
 
 ### Lang
 
-(`string`) The language tag as defined by [RFC 5646]. This is the lower cased key from the site configuration.
+(`string`) Returns the language tag as defined by [RFC 5646][]. This is the lowercased key from your project configuration.
 
 ```go-html-template
 {{ .Site.Language.Lang }} → de
 ```
 
 ### LanguageCode
 
-(`string`) The language code from the site configuration. Falls back to `Lang` if not defined.
+(`string`) Returns the [`languageCode`][] from your project configuration. Falls back to `Lang` if not defined.
 
 ```go-html-template
 {{ .Site.Language.LanguageCode }} → de-DE
 ```
 
 ### LanguageDirection
 
-(`string`) The language direction from the site configuration, either `ltr` or `rtl`.
+(`string`) Returns the [`languageDirection`][] from your project configuration.
 
 ```go-html-template
 {{ .Site.Language.LanguageDirection }} → ltr
 ```
 
 ### LanguageName
 
-(`string`) The language name from the site configuration.
+(`string`) Returns the [`languageName`][] from your project configuration.
 
 ```go-html-template
 {{ .Site.Language.LanguageName }} → Deutsch
 ```
 
 ### Name
 
-(`string`) The language tag as defined by [RFC 5646]. This is the lower cased key from the site configuration. This is an alias for `Lang`.
+{{< new-in 0.153.0 />}}
+
+(`string`) Returns the language tag as defined by [RFC 5646][]. This is the lowercased key from your project configuration. This is an alias for `Lang`.
 
 ```go-html-template
 {{ .Site.Language.Name }} → de
 ```
 
 ### Weight
 
-(`int`) The language weight from the site configuration which determines its order in the slice of languages returned by the `Languages` method on a `Site` object.
+(`int`) Returns the language [`weight`][] from your project configuration.
 
 ```go-html-template
 {{ .Site.Language.Weight }} → 1
@@ -94,6 +96,10 @@ Some of the methods above are commonly used in a base template as attributes for
 >
 ```
 
-[`defaultContentLanguage`]: /configuration/all/#defaultcontentlanguage
+[`languageCode`]: /configuration/languages/#languagecode
+[`languageDirection`]: /configuration/languages/#languagedirection
+[`languageName`]: /configuration/languages/#languagename
+[`weight`]: /configuration/languages/#weight
+[default language]: /quick-reference/glossary/#default-language
 [details]: /methods/page/language/
 [RFC 5646]: https://datatracker.ietf.org/doc/html/rfc5646
diff --git a/content/en/methods/site/Role.md b/content/en/methods/site/Role.md
@@ -1,34 +1,34 @@
 ---
 title: Role
-description: Returns the role object for the given site.
+description: Returns the Role object for the given site.
 categories: []
 keywords: []
 params:
   functions_and_methods:
-    returnType: roles.RoleSite
+    returnType: roles.Role
     signatures: [SITE.Role]
 ---
 
 {{< new-in 0.153.0 />}}
 
-The `Role` method on a `Site` object returns the role object for the given site. The role object is derived from the role definition in the site configuration.
+The `Role` method on a `Site` object returns the `Role` object for the given site, derived from the role definition in your site configuration.
 
 ## Methods
 
 ### IsDefault
 
-(`bool`) Reports whether this is the default role object as defined by the [`defaultContentRole`][] setting in the site configuration.
+(`bool`) Reports whether this is the [default role][].
 
 ```go-html-template
 {{ .Site.Role.IsDefault }} → true
 ```
 
 ### Name
 
-(`string`) Returns the role name. This is the lower cased key from the site configuration.
+(`string`) Returns the role name. This is the lowercased key from your site configuration.
 
 ```go-html-template
 {{ .Site.Role.Name }} → guest
 ```
 
-[`defaultContentRole`]: /configuration/all/#defaultcontentrole
+[default role]: /quick-reference/glossary/#default-role
diff --git a/content/en/methods/site/Version.md b/content/en/methods/site/Version.md
@@ -1,6 +1,6 @@
 ---
 title: Version
-description: Returns the version object for the given site.
+description: Returns the Version object for the given site.
 categories: []
 keywords: []
 params:
@@ -11,24 +11,24 @@ params:
 
 {{< new-in 0.153.0 />}}
 
-The `Version` method on a `Site` object returns the version object for the given site. The version object is derived from the version definition in the site configuration.
+The `Version` method on a `Site` object returns the `Version` object for the given site, derived from the version definition in your site configuration.
 
 ## Methods
 
 ### IsDefault
 
-(`bool`) Reports whether this is the default version object as defined by the [`defaultContentVersion`][] setting in the site configuration.
+(`bool`) Reports whether this is the [default version][].
 
 ```go-html-template
 {{ .Site.Version.IsDefault }} → true
 ```
 
 ### Name
 
-(`string`) Returns the version name. This is the lower cased key from the site configuration.
+(`string`) Returns the version name. This is the lowercased key from your site configuration.
 
 ```go-html-template
 {{ .Site.Version.Name }} → v1.0.0
 ```
 
-[`defaultContentVersion`]: /configuration/all/#defaultcontentversion
+[default version]: /quick-reference/glossary/#default-version
diff --git a/content/en/quick-reference/glossary/default-language.md b/content/en/quick-reference/glossary/default-language.md
@@ -2,7 +2,7 @@
 title: default language
 ---
 
-The _default language_ is is the value defined by the [`defaultContentLanguage`][] setting, falling back to the first language in the project, and finally to `en`. This first language is identified by the lowest [_weight_](g), using lexicographical order as the final fallback if weights are tied or undefined.
+The _default language_ is is the value defined by the [`defaultContentLanguage`][] setting, falling back to the first language in the project, and finally to `en`. The first language is identified by the lowest [_weight_](g), using lexicographical order as the final fallback if weights are tied or undefined.
 
   See also: [_language_](g).
 
diff --git a/content/en/quick-reference/glossary/default-role.md b/content/en/quick-reference/glossary/default-role.md
@@ -2,7 +2,7 @@
 title: default role
 ---
 
-The _default role_ is the value defined by the [`defaultContentRole`][] setting, falling back to the first role in the project, and finally to `guest`. This first role is identified by the lowest [_weight_](g), using lexicographical order as the final fallback if weights are tied or undefined.
+The _default role_ is the value defined by the [`defaultContentRole`][] setting, falling back to the first role in the project, and finally to `guest`. The first role is identified by the lowest [_weight_](g), using lexicographical order as the final fallback if weights are tied or undefined.
 
   See also: [_role_](g).
 
diff --git a/content/en/quick-reference/glossary/default-version.md b/content/en/quick-reference/glossary/default-version.md
@@ -2,7 +2,7 @@
 title: default version
 ---
 
-The _default version_ is the value defined by the [`defaultContentVersion`][] setting, falling back to the first version in the project, and finally to `v1.0.0`. This first version is identified by the lowest [_weight_](g), using a descending semantic sort as the final fallback if weights are tied or undefined.
+The _default version_ is the value defined by the [`defaultContentVersion`][] setting, falling back to the first version in the project, and finally to `v1.0.0`. The first version is identified by the lowest [_weight_](g), using a descending semantic sort as the final fallback if weights are tied or undefined.
 
   See also: [_version_](g).
 
