From 1df914acdc2fbc2236bb1540f6051f9931878022 Mon Sep 17 00:00:00 2001 From: Andrea Luzzardi Date: Thu, 22 Jul 2021 13:34:53 +0200 Subject: [PATCH] docs: Fix relative URLs, add a CONTRIBUTING.md note Signed-off-by: Andrea Luzzardi --- CONTRIBUTING.md | 14 +++++++++++++- docs/learn/1003-get-started.md | 2 +- docs/learn/1008-aws-cloudformation.md | 4 ++-- 3 files changed, 16 insertions(+), 4 deletions(-) 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