-
-
Notifications
You must be signed in to change notification settings - Fork 7.6k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Closes #13205
- Loading branch information
Showing
10 changed files
with
495 additions
and
28 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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 |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.