diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index a4885223..ec81c8ff 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -85,6 +85,18 @@ Guidelines:
 - Format: Use the imperative mood in the subject line: "If applied, this commit
   will _your subject line here_"
 
+## Docs
+
+### Use relative links to markdown files
+
+Link to markdown files (`[link](../foo.md)`) instead of relative URLs
+(`[link](/foo)`).
+
+The docs compiler will replace file links with relative URLs automatically.
+
+This is to avoid broken links. If a file gets renamed, the compiler will
+catch broken links and throw an error. Relative URLs get broken unnoticed.
+
 ## FAQ
 
 ### How to run the markdown linter locally
@@ -96,6 +108,6 @@ First install `markdownlint-cli`:
 
 Then from the repository root:
 
-```
+```console
 markdownlint -c .markdownlint.yaml docs/**/*.md
 ```
diff --git a/docs/learn/1003-get-started.md b/docs/learn/1003-get-started.md
index 22a98f9b..d5548f98 100644
--- a/docs/learn/1003-get-started.md
+++ b/docs/learn/1003-get-started.md
@@ -121,4 +121,4 @@ dagger output list
 
 ## What's next?
 
-At this point, you have deployed your first application using Dagger and learned some dagger commands. You are now ready to [learn more about how to program Dagger](/learn/102-dev).
+At this point, you have deployed your first application using Dagger and learned some dagger commands. You are now ready to [learn more about how to program Dagger](./1004-first-env.md).
diff --git a/docs/learn/1008-aws-cloudformation.md b/docs/learn/1008-aws-cloudformation.md
index 24e84871..63ef450e 100644
--- a/docs/learn/1008-aws-cloudformation.md
+++ b/docs/learn/1008-aws-cloudformation.md
@@ -18,7 +18,7 @@ The provisioning strategy detailed below follows S3 best practices. However, to
 
 #### Relays
 
-The first thing to consider when developing a plan based on relays is to read their universe reference: it summarizes the expected inputs and their corresponding formats. [Here](/reference/universe/aws/cloudformation) is the Cloudformation one.
+The first thing to consider when developing a plan based on relays is to read their universe reference: it summarizes the expected inputs and their corresponding formats. [Here](../reference/universe/aws/cloudformation.md) is the Cloudformation one.
 
 ## Initialize a Dagger Workspace and Environment
 
@@ -132,7 +132,7 @@ template: """
 
 ##### 2. Cloudformation relay
 
-As our plan relies on [Cloudformation's relay](/reference/universe/aws/cloudformation), let's dissect the expected inputs by gradually incorporating them into our plan.
+As our plan relies on [Cloudformation's relay](../reference/universe/aws/cloudformation.md), let's dissect the expected inputs by gradually incorporating them into our plan.
 
 ```shell
 dagger doc alpha.dagger.io/aws/cloudformation