add docs on alternative link syntax (#638)

This adds a small section to the markdown link section of the docs to also outline the `[[ link ]]` syntax that is supported in markdown texts that are rendered to html.

Closes #524.

Reviewed-on: https://codeberg.org/Codeberg/Documentation/pulls/638
Reviewed-by: Robert Wolff <mahlzahn@posteo.de>
Co-authored-by: Bastian Greshake Tzovaras <bgreshake@googlemail.com>
Co-committed-by: Bastian Greshake Tzovaras <bgreshake@googlemail.com>

content/markdown/using-links.md

@@ -72,3 +72,39 @@ For example, you can link to the heading on "Bold" in the article "Introduction
 This is rendered as:
 
 [Link to the bold section](/markdown/introduction-to-markdown/#bold)
+
+## Alternative link syntax
+
+The link parser used in Forgejo can also work with the _double square brackets_ syntax in issues and other places where markdown is rendered:
+
+```markdown
+[[https://codeberg.org/]]
+```
+
+will get rendered as <https://codeberg.org>.
+
+You can also give a link description, as with the regular markdown syntax:
+
+```markdown
+[[This is a link to Codeberg|https://codeberg.org]]
+```
+
+will be rendered as [This is a link to Codeberg](https://codeberg.org).
+
+This also works for relative links:
+
+```markdown
+[[This is a link to the markdown section of the docs|/markdown/]]
+```
+
+will be rendered as [This is a link to the markdown section of the docs](/markdown/).
+
+{% admonition "warning" %}
+
+Be aware that this syntax is 'inverted' compared to the one that [MediaWiki](https://www.mediawiki.org) uses (i.e. `[[https://example.com|link title]]`).
+For compatibility reasons, Forgejo can also convert those links, but only if full paths are specified.
+
+This means `[[https://example.com|link title]]` will also be converted to "[link title](https://example.com)".
+But `[[example.com|link title]]` will result in a broken link!
+
+{% endadmonition %}