docs: describe linking formats and languages #850

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

@@ -0,0 +1,66 @@
++++
+categories = ["explanation"]
+description = "How to apply effects to your images"
+frontmatter = ["imageEffects"]
+title = "Image Effects"
+weight = 3
++++
+
+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.
+
+The default image effects shipped with the theme are
+
+| Name          | Description                                                       |
+| ------------- | ----------------------------------------------------------------- |
+| border        | Draws a light thin border around the image                        |
+| dataurl       | if the linked image points to a resource, it is converted to a base64 encoded dataurl |
+| inlinecontent | if the linked image points to a SVG resource, 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 |
+| lazy          | Lets the image be lazy loaded                                     |
+| lightbox      | The image will be clickable to show it enlarged                   |
+| shadow        | Draws a shadow around the image to make it appear hovered/glowing |
+
+One way to use them is to add them as URL query parameter to each individually linked image.
+
+This can become cumbersome to be done consistently for the whole site. Instead, you can [configure the defaults](configuration/customization/imageeffects) 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` `imageEffects` defaults to
+
+{{< multiconfig >}}
+[imageEffects]
+  border = false
+  dataurl = false
+  inlinecontent = false
+  lazy = true
+  lightbox = true
+  shadow = 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 >}}
+[imageEffects]
+  lazy = false
+{{< /multiconfig >}}
+
+Or by explicitly override settings by URL query parameter
+
+````md {title="URL"}
+![Minion](https://octodex.github.com/images/minion.png?lazy=true&lightbox=false)
+````
+
+The settings applied to the above image would be
+
+{{< multiconfig >}}
+border = true
+dataurl = false
+inlinecontent = false
+lazy = true
+lightbox = false
+shadow = false
+{{< /multiconfig >}}

docs/content/authoring/linking/imageeffects.pir.md

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

docs/content/authoring/linking/linkeffects.en.md

@@ -0,0 +1,54 @@
++++
+categories = ["explanation"]
+description = "How to apply effects to your links"
+frontmatter = ["linkEffects"]
+title = "Link Effects"
+weight = 2
++++
+
+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/linking/linkeffects.pir.md

@@ -0,0 +1,8 @@
++++
+categories = ["explanation"]
+description = "How to apply effects to your links"
+frontmatter = ["linkEffects"]
+title = "Link Effects"
+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 >}}