From 0adbe0028ead66b763d42b65e724a86b60f0ac9e Mon Sep 17 00:00:00 2001
From: Mike Thomas <78363703+mike-j-thomas@users.noreply.github.com>
Date: Tue, 31 Aug 2021 10:09:37 +0900
Subject: [PATCH] Handbook - How to add a link to Fleet docs (#1856)

* Handbook - Adding links to Fleet docs

Instructions for how to add, and fix links in the Fleet docs.

* Update handbook/README.md

* Update handbook/README.md

typo fix.

* Update handbook/README.md

Added paragraph about linking to other docs pages using relative paths.

* Update handbook/README.md
---
 handbook/README.md | 28 ++++++++++++++++++++++++++++
 1 file changed, 28 insertions(+)

diff --git a/handbook/README.md b/handbook/README.md
index af962912bf..199d9c03ef 100644
--- a/handbook/README.md
+++ b/handbook/README.md
@@ -105,6 +105,33 @@ A browser compatibility check of [fleetdm.com](https://fleetdm.com/) should be c
 - Document any issues in GitHub as a [bug report](https://github.com/fleetdm/fleet/issues/new?assignees=&labels=bug%2C%3Areproduce&template=bug-report.md&title=), and assign for fixing.
 - If in doubt about anything regarding design or layout, please reach out to the Design team.
 
+
+### Fleet docs
+
+#### Adding a link to Fleet docs
+You can link documentation pages to each other using relative paths. For example, in `docs/1-Using-Fleet/1-Fleet-UI.md`, you can link to `docs/1-Using-Fleet/9-Permissions.md` by writing `[permissions](./9-Permissions.md)`. This will be automatically transformed into the appropriate URL for `fleetdm.com/docs`.
+
+However, the `fleetdm.com/docs` compilation process does not account for relative links to directories **outside** of `/docs`.
+Therefore, when adding a link to Fleet docs, it is important to always use the absolute file path.
+
+#### Linking to a location on GitHub
+When adding a link to a location on GitHub that is outside of `/docs`, be sure to use the canonical form of the URL.
+
+To do this, navigate to the file's location on GitHub, and press "y" to transform the URL into its canonical form.
+
+#### How to fix a broken link
+For instances in which a broken link is discovered on fleetdm.com, check if the link is a relative link to a directory outside of `/docs`. 
+
+An example of a link that lives outside of `/docs` is:
+
+```
+../../tools/app/prometheus
+```
+
+If the link lives outside `/docs`, head to the file's location on GitHub (in this case, [https://github.com/fleetdm/fleet/blob/main/tools/app/prometheus.yml)](https://github.com/fleetdm/fleet/blob/main/tools/app/prometheus.yml)), and press "y" to transform the URL into its canonical form ([https://github.com/fleetdm/fleet/blob/194ad5963b0d55bdf976aa93f3de6cabd590c97a/tools/app/prometheus.yml](https://github.com/fleetdm/fleet/blob/194ad5963b0d55bdf976aa93f3de6cabd590c97a/tools/app/prometheus.yml)). Replace the relative link with this link in the markdown file.
+
+> Note that the instructions above also apply to adding links in the Fleet handbook.
+
 ### Style and grammar guidelines
 
 #### How to write headings & subheadings
@@ -123,6 +150,7 @@ or
 
 > Osquery and Fleet provide structured, convenient access to information about your devices.
 
+
 ### About the handbook
 #### Why bother?
 The Fleet handbook is inspired by (and heavily influenced by) the [GitLab team handbook](https://about.gitlab.com/handbook/about/).  It shares the same [advantages](https://about.gitlab.com/handbook/about/#advantages) and will probably undergo a similar [evolution](https://about.gitlab.com/handbook/ceo/#evolution-of-the-handbook).