From 7cfd905bd48aedb235e4928d79e1aad364eb00dd Mon Sep 17 00:00:00 2001
From: Bastian Greshake Tzovaras <bgreshake@googlemail.com>
Date: Fri, 11 Jul 2025 21:09:46 +0200
Subject: [PATCH] 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 | 36 +++++++++++++++++++++++++++++++++
 1 file changed, 36 insertions(+)

diff --git a/content/markdown/using-links.md b/content/markdown/using-links.md
index 486df7d..34cc363 100644
--- a/content/markdown/using-links.md
+++ b/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 %}