From ada42d7023ad796ecb3329fdf63ae90bed45eb64 Mon Sep 17 00:00:00 2001 From: Tobias Killer Date: Thu, 8 Apr 2021 11:25:36 +0200 Subject: [PATCH] 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.)