From 59414a1b792e2ad40d66ac9c49c9dd8dd0becb39 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=B6ren=20Weber?= Date: Sat, 8 Feb 2025 18:53:53 +0100 Subject: [PATCH] docs: describe linking formats and languages #850 --- .../authoring/frontmatter/linking/index.en.md | 2 +- docs/content/authoring/linking/_index.en.md | 9 +++++ docs/content/authoring/linking/_index.pir.md | 8 +++++ .../{ => linking}/imageeffects.en.md | 2 +- .../{ => linking}/imageeffects.pir.md | 2 +- .../authoring/{ => linking}/linkeffects.en.md | 4 +-- .../{ => linking}/linkeffects.pir.md | 4 +-- docs/content/authoring/linking/pages.en.md | 6 ++++ docs/content/authoring/linking/pages.pir.md | 7 ++++ docs/content/authoring/markdown.en.md | 4 +-- .../configuration/content/linking/index.en.md | 8 +++++ .../customization/imageeffects.en.md | 2 +- .../customization/linkeffects.en.md | 2 +- .../introduction/releasenotes/7/4.en.md | 34 +++++++++++++------ layouts/partials/version.txt | 2 +- 15 files changed, 73 insertions(+), 23 deletions(-) create mode 100644 docs/content/authoring/linking/_index.en.md create mode 100644 docs/content/authoring/linking/_index.pir.md rename docs/content/authoring/{ => linking}/imageeffects.en.md (99%) rename docs/content/authoring/{ => linking}/imageeffects.pir.md (93%) rename docs/content/authoring/{ => linking}/linkeffects.en.md (97%) rename docs/content/authoring/{ => linking}/linkeffects.pir.md (59%) create mode 100644 docs/content/authoring/linking/pages.en.md create mode 100644 docs/content/authoring/linking/pages.pir.md diff --git a/docs/content/authoring/frontmatter/linking/index.en.md b/docs/content/authoring/frontmatter/linking/index.en.md index 38d78c5d3e..54b6e5dcd2 100644 --- a/docs/content/authoring/frontmatter/linking/index.en.md +++ b/docs/content/authoring/frontmatter/linking/index.en.md @@ -11,7 +11,7 @@ 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). +To set default values for all links, use [link effects](authoring/linking/linkeffects). For example, this will open links in the same tab diff --git a/docs/content/authoring/linking/_index.en.md b/docs/content/authoring/linking/_index.en.md new file mode 100644 index 0000000000..03abeafbf0 --- /dev/null +++ b/docs/content/authoring/linking/_index.en.md @@ -0,0 +1,9 @@ ++++ +alwaysopen = false +categories = ["reference"] +description = "How to link your content" +title = "Linking" +weight = 5 ++++ + +{{% children containerstyle="div" style="h2" description=true %}} diff --git a/docs/content/authoring/linking/_index.pir.md b/docs/content/authoring/linking/_index.pir.md new file mode 100644 index 0000000000..ea5871b01c --- /dev/null +++ b/docs/content/authoring/linking/_index.pir.md @@ -0,0 +1,8 @@ ++++ +alwaysopen = false +categories = ["reference"] +description = "How to link your content" +title = "Linking" +weight = 5 ++++ +{{< piratify >}} \ No newline at end of file diff --git a/docs/content/authoring/imageeffects.en.md b/docs/content/authoring/linking/imageeffects.en.md similarity index 99% rename from docs/content/authoring/imageeffects.en.md rename to docs/content/authoring/linking/imageeffects.en.md index 864c8fe984..7948dc1e7b 100644 --- a/docs/content/authoring/imageeffects.en.md +++ b/docs/content/authoring/linking/imageeffects.en.md @@ -3,7 +3,7 @@ categories = ["explanation"] description = "How to apply effects to your images" frontmatter = ["imageEffects"] title = "Image Effects" -weight = 6 +weight = 3 +++ The theme offers [effects](authoring/markdown#image-effects) for your linked images. diff --git a/docs/content/authoring/imageeffects.pir.md b/docs/content/authoring/linking/imageeffects.pir.md similarity index 93% rename from docs/content/authoring/imageeffects.pir.md rename to docs/content/authoring/linking/imageeffects.pir.md index 31c76116c5..fccce84ea0 100644 --- a/docs/content/authoring/imageeffects.pir.md +++ b/docs/content/authoring/linking/imageeffects.pir.md @@ -3,6 +3,6 @@ categories = ["explanation"] description = "How to apply effects to your images" frontmatter = ["imageEffects"] title = "Image Effects" -weight = 6 +weight = 3 +++ {{< piratify >}} \ No newline at end of file diff --git a/docs/content/authoring/linkeffects.en.md b/docs/content/authoring/linking/linkeffects.en.md similarity index 97% rename from docs/content/authoring/linkeffects.en.md rename to docs/content/authoring/linking/linkeffects.en.md index e3d4004323..d81772ecf4 100644 --- a/docs/content/authoring/linkeffects.en.md +++ b/docs/content/authoring/linking/linkeffects.en.md @@ -1,9 +1,9 @@ +++ categories = ["explanation"] -description = "How to apply graphical effects to your links" +description = "How to apply effects to your links" frontmatter = ["linkEffects"] title = "Link Effects" -weight = 5 +weight = 2 +++ The theme offers [effects](authoring/markdown#link-effects) for your linked links. diff --git a/docs/content/authoring/linkeffects.pir.md b/docs/content/authoring/linking/linkeffects.pir.md similarity index 59% rename from docs/content/authoring/linkeffects.pir.md rename to docs/content/authoring/linking/linkeffects.pir.md index 09e29c8777..2839f64052 100644 --- a/docs/content/authoring/linkeffects.pir.md +++ b/docs/content/authoring/linking/linkeffects.pir.md @@ -1,8 +1,8 @@ +++ categories = ["explanation"] -description = "How to apply graphical effects to your links" +description = "How to apply effects to your links" frontmatter = ["linkEffects"] title = "Link Effects" -weight = 5 +weight = 2 +++ {{< piratify >}} \ No newline at end of file diff --git a/docs/content/authoring/linking/pages.en.md b/docs/content/authoring/linking/pages.en.md new file mode 100644 index 0000000000..4c7062691a --- /dev/null +++ b/docs/content/authoring/linking/pages.en.md @@ -0,0 +1,6 @@ ++++ +categories = ["explanation"] +description = "How to link to pages and resources" +title = "Pages & Resources" +weight = 1 ++++ diff --git a/docs/content/authoring/linking/pages.pir.md b/docs/content/authoring/linking/pages.pir.md new file mode 100644 index 0000000000..087b51920e --- /dev/null +++ b/docs/content/authoring/linking/pages.pir.md @@ -0,0 +1,7 @@ ++++ +categories = ["explanation"] +description = "How to link to pages and resources" +title = "Pages & Resources" +weight = 1 ++++ +{{< piratify >}} \ No newline at end of file diff --git a/docs/content/authoring/markdown.en.md b/docs/content/authoring/markdown.en.md index f3c8d490bc..97e669a47b 100644 --- a/docs/content/authoring/markdown.en.md +++ b/docs/content/authoring/markdown.en.md @@ -683,7 +683,7 @@ That's some more text with a footnote.[^someid] ### Link Effects -{{% badge color="#7dc903" icon="fa-fw fas fa-puzzle-piece" %}}Relearn{{% /badge %}} This theme allows additional non-standard formatting by setting query parameter at the end of the URL. See the [link effects docs](authoring/linkeffects) for a detailed example and how to configure it. +{{% badge color="#7dc903" icon="fa-fw fas fa-puzzle-piece" %}}Relearn{{% /badge %}} This theme allows additional non-standard formatting by setting query parameter at the end of the URL. See the [link effects docs](authoring/linking/linkeffects) for a detailed example and how to configure it. #### Target @@ -753,7 +753,7 @@ Images can also be linked by reference ID to later define the URL location. This ### Image Effects -{{% badge color="#7dc903" icon="fa-fw fas fa-puzzle-piece" %}}Relearn{{% /badge %}} This theme allows additional non-standard formatting by setting query parameter at the end of the image URL. See the [image effects docs](authoring/imageeffects) for a detailed example and how to configure it. +{{% badge color="#7dc903" icon="fa-fw fas fa-puzzle-piece" %}}Relearn{{% /badge %}} This theme allows additional non-standard formatting by setting query parameter at the end of the image URL. See the [image effects docs](authoring/linking/imageeffects) for a detailed example and how to configure it. #### Resizing diff --git a/docs/content/configuration/content/linking/index.en.md b/docs/content/configuration/content/linking/index.en.md index 296a1f2fe1..d216ea1e98 100644 --- a/docs/content/configuration/content/linking/index.en.md +++ b/docs/content/configuration/content/linking/index.en.md @@ -21,6 +21,14 @@ For the file system scenario, you are not allowed to change this value. disableExplicitIndexURLs = true {{< /multiconfig >}} +## Legacy Cross-Language Links + +You can link to pages of different languages by appending the `lang` query parameter with the language code to the URL, e.g. `/my-page?lang=pir`. + +In previous releases of the theme you had to prepend the language code to the URL, e.g. `/pir/my-page` to achieve this. + +If you still need the old behavior, you can set `enableLegacyLanguageLinks=true` in your `hugo.toml`. Note that this legacy feature may be removed in the future. + ## Patching the `relref` Shortcode {{% badge style="cyan" icon="gears" title=" " %}}Option{{% /badge %}} While the usage of `relref` is obsolete and discouraged by Hugo for a while, existing installations may still use it. diff --git a/docs/content/configuration/customization/imageeffects.en.md b/docs/content/configuration/customization/imageeffects.en.md index a949216695..baac43324b 100644 --- a/docs/content/configuration/customization/imageeffects.en.md +++ b/docs/content/configuration/customization/imageeffects.en.md @@ -8,7 +8,7 @@ weight = 4 This page shows you, how to configure custom [image effects](authoring/markdown#image-effects) on top of existing ones. -This setting can also [be overridden by your front matter](authoring/imageeffects). +This setting can also [be overridden by your front matter](authoring/linking/imageeffects). If you don't configure anything in your `hugo.toml`, the image effects default to diff --git a/docs/content/configuration/customization/linkeffects.en.md b/docs/content/configuration/customization/linkeffects.en.md index 95c3765e02..2fc24b33a0 100644 --- a/docs/content/configuration/customization/linkeffects.en.md +++ b/docs/content/configuration/customization/linkeffects.en.md @@ -8,7 +8,7 @@ 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). +This setting can also [be overridden by your front matter](authoring/linking/linkeffects). If you don't configure anything in your `hugo.toml`, the link effects default to diff --git a/docs/content/introduction/releasenotes/7/4.en.md b/docs/content/introduction/releasenotes/7/4.en.md index 6e6c33ae4b..a5a992cd48 100644 --- a/docs/content/introduction/releasenotes/7/4.en.md +++ b/docs/content/introduction/releasenotes/7/4.en.md @@ -10,6 +10,14 @@ weight = -4 ### Change +- {{% badge style="note" title=" " %}}Change{{% /badge %}} The way you [link to pages in a different language](authoring/linking/pages) has changed. Until now this was an undocumented feature. + + Previously you could prepend an URL with the language code, e.g. `/pir/my-page` to link to pages of other languages. This could cause problems if you have a page with the same name as the language code on the top level of your page structure. + + Now you have to set the query parameter `lang` to the language code, e.g. `/my-page?lang=pir`. + + As this was previously undocumented, most projects will not be affected. If you [still need the old behavior](configuration/content/linking#legacy-cross-language-links), you can set `enableLegacyLanguageLinks=true` in your `hugo.toml`. + - {{% 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` parameter instead. You don't need to change anything as the old parameter still works but may generate warnings. @@ -20,26 +28,30 @@ weight = -4 - {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} If [`link.errorlevel` is configured](authoring/frontmatter/linking/#enabling-link-and-image-link-warnings), now also page references will be checked for existence. +- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} You can now [configure an ignore list](authoring/frontmatter/linking/#ignoring-false-negatives) of regular expressions for addresses that should be ignored if an errorlevel test fails. This is configured by setting `errorignore=[]` globally in your `hugo.toml` for all errorlevel checks. + + This helps to remove false negatives while still benefitting from the check for all other addresses. + - {{% 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 and image links, page references and [buttons](shortcodes/button). -- {{% 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. +- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} You can now [link to different output formats](authoring/linking/pages) of a page by adding a query parameter. - With that you currently can specify + For example to link to the print format of a page, write `/my-page?format=print`. - - a link target individually for each link - - that a link should result in a file download in your browser - -- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} You can now [configure an ignore list](authoring/frontmatter/linking/#ignoring-false-negatives) of addresses that should be ignored if an errorlevel test fails. This is configured by setting `errorignore=[]` globally in your `hugo.toml` for all errorlevel checks. - - This helps to remove false negatives while still benefitting from the check for all other addresses. - -- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} There are two new [image effects](authoring/imageeffects) that are usable if the linked image points to a resource: +- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} There are two new [image effects](authoring/linking/imageeffects) that are usable if the linked image points to a resource: - **dataurl**: resource is converted to a base64 encoded dataurl - **inlinecontent**: in case of SVG resources, the content will be used instead of an `` element, this is useful for applying additional CSS styles to the elements inside of the SVG which is otherwise impossible +- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} This release introduces [link effects](authoring/linking/linkeffects) which work similar to [image effects](authoring/linking/imageeffects) and can be set as query parameter on any link. + + With that you currently can specify + + - **target**: set a link target individually for each link + - **download**: a click on the link should result in a file download instead of a navigation + - {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} The theme supports the new [`source` output format](configuration/sitemanagement/outputformats/#source-support) which behaves similar in configuration as the `markdown` output format but allows the original Markdown source including the front matter of a page to be viewed. You can see this in action on the above linked page, accessible by clicking the {{% button style="transparent" icon="code" %}}{{% /button %}} topbar button. @@ -56,6 +68,6 @@ weight = -4 - {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} Table headers are sticky now. -- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} The themes documentation has been moved from `exampleSite` to `docs` to make place for a [brand new exampleSite](https://mcshelby.github.io/hugo-theme-relearn/exampleSite/about/index.html). +- {{% badge style="info" icon="plus-circle" title=" " %}}New{{% /badge %}} The themes documentation has been moved from `exampleSite` to `docs` to make place for a brand new exampleSite. Welcome on board the [The Purple Pulpo](https://mcshelby.github.io/hugo-theme-relearn/exampleSite/about/index.html)! This was done because the docs contained to much docs specific configuration and quirks. The new exampleSite is meant as a starting template for your own project with minimal initial configuration. diff --git a/layouts/partials/version.txt b/layouts/partials/version.txt index 44bf3fe347..b58dad1a77 100644 --- a/layouts/partials/version.txt +++ b/layouts/partials/version.txt @@ -1 +1 @@ -7.3.2+1ebb5451c366e5c592ed18d9b9454804f1d9e624 \ No newline at end of file +7.3.2+b243bacf3408c44998c6007b215305c9e4cfcb6e \ No newline at end of file