mirror of
https://github.com/gohugoio/hugoDocs.git
synced 2025-09-16 04:47:38 -04:00
Define and describe the concept of a logical path
This commit is contained in:
Joe Mooring
Bjørn Erik Pedersen
parent
97a8d29636
commit
313b1d85e6
@ -11,26 +11,26 @@ 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)
|
||||
[N](#node)
|
||||
[O](#object)
|
||||
[P](#page-bundle)
|
||||
[R](#regular-page)
|
||||
[S](#scalar)
|
||||
[T](#taxonomic-weight)
|
||||
[U](#unmarshal)
|
||||
[V](#variable)
|
||||
[W](#walk)
|
||||
[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)
|
||||
[N](#node)
|
||||
[O](#object)
|
||||
[P](#page-bundle)
|
||||
[R](#regular-page)
|
||||
[S](#scalar)
|
||||
[T](#taxonomic-weight)
|
||||
[U](#unmarshal)
|
||||
[V](#variable)
|
||||
[W](#walk)
|
||||
|
||||
###### action
|
||||
|
||||
@ -202,6 +202,12 @@ Any [page kind](#page-kind) that receives a page [collection](#collection) in [c
|
||||
|
||||
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.
|
||||
|
||||
###### logical path
|
||||
|
||||
{{< new-in 0.123.0 >}}
|
||||
|
||||
A page or page resource identifier derived from the file path, excluding its extension and language identifier. This value is neither a file path nor a URL. <!-- You may also set this value using the `path` front matter field. --> See [details](/methods/page/path).
|
||||
|
||||
###### 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.
|
||||
|
||||
@ -1,6 +1,6 @@
|
||||
---
|
||||
title: Path
|
||||
description: Returns the canonical page path of the given page.
|
||||
description: Returns the logical path of the given page.
|
||||
categories: []
|
||||
keywords: []
|
||||
action:
|
||||
@ -9,20 +9,23 @@ action:
|
||||
- methods/page/RelPermalink
|
||||
returnType: string
|
||||
signatures: [PAGE.Path]
|
||||
toc: true
|
||||
---
|
||||
|
||||
{{< new-in 0.123.0 >}}
|
||||
|
||||
The `Path` method on a `Page` object returns the canonical page path of the given page, regardless of whether the page is backed by a file.
|
||||
The `Path` method on a `Page` object returns the logical path of the given page, regardless of whether the page is backed by a file.
|
||||
|
||||
[logical path]: /getting-started/glossary#logical-path
|
||||
|
||||
```go-html-template
|
||||
{{ .Path }} → /posts/post-1
|
||||
```
|
||||
|
||||
This value is neither a file path nor a relative URL. It is a canonical identifier for each page, independent of content format, language, and URL.
|
||||
This value is neither a file path nor a relative URL. It is a logical identifier for each page, independent of content format, language, and URL modifiers.
|
||||
|
||||
{{% note %}}
|
||||
Beginning with the release of [v0.92.0] in January 2022, Hugo emitted a warning whenever the `Path` method was called. The warning indicated that this method would change in a future release.
|
||||
Beginning with the release of [v0.92.0] in January 2022, Hugo emitted a warning whenever calling the `Path` method. The warning indicated that this method would change in a future release.
|
||||
|
||||
The meaning of, and value returned by, the `Path` method on a `Page` object changed with the release of [v0.123.0] in February 2024.
|
||||
|
||||
@ -30,7 +33,7 @@ The meaning of, and value returned by, the `Path` method on a `Page` object chan
|
||||
[v0.123.0]: https://github.com/gohugoio/hugo/releases/tag/v0.123.0
|
||||
{{% /note %}}
|
||||
|
||||
To determine the canonical page path for pages backed by a file, Hugo starts with the file path, relative to the content directory, and then:
|
||||
To determine the logical path for pages backed by a file, Hugo starts with the file path, relative to the content directory, and then:
|
||||
|
||||
1. Strips the file extension
|
||||
2. Strips the language identifier
|
||||
@ -39,16 +42,24 @@ To determine the canonical page path for pages backed by a file, Hugo starts wit
|
||||
|
||||
The value returned by the `Path` method on a `Page` object is independent of content format, language, and URL modifiers such as the `slug` and `url` front matter fields.
|
||||
|
||||
File path|Front matter slug|Value returned by .Path
|
||||
## Examples
|
||||
|
||||
### Monolingual site
|
||||
|
||||
Note that the logical path is independent of content format and URL modifiers.
|
||||
|
||||
File path|Front matter slug|Logical path
|
||||
:--|:--|:--
|
||||
`content/_index.md`||`/`
|
||||
`content/posts/_index.md`||`/posts`
|
||||
`content/posts/post-1.md`|`foo`|`/posts/post-1`
|
||||
`content/posts/post-2.html`|`bar`|`/posts/post-2`
|
||||
|
||||
On a multilingual site, note that the return value is the same regardless of language:
|
||||
### Multilingual site
|
||||
|
||||
File path|Front matter slug|Value returned by .Path
|
||||
Note that the logical path is independent of content format, language identifiers, and URL modifiers.
|
||||
|
||||
File path|Front matter slug|Logical path
|
||||
:--|:--|:--
|
||||
`content/_index.en.md`||`/`
|
||||
`content/_index.de.md`||`/`
|
||||
@ -59,6 +70,8 @@ File path|Front matter slug|Value returned by .Path
|
||||
`content/posts/posts-2.en.html`|`bar`|`/posts/post-2`
|
||||
`content/posts/posts-2.de.html`|`bar`|`/posts/post-2`
|
||||
|
||||
### Pages not backed by a file
|
||||
|
||||
The `Path` method on a `Page` object returns a value regardless of whether the page is backed by a file.
|
||||
|
||||
```text
|
||||
@ -81,3 +94,60 @@ public/
|
||||
│ └── index.html .Page.Path = /tags
|
||||
└── index.html .Page.Path = /
|
||||
```
|
||||
|
||||
## Finding pages
|
||||
|
||||
These methods, functions, and shortcodes use the logical path to find the given page:
|
||||
|
||||
Methods|Functions|Shortcodes
|
||||
:--|:--|:--
|
||||
[`Site.GetPage`]|[`urls.Ref`]|[`ref`]
|
||||
[`Page.GetPage`]|[`urls.RelRef`]|[`relref`]
|
||||
[`Page.Ref`]||
|
||||
[`Page.RelRef`]||
|
||||
|
||||
[`urls.Ref`]: functions/urls/ref/
|
||||
[`urls.RelRef`]: /functions/urls/relref/
|
||||
[`Page.GetPage`]: /methods/page/getpage/
|
||||
[`Site.GetPage`]: /methods/site/getpage/
|
||||
[`ref`]: /content-management/shortcodes/#ref
|
||||
[`relref`]: /content-management/shortcodes/#relref
|
||||
[`Page.Ref`]: /methods/page/ref
|
||||
[`Page.RelRef`]: /methods/page/relref
|
||||
|
||||
{{% note %}}
|
||||
Specify the logical path when using any of these methods, functions, or shortcodes. If you include a file extension or language identifier, Hugo will strip these values before finding the page in the logical tree.
|
||||
{{% /note %}}
|
||||
|
||||
|
||||
## Logical tree
|
||||
|
||||
Just as file paths form a file tree, logical paths form a logical tree.
|
||||
|
||||
A file tree:
|
||||
|
||||
```text
|
||||
content/
|
||||
└── s1/
|
||||
├── p1/
|
||||
│ └── index.md
|
||||
└── p2.md
|
||||
```
|
||||
|
||||
The same content represented as a logical tree:
|
||||
|
||||
```text
|
||||
content/
|
||||
└── s1/
|
||||
├── p1
|
||||
└── p2
|
||||
```
|
||||
|
||||
A key difference between these trees is the relative path from p1 to p2:
|
||||
|
||||
- In the file tree, the relative path from p1 to p2 is `../p2.md`
|
||||
- In the logical tree, the relative path is `p2`
|
||||
|
||||
{{% note %}}
|
||||
Rember to use the logical path when using any of the methods, functions, or shortcodes listed in the previous section. If you include a file extension or language identifier, Hugo will strip these values before finding the page in the logical tree.
|
||||
{{% /note %}}
|
||||
|
||||
@ -25,4 +25,4 @@ To prevent Go's [html/template] package from escaping HTML entities, pass the re
|
||||
[html/template]: https://pkg.go.dev/html/template
|
||||
[entities]: https://developer.mozilla.org/en-US/docs/Glossary/Entity
|
||||
[tags]: https://developer.mozilla.org/en-US/docs/Glossary/Tag
|
||||
[`htmlUnescape`]: /functions/
|
||||
[`htmlUnescape`]: /functions/transform/htmlunescape/
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user