From ada42d7023ad796ecb3329fdf63ae90bed45eb64 Mon Sep 17 00:00:00 2001 From: Tobias Killer 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 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.)