diff --git a/README.md b/README.md index edc5d231ae..3fad4a69c4 100644 --- a/README.md +++ b/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) diff --git a/docs/config/_default/params.toml b/docs/config/_default/params.toml index e62111ad55..9e53e9cbda 100644 --- a/docs/config/_default/params.toml +++ b/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 diff --git a/docs/content/authoring/frontmatter/linking/index.en.md b/docs/content/authoring/frontmatter/linking/index.en.md index 8bf2772f0f..38d78c5d3e 100644 --- a/docs/content/authoring/frontmatter/linking/index.en.md +++ b/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 >}} diff --git a/docs/content/authoring/frontmatter/reference/frontmatter.toml b/docs/content/authoring/frontmatter/reference/frontmatter.toml index ee72822de1..0960615e37 100644 --- a/docs/content/authoring/frontmatter/reference/frontmatter.toml +++ b/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 diff --git a/docs/content/authoring/imageeffects.en.md b/docs/content/authoring/imageeffects.en.md index 7eca2aee5d..c4c947ec64 100644 --- a/docs/content/authoring/imageeffects.en.md +++ b/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 >}} diff --git a/docs/content/authoring/imageeffects.pir.md b/docs/content/authoring/imageeffects.pir.md index e2dd1e62cb..31c76116c5 100644 --- a/docs/content/authoring/imageeffects.pir.md +++ b/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 >}} \ No newline at end of file diff --git a/docs/content/authoring/linkeffects.en.md b/docs/content/authoring/linkeffects.en.md new file mode 100644 index 0000000000..e3d4004323 --- /dev/null +++ b/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.

- `false`: a usual link sending you to the location in your browser
- `true`: a link to download the resource
- _<string>_: a link to download the resource with the given filename | +| target | Whether to show the link in a separate browser tab.

- `false`: shown in the same tab
- _<string>_: [a valid `a` `target` value](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#target)

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 >}} diff --git a/docs/content/authoring/linkeffects.pir.md b/docs/content/authoring/linkeffects.pir.md new file mode 100644 index 0000000000..09e29c8777 --- /dev/null +++ b/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 >}} \ No newline at end of file diff --git a/docs/content/configuration/customization/designs/index.en.md b/docs/content/configuration/customization/designs/index.en.md index fe38716044..8b48ce6240 100644 --- a/docs/content/configuration/customization/designs/index.en.md +++ b/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. diff --git a/docs/content/configuration/customization/designs/index.pir.md b/docs/content/configuration/customization/designs/index.pir.md index 8120753890..b3d4ff59a6 100644 --- a/docs/content/configuration/customization/designs/index.pir.md +++ b/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 >}} \ No newline at end of file diff --git a/docs/content/configuration/customization/imageeffects.en.md b/docs/content/configuration/customization/imageeffects.en.md index 8a92e0463f..97445ccfa8 100644 --- a/docs/content/configuration/customization/imageeffects.en.md +++ b/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. diff --git a/docs/content/configuration/customization/imageeffects.pir.md b/docs/content/configuration/customization/imageeffects.pir.md index a62efad158..10080574cb 100644 --- a/docs/content/configuration/customization/imageeffects.pir.md +++ b/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 >}} \ No newline at end of file diff --git a/docs/content/configuration/customization/linkeffects.en.md b/docs/content/configuration/customization/linkeffects.en.md new file mode 100644 index 0000000000..95c3765e02 --- /dev/null +++ b/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"} +Magic in new window +```` + +## 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"} + +```` diff --git a/docs/content/configuration/customization/linkeffects.pir.md b/docs/content/configuration/customization/linkeffects.pir.md new file mode 100644 index 0000000000..77bfc93abc --- /dev/null +++ b/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 >}} \ No newline at end of file diff --git a/docs/content/configuration/customization/outputformats/_index.en.md b/docs/content/configuration/customization/outputformats/_index.en.md index 9edaee834b..d687c96d69 100644 --- a/docs/content/configuration/customization/outputformats/_index.en.md +++ b/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 +++ diff --git a/docs/content/configuration/customization/outputformats/_index.pir.md b/docs/content/configuration/customization/outputformats/_index.pir.md index 3a47a2b121..3d8bd37ba0 100644 --- a/docs/content/configuration/customization/outputformats/_index.pir.md +++ b/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 >}} \ No newline at end of file diff --git a/docs/content/configuration/customization/taxonomy.en.md b/docs/content/configuration/customization/taxonomy.en.md index c3e08b75d6..29d7b51fe0 100644 --- a/docs/content/configuration/customization/taxonomy.en.md +++ b/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. diff --git a/docs/content/configuration/customization/taxonomy.pir.md b/docs/content/configuration/customization/taxonomy.pir.md index 6fd4262288..de32b39917 100644 --- a/docs/content/configuration/customization/taxonomy.pir.md +++ b/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 >}} \ No newline at end of file diff --git a/docs/content/configuration/customization/topbar/_index.en.md b/docs/content/configuration/customization/topbar/_index.en.md index 8f89ef4172..f5ac0292c9 100644 --- a/docs/content/configuration/customization/topbar/_index.en.md +++ b/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). diff --git a/docs/content/configuration/customization/topbar/_index.pir.md b/docs/content/configuration/customization/topbar/_index.pir.md index caf2ed7884..6d22c386dc 100644 --- a/docs/content/configuration/customization/topbar/_index.pir.md +++ b/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 >}} \ No newline at end of file diff --git a/docs/content/introduction/releasenotes/7/4.en.md b/docs/content/introduction/releasenotes/7/4.en.md index 5c2c18e4c4..21ba730b89 100644 --- a/docs/content/introduction/releasenotes/7/4.en.md +++ b/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 diff --git a/layouts/partials/version.txt b/layouts/partials/version.txt index 1a7d8ddcc7..da0020e8be 100644 --- a/layouts/partials/version.txt +++ b/layouts/partials/version.txt @@ -1 +1 @@ -7.3.2+ada45be3f20e6f22357d406158e530921283623b \ No newline at end of file +7.3.2+83860202296af0be408eba2a8145c8325403ce04 \ No newline at end of file