docs: describe linking formats and languages #850

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
 

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 %}}

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 >}}

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.

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 >}}

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.

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 >}}

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
++++

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 >}}

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
 

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.

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
 

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
 

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 `<img>` 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.

layouts/partials/version.txt

@@ -1 +1 @@
-7.3.2+1ebb5451c366e5c592ed18d9b9454804f1d9e624
+7.3.2+b243bacf3408c44998c6007b215305c9e4cfcb6e