From ada42d7023ad796ecb3329fdf63ae90bed45eb64 Mon Sep 17 00:00:00 2001
From: Tobias Killer <tokidev@posteo.de>
Date: Thu, 8 Apr 2021 11:25:36 +0200
Subject: [PATCH 1/2] Add Markdown convention rule about full reference links
---
developer/general/doc-guidelines.md | 18 ++++++++++++++++++
1 file changed, 18 insertions(+)
diff --git a/developer/general/doc-guidelines.md b/developer/general/doc-guidelines.md
index 320fc42b..04529cc8 100644
--- a/developer/general/doc-guidelines.md
+++ b/developer/general/doc-guidelines.md
@@ -350,6 +350,24 @@ When making contributions, please try to observe the following style conventions
The `#` symbol preceding each comment is ambiguous with a root command prompt.
Instead, put your comments *outside* of the code block in normal prose.
+* Use full reference links like this
+
+ ```
+ Visit [our website][website].
+
+ [website]: https://example.com/
+ ```
+
+ over shortcut reference links and collapsed reference links like these
+
+ ```
+ Visit [our website].
+ Visit [our website][].
+
+ [our website]: https://example.com/
+ ```
+
+ * Rationale: This makes translations into other languages with different linguistic cases easier.
([This][md] is a great source for learning about Markdown.)
From 7250daea53803d9c9bdbac5eff9069cb19edada7 Mon Sep 17 00:00:00 2001
From: Tobias Killer <tokidev@posteo.de>
Date: Fri, 9 Apr 2021 09:30:39 +0200
Subject: [PATCH 2/2] Rewrite Markdown convention rule: Do not allow reference
links
---
developer/general/doc-guidelines.md | 20 ++------------------
1 file changed, 2 insertions(+), 18 deletions(-)
diff --git a/developer/general/doc-guidelines.md b/developer/general/doc-guidelines.md
index 04529cc8..c2d194f0 100644
--- a/developer/general/doc-guidelines.md
+++ b/developer/general/doc-guidelines.md
@@ -350,24 +350,8 @@ When making contributions, please try to observe the following style conventions
The `#` symbol preceding each comment is ambiguous with a root command prompt.
Instead, put your comments *outside* of the code block in normal prose.
-* Use full reference links like this
-
- ```
- Visit [our website][website].
-
- [website]: https://example.com/
- ```
-
- over shortcut reference links and collapsed reference links like these
-
- ```
- Visit [our website].
- Visit [our website][].
-
- [our website]: https://example.com/
- ```
-
- * Rationale: This makes translations into other languages with different linguistic cases easier.
+* Use non-reference-style links like `[website](https://example.com/)`.
+ Do *not* use reference links like `[website][example]`, `[website][]` or `[website]`.
([This][md] is a great source for learning about Markdown.)