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

tpl/images: Add images.QR function

Browse Source 
Closes #13205
This commit is contained in:
Joe Mooring
2024-12-31 17:43:35 -05:00
committed by Bjørn Erik Pedersen
parent 5d2cbee989
commit 4ea94c451d
10 changed files with 495 additions and 28 deletions
Download Patch File Download Diff File Expand all files Collapse all files

102
docs/content/en/content-management/shortcodes.md
View File

@@ -121,7 +121,7 @@ Hugo renders this to:
</details>
```
The details shortcode accepts these named arguments:
The `details` shortcode accepts these named arguments:
summary
: (`string`) The content of the child `summary` element rendered from Markdown to HTML. Default is `Details`.
@@ -333,6 +333,106 @@ Access nested values by [chaining] the [identifiers]:
{{</* param my.nested.param */>}}
```
### qr
{{% note %}}
To override Hugo's embedded `qr` shortcode, copy the [source code] to a file with the same name in the layouts/shortcodes directory.
[source code]: {{% eturl qr %}}
{{% /note %}}
The `qr` shortcode encodes the given text into a [QR code] using the specified options and renders the resulting image.
[QR code]: https://en.wikipedia.org/wiki/QR_code
Use the self-closing syntax to pass the text as an argument:
```text
{{</* qr text="https://gohugo.io" /*/>}}
```
Or insert the text between the opening and closing tags:
```text
{{</* qr */>}}
https://gohugo.io
{{</* /qr */>}}
```
Both of the above produce this image:
{{< qr text="https://gohugo.io" class="qrcode" />}}
To create a QR code for a phone number:
```text
{{</* qr text="tel:+12065550101" /*/>}}
```
{{< qr text="tel:+12065550101" class="qrcode" />}}
To create a QR code containing contact information in the [vCard] format:
[vCard]: https://en.wikipedia.org/wiki/VCard
```text
{{</* qr level="low" scale=2 alt="QR code of vCard for John Smith" */>}}
BEGIN:VCARD
VERSION:2.1
N;CHARSET=UTF-8:Smith;John;R.;Dr.;PhD
FN;CHARSET=UTF-8:Dr. John R. Smith, PhD.
ORG;CHARSET=UTF-8:ABC Widgets
TITLE;CHARSET=UTF-8:Vice President Engineering
TEL;TYPE=WORK:+12065550101
EMAIL;TYPE=WORK:jsmith@example.org
END:VCARD
{{</* /qr */>}}
```
{{< qr level="low" scale=2 alt="QR code of vCard for John Smith" class="qrcode" >}}
BEGIN:VCARD
VERSION:2.1
N;CHARSET=UTF-8:Smith;John;R.;Dr.;PhD
FN;CHARSET=UTF-8:Dr. John R. Smith, PhD.
ORG;CHARSET=UTF-8:ABC Widgets
TITLE;CHARSET=UTF-8:Vice President Engineering
TEL;TYPE=WORK:+12065550101
EMAIL;TYPE=WORK:jsmith@example.org
END:VCARD
{{< /qr >}}
Internally this shortcode calls the `images.QR` function. Please read the [related documentation] for implementation details and guidance.
[related documentation]: /functions/images/qr/
The `qr` shortcode accepts these named arguments:
text
: (`string`) The text to encode, falling back to the text between the opening and closing shortcode tags.
level
: (`string`) The error correction level to use when encoding the text, one of `low`, `medium`, `quartile`, or `high`. Default is `medium`.
scale
: (`int`) The number of image pixels per QR code module. Must be greater than or equal to 2. Default is `4`.
targetDir
: (`string`) The subdirectory within the [`publishDir`] where Hugo will place the generated image.
[`publishDir`]: /getting-started/configuration/#publishdir
alt
: (`string`) The `alt` attribute of the `img` element.
class
: (`string`) The `class` attribute of the `img` element.
id
: (`string`) The `id` attribute of the `img` element.
title
: (`string`) The `title` attribute of the `img` element.
### ref
{{% note %}}

