mirror/hugo
1
0
Fork 0
mirror of https://github.com/gohugoio/hugo.git synced 2025-08-21 21:35:28 +02:00
Code Issues Packages Projects Releases Wiki Activity

Merge commit 'dec8cd4ada29218971743333f8ac662a9c06aad8'

Browse Source
This commit is contained in:
Bjørn Erik Pedersen
2024-09-01 14:51:15 +02:00
parent 469124823c dec8cd4ada
commit 0c453420e6
43 changed files with 906 additions and 436 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
docs/content/en/content-management/content-adapters.md
View File

@@ -125,7 +125,7 @@ Set any [front matter field] in the map passed to the [`AddPage`](#addpage) meth
This table describes the fields most commonly passed to the `AddPage` method.
Key|Descripion|Required
Key|Description|Required
:--|:--|:-:
`content.mediaType`|The content [media type]. Default is `text/markdown`. See [content formats] for examples.| 
`content.value`|The content value as a string.| 
@@ -148,7 +148,7 @@ When setting the `path`, Hugo transforms the given string to a logical path. For
Construct the map passed to the [`AddResource`](#addresource) method using the fields below.
Key|Descripion|Required
Key|Description|Required
:--|:--|:-:
`content.mediaType`|The content [media type].|:heavy_check_mark:
`content.value`|The content value as a string or resource.|:heavy_check_mark:

17
docs/content/en/content-management/multilingual.md
View File

@@ -21,15 +21,22 @@ This is the default language configuration:
In the above, `en` is the language key.
{{% note %}}
Each language key must conform to the syntax described in [RFC 5646]. You must use hyphens to separate subtags. For example:
Language keys must conform to the syntax described in [RFC 5646]. For example:
- `en`
- `en-GB`
- `pt-BR`
- `en-US`
Artificial languages with private use subtags as defined in [RFC 5646 § 2.2.7] are also supported. Omit the `art-x-` prefix from the language key. For example:
- `hugolang`
{{% note %}}
Private use subtags must not exceed 8 alphanumeric characters.
{{% /note %}}
[RFC 5646]: https://datatracker.ietf.org/doc/html/rfc5646#section-2.1
{{% /note %}}
[RFC 5646 § 2.2.7]: https://datatracker.ietf.org/doc/html/rfc5646#section-2.2.7
This is an example of a site configuration for a multilingual project. Any key not defined in a `languages` object will fall back to the global value in the root of your site configuration.

127
docs/content/en/content-management/page-resources.md
View File

@@ -1,6 +1,6 @@
---
title: Page resources
description: Page resources -- images, other pages, documents, etc. -- have page-relative URLs and their own metadata.
description: Use page resources to logically associate assets with a page.
categories: [content management]
keywords: [bundle,content,resources]
menu:
@@ -37,82 +37,83 @@ content
└── index.md (root of page bundle)
```
## Properties
## Examples
ResourceType
: The main type of the resource's [Media Type](/templates/output-formats/#media-types). For example, a file of MIME type `image/jpeg` has the ResourceType `image`. A `Page` will have `ResourceType` with value `page`.
Use any of these methods on a `Page` object to capture page resources:
Name
: Default value is the file name (relative to the owning page). Can be set in front matter.
- [`Resources.ByType`]
- [`Resources.Get`]
- [`Resources.GetMatch`]
- [`Resources.Match`]
Title
: Default value is the same as `.Name`. Can be set in front matter.
Once you have captured a resource, use any of the applicable [`Resource`] methods to return a value or perform an action.
Permalink
: The absolute URL to the resource. Resources of type `page` will have no value.
[`Resource`]: /methods/resource
[`Resources.ByType`]: /methods/page/resources#bytype
[`Resources.GetMatch`]: /methods/page/resources#getmatch
[`Resources.Get`]: /methods/page/resources#get
[`Resources.Match`]: /methods/page/resources#match
RelPermalink
: The relative URL to the resource. Resources of type `page` will have no value.
The following examples assume this content structure:
Content
: The content of the resource itself. For most resources, this returns a string
with the contents of the file. Use this to create inline resources.
```text
content/
└── example/
├── data/
│ └── books.json <-- page resource
├── images/
│ ├── a.jpg <-- page resource
│ └── b.jpg <-- page resource
├── snippets/
│ └── text.md <-- page resource
└── index.md
```
Render a single image, and throw an error if the file does not exist:
```go-html-template
{{ with .Resources.GetMatch "script.js" }}
<script>{{ .Content | safeJS }}</script>
{{ end }}
{{ with .Resources.GetMatch "style.css" }}
<style>{{ .Content | safeCSS }}</style>
{{ end }}
{{ with .Resources.GetMatch "img.png" }}
<img src="data:{{ .MediaType.Type }};base64,{{ .Content | base64Encode }}">
{{ $path := "images/a.jpg" }}
{{ with .Resources.Get $path }}
<img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
{{ else }}
{{ errorf "Unable to get page resource %q" $path }}
{{ end }}
```
MediaType.Type
: The media type (formerly known as a MIME type) of the resource (e.g., `image/jpeg`).
MediaType.MainType
: The main type of the resource's media type (e.g., `image`).
MediaType.SubType
: The subtype of the resource's type (e.g., `jpeg`). This may or may not correspond to the file suffix.
MediaType.Suffixes
: A slice of possible file suffixes for the resource's media type (e.g., `[jpg jpeg jpe jif jfif]`).
## Methods
ByType
: Returns the page resources of the given type.
Render all images, resized to 300 px wide:
```go-html-template
{{ .Resources.ByType "image" }}
{{ range .Resources.ByType "image" }}
{{ with .Resize "300x" }}
<img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
{{ end }}
{{ end }}
```
Match
: Returns all the page resources (as a slice) whose `Name` matches the given Glob pattern ([examples](https://github.com/gobwas/glob/blob/master/readme.md)). The matching is case-insensitive.
Render the markdown snippet:
```go-html-template
{{ .Resources.Match "images/*" }}
{{ with .Resources.Get "snippets/text.md" }}
{{ .Content }}
{{ end }}
```
GetMatch
: Same as `Match` but will return the first match.
List the titles in the data file, and throw an error if the file does not exist.
### Pattern matching
```go
// Using Match/GetMatch to find this images/sunset.jpg ?
.Resources.Match "images/sun*" ✅
.Resources.Match "**/sunset.jpg" ✅
.Resources.Match "images/*.jpg" ✅
.Resources.Match "**.jpg" ✅
.Resources.Match "*" 🚫
.Resources.Match "sunset.jpg" 🚫
.Resources.Match "*sunset.jpg" 🚫
```go-html-template
{{ $path := "data/books.json" }}
{{ with .Resources.Get $path }}
{{ with . | transform.Unmarshal }}
<p>Books:</p>
<ul>
{{ range . }}
<li>{{ .title }}</li>
{{ end }}
</ul>
{{ end }}
{{ else }}
{{ errorf "Unable to get page resource %q" $path }}
{{ end }}
```
## Metadata
@@ -124,21 +125,21 @@ Resources of type `page` get `Title` etc. from their own front matter.
{{% /note %}}
name
: Sets the value returned in `Name`.
: (`string`) Sets the value returned in `Name`.
{{% note %}}
The methods `Match`, `Get` and `GetMatch` use `Name` to match the resources.
{{% /note %}}
title
: Sets the value returned in `Title`
: (`string`) Sets the value returned in `Title`
params
: A map of custom key-value pairs.
: (`map`) A map of custom key-value pairs.
### Resources metadata example
{{< code-toggle >}}
{{< code-toggle file=content/example.md fm=true >}}
title: Application
date : 2018-01-25
resources :
@@ -173,7 +174,7 @@ From the example above:
- Every docx in the bundle will receive the `word` icon.
{{% note %}}
The __order matters__ --- Only the **first set** values of the `title`, `name` and `params`-**keys** will be used. Consecutive parameters will be set only for the ones not already set. In the above example, `.Params.icon` is first set to `"photo"` in `src = "documents/photo_specs.pdf"`. So that would not get overridden to `"pdf"` by the later set `src = "**.pdf"` rule.
The order matters; only the first set values of the `title`, `name` and `params` keys will be used. Consecutive parameters will be set only for the ones not already set. In the above example, `.Params.icon` is first set to `"photo"` in `src = "documents/photo_specs.pdf"`. So that would not get overridden to `"pdf"` by the later set `src = "**.pdf"` rule.
{{% /note %}}
### The `:counter` placeholder in `name` and `title`