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