mirrors/hugo
1
0
Fork 0
mirror of https://github.com/gohugoio/hugo.git synced 2025-04-25 21:21:22 +03:00
Code Issues Projects Releases Packages Wiki Activity Actions 2
hugo/docs/content/en/functions/images/Text.md
Pranshu Gaba 2fce0bac03 images: Add option for vertical alignment to images.Text 
Add option ``aligny`` to specify the vertical alignment of the text
with respect to the ``y`` offset from the top of the image. Possible
values of ``aligny`` are ``top`` (default), ``center``, and ``bottom``.

The height of the block of text is measured from the top of the first
line to the baseline of the last line.

- ``top``: (Current behaviour) The top of the first line of the block of
  text is at an offset of ``y`` from the top of the image.

- ``center``: The vertical center of the block of text is at an offset of
  ``y`` from the top of the image.

- ``bottom``: The baseline of the last line of the text is at an offset
  of ``y`` from the top of the image.

Resolves #13414
2025-04-24 14:09:13 +02:00

3.2 KiB
Raw Blame History

title description categories keywords params
images.Text Returns an image filter that adds text to an image.
functions_and_methods
aliases returnType signatures
images.filter
images.Text TEXT [OPTIONS]

Options

Although none of the options are required, at a minimum you will want to set the size to be some reasonable percentage of the image height.

alignx
{{< new-in 0.141.0 />}}
(string) The horizontal alignment of the text relative to the horizontal offset, one of left, center, or right. Default is left.
aligny
(string) The vertical alignment of the text relative to the vertical offset, one of top, center, or bottom. Default is top.
color
(string) The font color, either a 3-digit or 6-digit hexadecimal color code. Default is #ffffff (white).
font
(resource.Resource) The font can be a global resource, a page resource, or a remote resource. Default is Go Regular, a proportional sans-serif TrueType font.
linespacing
(int) The number of pixels between each line. For a line height of 1.4, set the linespacing to 0.4 multiplied by the size. Default is 2.
size
(int) The font size in pixels. Default is 20.
x
(int) The horizontal offset, in pixels, relative to the left of the image. Default is 10.
y
(int) The vertical offset, in pixels, relative to the top of the image. Default is 10.

Usage

Set the text and paths:

{{ $text := "Zion National Park" }}
{{ $fontPath := "https://github.com/google/fonts/raw/main/ofl/lato/Lato-Regular.ttf" }}
{{ $imagePath := "images/original.jpg" }}

Capture the font as a resource:

{{ $font := "" }}
{{ with try (resources.GetRemote $fontPath) }}
  {{ with .Err }}
    {{ errorf "%s" . }}
  {{ else with .Value }}
    {{ $font = . }}
  {{ else }}
    {{ errorf "Unable to get resource %s" $fontPath }}
  {{ end }}
{{ end }}

Create the filter, centering the text horizontally and vertically:

{{ $r := "" }}
{{ $filter := "" }}
{{ with $r = resources.Get $imagePath }}
  {{ $opts := dict
    "alignx" "center"
    "color" "#fbfaf5"
    "font" $font
    "linespacing" 8
    "size" 60
    "x" (mul .Width 0.5 | int)
    "y" (mul .Height 0.5 | int)
  }}
  {{ $filter = images.Text $text $opts }}
{{ else }}
  {{ errorf "Unable to get resource %s" $imagePath }}
{{ end }}

Apply the filter using the images.Filter function:

{{ with $r }}
  {{ with . | images.Filter $filter }}
    <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
  {{ end }}
{{ end }}

You can also apply the filter using the Filter method on a Resource object:

{{ with $r }}
  {{ with .Filter $filter }}
    <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
  {{ end }}
{{ end }}

Example

{{< img src="images/examples/zion-national-park.jpg" alt="Zion National Park" filter="Text" filterArgs="Zion National Park,25,190,40,1.2,#fbfaf5" example=true

}}