115
docs/content/en/functions/images/QR.md Normal file
View File

@@ -0,0 +1,115 @@
---
title: images.QR
description: Encodes the given text into a QR code using the specified options, returning an image resource.
keywords: []
action:
aliases: []
related: []
returnType: images.ImageResource
signatures: ['images.QR OPTIONS']
toc: true
math: true
---
{{< new-in 0.141.0 >}}
The `images.QR` function encodes the given text into a [QR code] using the specified options, returning an image resource. The size of the generated image depends on three factors:
- Data length: Longer text necessitates a larger image to accommodate the increased information density.
- Error correction level: Higher error correction levels enhance the QR code's resistance to damage, but this typically results in a slightly larger image size to maintain readability.
- Pixels per module: The number of image pixels assigned to each individual module (the smallest unit of the QR code) directly impacts the overall image size. A higher pixel count per module leads to a larger, higher-resolution image.
Although the default option values are sufficient for most applications, you should test the rendered QR code both on-screen and in print.
[QR code]: https://en.wikipedia.org/wiki/QR_code
## Options
text
: (`string`) The text to encode.
level
: (`string`) The error correction level to use when encoding the text, one of `low`, `medium`, `quartile`, or `high`. Default is `medium`.
Error correction level|Redundancy
:--|:--|:--
low|20%
medium|38%
quartile|55%
high|65%
scale
: (`int`) The number of image pixels per QR code module. Must be greater than or equal to `2`. Default is `4`.
targetDir
: (`string`) The subdirectory within the [`publishDir`] where Hugo will place the generated image. Use Unix-style slashes (`/`) to separarate path segments. If empty or not provided, the image is placed directly in the `publishDir` root. Hugo automatically creates the necessary subdirectories if they don't exist.
[`publishDir`]: /getting-started/configuration/#publishdir
## Examples
To create a QR code using the default values for `level` and `scale`:
```go-html-template
{{ $opts := dict "text" "https://gohugo.io" }}
{{ with images.QR $opts }}
<img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
{{ end }}
```
{{< qr text="https://gohugo.io" class="qrcode" />}}
Specify `level`, `scale`, and `targetDir` as needed to achieve the desired result:
```go-html-template
{{ $opts := dict
"text" "https://gohugo.io"
"level" "high"
"scale" 3
"targetDir" "codes"
}}
{{ with images.QR $opts }}
<img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
{{ end }}
```
{{< qr text="https://gohugo.io" level="high" scale=3 targetDir="codes" class="qrcode" />}}
## Scale
As you decrease the size of a QR code, the maximum distance at which it can be reliably scanned by a device also decreases.
In the example above, we set the `scale` to `2`, resulting in a QR code where each module consists of 2x2 pixels. While this might be sufficient for on-screen display, it's likely to be problematic when printed at 600 dpi.
\[ \frac{2\:px}{module} \times \frac{1\:inch}{600\:px} \times \frac{25.4\:mm}{1\:inch} = \frac{0.085\:mm}{module} \]
This module size is half of the commonly recommended minimum of 0.170 mm.\
If the QR code will be printed, use the default `scale` value of `4` pixels per module.
Avoid using Hugo's image processing methods to resize QR codes. Resizing can introduce blurring due to anti-aliasing when a QR code module occupies a fractional number of pixels.
{{% note %}}
Always test the rendered QR code both on-screen and in print.
{{% /note %}}
## Shortcode
Call the `qr` shortcode to insert a QR code into your content.
Use the self-closing syntax to pass the text as an argument:
```text
{{</* qr text="https://gohugo.io" /*/>}}
```
Or insert the text between the opening and closing tags:
```text
{{</* qr */>}}
https://gohugo.io
{{</* /qr */>}}
```
The `qr` shortcode accepts several arguments including `level` and `scale`. See the [related documentation] for details.
[related documentation]: /content-management/shortcodes/#qr