docs: link effects #1008

README.md

@@ -42,12 +42,14 @@ The Relearn theme is an enhanced fork of the popular [Learn theme](https://githu
   - [Multilingual content search capabilities](https://mcshelby.github.io/hugo-theme-relearn/configuration/sidebar/search#mixed-language-support)
 
 - **Enhanced Markdown Features**
-  - [CommonMark and other Markdown extensions](https://mcshelby.github.io/hugo-theme-relearn/authoring/markdown#standard-and-extensions)
+  - [CommonMark compliant](https://mcshelby.github.io/hugo-theme-relearn/authoring/markdown)
+  - [Support for Markdown extensions like GitHub Flavored Markdown](https://mcshelby.github.io/hugo-theme-relearn/authoring/markdown#standard-and-extensions)
   - [Support for Obsidian callouts](https://mcshelby.github.io/hugo-theme-relearn/authoring/markdown#obsidian-callouts)
-  - [Advanced image manipulation like lightbox, sizing, shadows, borders, and alignment](https://mcshelby.github.io/hugo-theme-relearn/configuration/customization/imageeffects)
+  - [Advanced link manipulation like download and target](https://mcshelby.github.io/hugo-theme-relearn/configuration/customization/linkeffects)
+  - [Advanced image manipulation like lightbox, sizing, shadows, borders and alignment](https://mcshelby.github.io/hugo-theme-relearn/configuration/customization/imageeffects)
 
 - **Rich Shortcode Library**
-  - [Customizable marker badges](https://mcshelby.github.io/hugo-theme-relearn/shortcodes/badge)
+  - [Marker badges](https://mcshelby.github.io/hugo-theme-relearn/shortcodes/badge)
   - [Flexible buttons](https://mcshelby.github.io/hugo-theme-relearn/shortcodes/button)
   - [Child page listing](https://mcshelby.github.io/hugo-theme-relearn/shortcodes/children)
   - [Expandable content areas](https://mcshelby.github.io/hugo-theme-relearn/shortcodes/expand)

docs/config/_default/params.toml

@@ -488,6 +488,16 @@ disableDefaultRelref = false
 # not be servable from the file system.
 disableExplicitIndexURLs = false
 
+# How to open external links.
+# Default: '_blank'
+# For external links you can define how they are opened in your browser. All
+# values for the HTML `target` attribute of the `a` element are allowed. The
+# default value opens external links in a separate browser tab. If you want
+# to open those links in the same tab, use '_self'.
+# If you want to set the default behavior for all links, use link effects.
+# This can be overridden in the page's frontmatter.
+externalLinkTarget = '_self'
+
 # What to do when local page link is not resolved.
 # Default: ''
 # You can control what should happen if a local link can not be resolved to a
@@ -500,14 +510,16 @@ disableExplicitIndexURLs = false
 # This can be overridden in the page's frontmatter.
 link.errorlevel = 'warning'
 
-# How to open external links.
-# Default: '_blank'
-# For external links you can define how they are opened in your browser. All
-# values for the HTML `target` attribute of the `a` element are allowed. The
-# default value opens external links in a separate browser tab. If you want
-# to open those links in the same tab, use '_self'.
-# This can be overridden in the page's frontmatter.
-externalLinkTarget = '_self'
+# Link effects.
+# See the documentation for how you can even add your own arbitrary effects to
+# the list.
+# All effects can be overridden in the page's frontmatter or through URL parameter
+# given to the link. See the documentation for details.
+
+# Default: false
+linkEffects.download = false
+# Default: false
+linkEffects.target = false
 
 #++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 # MathJax

docs/content/authoring/frontmatter/linking/index.en.md

@@ -11,6 +11,8 @@ weight = 3
 
 {{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} {{% badge style="green" icon="fa-fw fab fa-markdown" title=" " %}}Front Matter{{% /badge %}} By default, external links open in a new tab. To change this, use the `externalLinkTarget` setting with a proper [link target](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#target).
 
+To set default values for all links, use [link effects](authoring/linkeffects).
+
 For example, this will open links in the same tab
 
 {{< multiconfig >}}

docs/content/authoring/frontmatter/reference/frontmatter.toml

@@ -291,6 +291,16 @@ imageEffects.shadow = false
 # Links
 # These options configure how links are displayed.
 
+# How to open external links.
+# Default: '_blank'
+# For external links you can define how they are opened in your browser. All
+# values for the HTML `target` attribute of the `a` element are allowed. The
+# default value opens external links in a separate browser tab. If you want
+# to open those links in the same tab, use '_self'.
+# If you want to set the default behavior for all links, use link effects.
+# If not set, the set value of your site's hugo.toml is used.
+externalLinkTarget = '_self'
+
 # What to do when local page link is not resolved.
 # Default: ''
 # You can control what should happen if a local link can not be resolved to a
@@ -303,14 +313,17 @@ imageEffects.shadow = false
 # If not set, the set value of your site's hugo.toml is used.
 link.errorlevel = ''
 
-# How to open external links.
-# Default: '_blank'
-# For external links you can define how they are opened in your browser. All
-# values for the HTML `target` attribute of the `a` element are allowed. The
-# default value opens external links in a separate browser tab. If you want
-# to open those links in the same tab, use '_self'.
-# If not set, the set value of your site's hugo.toml is used.
-externalLinkTarget = '_self'
+# Link effects.
+# See the documentation for how you can even add your own arbitrary effects to
+# the list.
+# All effect values default to the values of your site's hugo.toml and can be
+# overridden through URL parameter given to the link. See the documentation for
+# details.
+
+# Default: false
+linkEffects.download = false
+# Default: false
+linkEffects.target = false
 
 #++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 # MathJax

docs/content/authoring/imageeffects.en.md

@@ -1,12 +1,12 @@
 +++
 categories = ["explanation"]
-description = "How to apply graphical effects to your images"
+description = "How to apply effects to your images"
 frontmatter = ["imageEffects"]
 title = "Image Effects"
-weight = 5
+weight = 6
 +++
 
-The theme offers [graphical effects](authoring/markdown#image-effects) for your linked images.
+The theme offers [effects](authoring/markdown#image-effects) for your linked images.
 
 You can [define additional custom image effects and set defaults](configuration/customization/imageeffects) in your configuration.
 
@@ -25,6 +25,8 @@ This can become cumbersome to be done consistently for the whole site. Instead,
 
 Explicitly set URL query parameter will override the defaults set for a page or your site.
 
+If an effect accepts boolean values, only setting the parameter name without a value in the URL will set it to `true`.
+
 Without any settings in your `hugo.toml` `imageEffects` defaults to
 
 {{< multiconfig >}}

docs/content/authoring/imageeffects.pir.md

@@ -1,8 +1,8 @@
 +++
 categories = ["explanation"]
-description = "How to apply graphical effects to your images"
+description = "How to apply effects to your images"
 frontmatter = ["imageEffects"]
 title = "Image Effects"
-weight = 5
+weight = 6
 +++
 {{< piratify >}}

docs/content/authoring/linkeffects.en.md

@@ -0,0 +1,54 @@
++++
+categories = ["explanation"]
+description = "How to apply graphical effects to your links"
+frontmatter = ["linkEffects"]
+title = "Link Effects"
+weight = 5
++++
+
+The theme offers [effects](authoring/markdown#link-effects) for your linked links.
+
+You can [define additional custom link effects and set defaults](configuration/customization/linkeffects) in your configuration.
+
+The default link effects shipped with the theme are
+
+| Name     | Description                                                                  |
+| -------- | ---------------------------------------------------------------------------- |
+| download | Causes the linked resource to be downloaded instead of shown in your browser.<br><br>- `false`: a usual link sending you to the location in your browser<br>- `true`: a link to download the resource<br>- _&lt;string&gt;_: a link to download the resource with the given filename |
+| target   | Whether to show the link in a separate browser tab.<br><br>- `false`: shown in the same tab<br>- _&lt;string&gt;_: [a valid `a` `target` value](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#target)<br><br>If [`externalLinkTarget` is configured](authoring/frontmatter/linking#opening-links) and the URL is external, this will overwrite the link effect value of your `hugo.toml` and page's front matter but can still be overwritten in the URL query parameter. |
+
+One way to use them is to add them as URL query parameter to each individual link.
+
+This can become cumbersome to be done consistently for the whole site. Instead, you can [configure the defaults](configuration/customization/linkeffects) in your `hugo.toml` as well as overriding these defaults in a page's front matter.
+
+Explicitly set URL query parameter will override the defaults set for a page or your site.
+
+If an effect accepts boolean values, only setting the parameter name without a value in the URL will set it to `true`.
+
+Without any settings in your `hugo.toml` `linkEffects` defaults to
+
+{{< multiconfig >}}
+[linkEffects]
+  download = false
+  target = false
+{{< /multiconfig >}}
+
+{{% badge style="green" icon="fa-fw fab fa-markdown" title=" " %}}Front Matter{{% /badge %}} This can be overridden in a pages front matter for example by
+
+{{< multiconfig fm=true >}}
+[linkEffects]
+  target = '_blank'
+{{< /multiconfig >}}
+
+Or by explicitly override settings by URL query parameter
+
+````md {title="URL"}
+[Magic in new window](images/magic.gif?target=_self)
+````
+
+The settings applied to the above link would be
+
+{{< multiconfig >}}
+download = false
+target = '_self'
+{{< /multiconfig >}}

docs/content/authoring/linkeffects.pir.md

@@ -0,0 +1,8 @@
++++
+categories = ["explanation"]
+description = "How to apply graphical effects to your links"
+frontmatter = ["linkEffects"]
+title = "Link Effects"
+weight = 5
++++
+{{< piratify >}}

docs/content/configuration/customization/designs/index.en.md

@@ -2,7 +2,7 @@
 categories = ["explanation", "howto"]
 description = "Extending page designs"
 title = "Page Designs"
-weight = 5
+weight = 6
 +++
 
 Page designs are used to provide different layouts for a given output format. If you instead want to [provide a new output format](configuration/customization/outputformats), the theme got you covered as well.

docs/content/configuration/customization/designs/index.pir.md

@@ -2,6 +2,6 @@
 categories = ["explanation", "howto"]
 description = "Using and extending page designs"
 title = "Page Designs"
-weight = 5
+weight = 6
 +++
 {{< piratify >}}

docs/content/configuration/customization/imageeffects.en.md

@@ -3,7 +3,7 @@ categories = ["explanation", "howto"]
 description = "How to extend image effects"
 options = ["imageEffects"]
 title = "Image Effects"
-weight = 3
+weight = 4
 +++
 
 This page shows you, how to configure custom [image effects](authoring/markdown#image-effects) on top of existing ones.

docs/content/configuration/customization/imageeffects.pir.md

@@ -3,6 +3,6 @@ categories = ["explanation", "howto"]
 description = "How to extend image effects"
 options = ["imageEffects"]
 title = "Image Effects"
-weight = 3
+weight = 4
 +++
 {{< piratify >}}

docs/content/configuration/customization/linkeffects.en.md

@@ -0,0 +1,71 @@
++++
+categories = ["explanation", "howto"]
+description = "How to extend link effects"
+options = ["linkEffects"]
+title = "Link Effects"
+weight = 3
++++
+
+This page shows you, how to configure custom [link effects](authoring/markdown#link-effects) on top of existing ones.
+
+This setting can also [be overridden by your front matter](authoring/linkeffects).
+
+If you don't configure anything in your `hugo.toml`, the link effects default to
+
+## Default Values
+
+{{< multiconfig >}}
+[linkEffects]
+  download = false
+  target = false
+{{< /multiconfig >}}
+
+## Configuration
+
+{{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} You can change these settings in your `hugo.toml` and add arbitrary custom effects as boolean values (like `bg-white` in the below snippet).
+
+{{< multiconfig file=hugo >}}
+[params]
+  [params.linkEffects]
+    bg-white = true
+    target = '_blank'
+{{< /multiconfig >}}
+
+This would result in
+
+{{< multiconfig >}}
+[linkEffects]
+  bg-white = true
+  download = false
+    target = '_blank'
+{{< /multiconfig >}}
+
+### Example
+
+With this configuration in effect, the following URL
+
+````markdown {title="Markdown"}
+[Magic in new window](images/magic.gif)
+````
+
+would result in
+
+````html {title="HTML"}
+<a href="/images/magic.gif?target=_blank" target="_blank" class="bg-white">Magic in new window</a>
+````
+
+## Styling Effects
+
+If the resulting effect value is `true` a class with the effect's name will be added.
+
+Styles for default effects are contained in the theme. Add styles for your custom effects to `layouts/partials/content-header.html`.
+
+For the above custom effect you could add the following style:
+
+````html {title="layouts/partials/content-header.html"}
+<style>
+a.bg-white {
+  background-color: white;
+}
+</style>
+````

docs/content/configuration/customization/linkeffects.pir.md

@@ -0,0 +1,8 @@
++++
+categories = ["explanation", "howto"]
+description = "How to extend link effects"
+options = ["linkEffects"]
+title = "Link Effects"
+weight = 3
++++
+{{< piratify >}}

docs/content/configuration/customization/outputformats/_index.en.md

@@ -2,7 +2,7 @@
 categories = ["explanation", "howto"]
 description = "Adding Custom Output Formats"
 title = "Output Formats"
-weight = 6
+weight = 7
 disableToc = false
 +++
 

docs/content/configuration/customization/outputformats/_index.pir.md

@@ -2,6 +2,6 @@
 categories = ["explanation", "howto"]
 description = "Adding Custom Output Formats"
 title = "Output Formats"
-weight = 6
+weight = 7
 +++
 {{< piratify >}}

docs/content/configuration/customization/taxonomy.en.md

@@ -3,7 +3,7 @@ categories = ["explanation", "howto", "reference"]
 description = "How to display custom taxonomies on your pages"
 tags = ["taxonomy"]
 title = "Taxonomies"
-weight = 7
+weight = 8
 +++
 
 This page explains how to show custom taxonomies on your pages.

docs/content/configuration/customization/taxonomy.pir.md

@@ -3,6 +3,6 @@ categories = ["explanation", "howto", "reference"]
 description = "How to display custom taxonomies on your pages"
 tags = ["taxonomy"]
 title = "Taxonomies"
-weight = 7
+weight = 8
 +++
 {{< piratify >}}

docs/content/configuration/customization/topbar/_index.en.md

@@ -4,7 +4,7 @@ description = "How to extend the topbar"
 options = ["editURL"]
 outputs = ["html", "rss", "print", "markdown", "source"]
 title = "Topbar"
-weight = 4
+weight = 5
 +++
 
 The theme comes with a reasonably configured topbar. You can learn how to [configure the defaults in this section](authoring/frontmatter/topbar).

docs/content/configuration/customization/topbar/_index.pir.md

@@ -4,6 +4,6 @@ description = "How to extend the topbar"
 options = ["editURL"]
 outputs = ["html", "rss", "print", "markdown", "source"]
 title = "Topbarrr"
-weight = 4
+weight = 5
 +++
 {{< piratify >}}

docs/content/introduction/releasenotes/7/4.en.md

@@ -10,9 +10,9 @@ weight = -4
 
 ### Change
 
-- {{% badge style="note" title=" " %}}Change{{% /badge %}} The `target` parameter of the [`button` shortcode](shortcodes/button#parameter) was deprecated. Use [link effects](authoring/markdown#link-effects)  on the `href` instead.
+- {{% badge style="note" title=" " %}}Change{{% /badge %}} The `target` parameter of the [`button` shortcode](shortcodes/button#parameter) was deprecated.
 
-  You don't need to change anything as the old parameter still works but may generate warnings.
+  Use [link effects](authoring/markdown#link-effects)  on the `href` parameter instead. You don't need to change anything as the old parameter still works but may generate warnings.
 
 ### New
 
@@ -22,9 +22,9 @@ weight = -4
 
 - {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} It is now possible to add query parameter and an optional fragment part to all links. This is regardless whether it is a local or remote address and also applies to Hugo's internal path.
 
-  By that you can now use it on Markdown links, image links, page references.
+  By that you can now use it on Markdown links and image links, page references and [buttons](shortcodes/button).
 
-- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} This release introduces [link effects](authoring/markdown#link-effects) which work similar to [image effects](authoring/markdown#image-effects) and can be set as query parameter on any link.
+- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} This release introduces [link effects](authoring/linkeffects) which work similar to [image effects](authoring/imageeffects) and can be set as query parameter on any link.
 
   With that you currently can specify
 

layouts/partials/version.txt

@@ -1 +1 @@
-7.3.2+ada45be3f20e6f22357d406158e530921283623b
+7.3.2+83860202296af0be408eba2a8145c8325403ce04