diff options
Diffstat (limited to 'docs/content/en/methods/page/File.md')
| -rw-r--r-- | docs/content/en/methods/page/File.md | 180 |
1 files changed, 180 insertions, 0 deletions
diff --git a/docs/content/en/methods/page/File.md b/docs/content/en/methods/page/File.md new file mode 100644 index 000000000..c39d1a64d --- /dev/null +++ b/docs/content/en/methods/page/File.md @@ -0,0 +1,180 @@ +--- +title: File +description: For pages backed by a file, returns file information for the given page. +categories: [] +keywords: [] +action: + related: [] + returnType: hugolib.fileInfo + signatures: [PAGE.File] +toc: true +--- + +By default, not all pages are backed by a file, including top level [section] pages, [taxonomy] pages, and [term] pages. By definition, you cannot retrieve file information when the file does not exist. + +To back one of the pages above with a file, create an _index.md file in the corresponding directory. For example: + +```text +content/ +└── books/ + ├── _index.md <-- the top level section page + ├── book-1.md + └── book-2.md +``` + +Code defensively by verifying file existence as shown in each of the examples below. + +## Methods + +{{% note %}} +The path separators (slash or backslash) in `Path`, `Dir`, and `Filename` depend on the operating system. +{{% /note %}} + +BaseFileName +: (`string`) The file name, excluding the extension. + +```go-html-template +{{ with .File }} + {{ .BaseFileName }} +{{ end }} +``` + +ContentBaseName +: (`string`) If the page is a branch or leaf bundle, the name of the containing directory, else the `TranslationBaseName`. + +```go-html-template +{{ with .File }} + {{ .ContentBaseName }} +{{ end }} +``` + +Dir +: (`string`) The file path, excluding the file name, relative to the `content` directory. + +```go-html-template +{{ with .File }} + {{ .Dir }} +{{ end }} +``` + +Ext +: (`string`) The file extension. + +```go-html-template +{{ with .File }} + {{ .Ext }} +{{ end }} +``` + +Filename +: (`string`) The absolute file path. + +```go-html-template +{{ with .File }} + {{ .Filename }} +{{ end }} +``` + +Lang +: (`string`) The language associated with the given file. + +```go-html-template +{{ with .File }} + {{ .Lang }} +{{ end }} +``` + +LogicalName +: (`string`) The file name. + +```go-html-template +{{ with .File }} + {{ .LogicalName }} +{{ end }} +``` + +Path +: (`string`) The file path, relative to the `content` directory. + +```go-html-template +{{ with .File }} + {{ .Path }} +{{ end }} +``` + +TranslationBaseName +: (`string`) The file name, excluding the extension and language identifier. + +```go-html-template +{{ with .File }} + {{ .TranslationBaseName }} +{{ end }} +``` + +UniqueID +: (`string`) The MD5 hash of `.File.Path`. + +```go-html-template +{{ with .File }} + {{ .UniqueID }} +{{ end }} +``` + +## Examples + +Consider this content structure in a multilingual project: + +```text +content/ +├── news/ +│ ├── b/ +│ │ ├── index.de.md <-- leaf bundle +│ │ └── index.en.md <-- leaf bundle +│ ├── a.de.md <-- regular content +│ ├── a.en.md <-- regular content +│ ├── _index.de.md <-- branch bundle +│ └── _index.en.md <-- branch bundle +├── _index.de.md +└── _index.en.md +``` + +With the English language site: + + |regular content|leaf bundle|branch bundle +:--|:--|:--|:-- +BaseFileName|a.en|index.en|_index.en +ContentBaseName|a|b|news +Dir|news/|news/b/|news/ +Ext|md|md|md +Filename|/home/user/...|/home/user/...|/home/user/... +Lang|en|en|en +LogicalName|a.en.md|index.en.md|_index.en.md +Path|news/a.en.md|news/b/index.en.md|news/_index.en.md +TranslationBaseName|a|index|_index +UniqueID|15be14b...|186868f...|7d9159d... + +## Defensive coding + +Some of the pages on a site may not be backed by a file. For example: + +- Top level section pages +- Taxonomy pages +- Term pages + +Without a backing file, Hugo will throw a warning if you attempt to access a `.File` property. For example: + +```text +WARN .File.ContentBaseName on zero object. Wrap it in if or with... +``` + +To code defensively, first check for file existence: + +```go-html-template +{{ with .File }} + {{ .ContentBaseName }} +{{ end }} +``` + +[section]: /getting-started/glossary/#section +[taxonomy]: /getting-started/glossary/#taxonomy +[term]: /getting-started/glossary/#term |