From 0fbf050d5dd9ff0da80c30495cf6c20aa1f73bc5 Mon Sep 17 00:00:00 2001
From: RichardJJG <rijohnson@vmware.com>
Date: Tue, 24 Aug 2021 14:11:24 +0100
Subject: [PATCH] Add link styling rules (#4155)

* Add link styling rules

* Update docs/help/contributor/style-guide/style-and-formatting.md

Co-authored-by: Samia Nneji <snneji@vmware.com>

* Moved rule further up

Co-authored-by: Samia Nneji <snneji@vmware.com>
---
 .../style-guide/style-and-formatting.md       | 27 +++++++++++++++++--
 1 file changed, 25 insertions(+), 2 deletions(-)

diff --git a/docs/help/contributor/style-guide/style-and-formatting.md b/docs/help/contributor/style-guide/style-and-formatting.md
index d89dfc798..14f1f3001 100644
--- a/docs/help/contributor/style-guide/style-and-formatting.md
+++ b/docs/help/contributor/style-guide/style-and-formatting.md
@@ -30,13 +30,36 @@
 
 ## Links
 
-### Make links descriptive
+### Describe what the link targets
 
 |:white_check_mark: Correct                                     |:no_entry: Incorrect
 |---------------------------------------|------
 |For an explanation of what makes a good hyperlink, see this [this article](https://medium.com/@heyoka/Correctnt-use-click-here-f32f445d1021).| See this article [here](https://medium.com/@heyoka/Correctnt-use-click-here-f32f445d1021).
 
-<!-- Add rule here, see https://github.com/knative/docs/issues/4034 -->
+### Write links in Markdown, not HTML
+
+|:white_check_mark: Correct                                     |:no_entry: Incorrect|
+|---------------------------------------|------|
+|`[Kafka Broker](../kafka-broker/README.md)`|`<a href="../kafka-broker/README.md">Kafka Broker</a>`|
+|`[Kafka Broker](../kafka-broker/README.md){target=_blank}`|`<a href="../kafka-broker/README.md" target="_blank">Kafka Broker</a>`|
+
+### Include the .md extension in internal links
+
+|:white_check_mark: Correct                                     |:no_entry: Incorrect|
+|---------------------------------------|------|
+|`[Setting up a custom domain](../serving/using-a-custom-domain.md)`|`[Setting up a custom domain](../serving/using-a-custom-domain)`|
+
+### Link to files, not folders
+
+|:white_check_mark: Correct                                     |:no_entry: Incorrect|
+|---------------------------------------|------|
+|`[Kafka Broker](../kafka-broker/README.md)`|`[Kafka Broker](../kafka-broker/)`|
+
+### Ensure the letter case is correct
+
+|:white_check_mark: Correct                                     |:no_entry: Incorrect|
+|---------------------------------------|------|
+|`[Kafka Broker](../kafka-broker/README.md)`|`[Kafka Broker](../kafka-broker/readme.md)`|
 
 ## Formatting