docs: ensure check-docs script checks internal header links

markdown-check-link doesn't check internal header links. This is a known issue (tcort/markdown-link-check#65). We therefore add a new tool to check for internal links and limit markdown-check-link to external links. The new tool is from the remark family of markdown tools and expects anchor links to not include any special characters so we also had to make appropriate changes to the docs generator functions. Finally, this commit fixes broken links discovered because of these fixes.
garden-io · Oct 4, 2019 · 1f7db54 · 1f7db54
1 parent 71e204d
commit 1f7db54
Show file tree

Hide file tree

Showing 28 changed files with 1,547 additions and 208 deletions.
diff --git a/bin/check-docs b/bin/check-docs
@@ -1,20 +1,35 @@
 #!/bin/bash -e
 
-# Linter before git check so we can lint docs even if they are 'dirty'
-
 # Use "|| true" so we don't exit on empty
 modified_docs=$(git diff --name-status master docs README.md) || true
 modified_examples=$(git diff --name-status master examples | grep "examples.*\README.md$") || true
 
+check_relative_links() {
+  echo $1 | xargs -n 1 ./node_modules/.bin/remark --use validate-links --frail --quiet --no-stdout
+}
+
+check_external_links() {
+  # markdown-link-check is configured to ignore relative links
+  echo $1 | xargs -n 1 ./node_modules/.bin/markdown-link-check --config markdown-link-check-config.json
+}
+
 # Only check links if docs or examples were modified
 if !([ -z "$modified_docs" ] && [ -z "$modified_examples" ]); then
-  # Using xargs to exit 1 if link is broken, see: https://github.com/tcort/markdown-link-check/issues/57
+  docs=$(find docs -name '*.md' -type f)
+  examples=$(find examples -name 'README.md' -type f -not -path "*/.garden/*" -not -path "*/node_modules/*")
+  readme=./README.md
+
   # Check docs
-  find docs -name '*.md' -type f | xargs -n 1 ./node_modules/.bin/markdown-link-check --config markdown-link-check-config.json
+  check_external_links "$docs"
+  check_relative_links "$docs"
+
   # Check examples
-  find examples -name 'README.md' -type f -not -path "*/.garden/*" -not -path "*/node_modules/*" | xargs -n 1 ./node_modules/.bin/markdown-link-check --config markdown-link-check-config.json
+  check_external_links "$examples"
+  check_relative_links "$examples"
+
   # Check README.md
-  find . -name 'README.md' -type f  -maxdepth 1 | xargs -n 1 ./node_modules/.bin/markdown-link-check --config markdown-link-check-config.json
+  check_external_links "$readme"
+  check_relative_links "$readme"
 fi
 
 # Needs to generate clean docs before we can validate they are up to date

diff --git a/docs/examples/demo-project.md b/docs/examples/demo-project.md
@@ -7,7 +7,7 @@ In what follows you'll learn how to:
 * [Configure the project](#project-wide-configuration)
 * [Configure individual modules](#module-configuration)
 * [Deploy the project locally](#deploying)
-* [Have the services communicate with one another](#inter-service-communication)
+* [Have the services communicate with one another](#communication-between-services)
 * [Manage service dependencies](#dependencies)
 * [Test services](#testing)
 
@@ -76,7 +76,7 @@ Above, we've specified the name of our project and configured it to use the `loc
 
 ## Module configuration
 
-Now, let's turn to our services. Services live inside [modules](../reference/glossary.md#Module), and each module has its own `garden.yml` configuration file. You can read more about the difference between services and modules [here](../basics/stack-graph.md#structure).
+Now, let's turn to our services. Services live inside [modules](../reference/glossary.md#Module), and each module has its own `garden.yml` configuration file. You can read more about the difference between services and modules [here](../basics/stack-graph.md#structure-and-terminology).
 
 We'll start with the module for the `frontend`:
 

diff --git a/docs/examples/using-garden-in-ci.md b/docs/examples/using-garden-in-ci.md
@@ -9,7 +9,7 @@ In this guide we'll demonstrate how Garden can fit into your continuous integrat
 
 To use Garden in your CI pipeline you need the following:
 
-1. A Garden project, [configured to deploy to a remote cluster](#configure-garden-for-remote-environments).
+1. A Garden project, [configured to deploy to a remote cluster](#configure-remote-environments).
 2. A [Kubectl context](#configure-the-kubectl-context) on the CI agent that's configured for the remote cluster.
 
 For the purposes of this example we'll be using [CircleCI](https://circleci.com) and deploying to a Google Kubernetes Engine (GKE) cluster. However, the instructions below can easily be applied to other CI platforms and cloud providers.

diff --git a/docs/reference/config.md b/docs/reference/config.md
@@ -4,7 +4,7 @@ title: Config Files Reference
 
 # garden.yml reference
 
-Below is the schema reference for the [Project](#project-configuration) and [Module](#module-configuration) `garden.yml` configuration files. For an introduction to configuring a Garden project,
+Below is the schema reference for the [Project](#project-configuration-keys) and [Module](#module-configuration-keys) `garden.yml` configuration files. For an introduction to configuring a Garden project,
 please look at our [configuration guide](../using-garden/configuration-files.md).
 
 The reference is divided into four sections. The [first section](#project-configuration-keys) lists and describes the available schema keys for the project level configuration, and the [second section](#project-yaml-schema) contains the project level YAML schema.
@@ -94,7 +94,7 @@ DEPRECATED - Please use the top-level `providers` field instead, and if needed u
 
 ### `environmentDefaults.providers[].name`
 
-[environmentDefaults](#environmentdefaults) > [providers](#environmentdefaults.providers[]) > name
+[environmentDefaults](#environmentdefaults) > [providers](#environmentdefaultsproviders) > name
 
 The name of the provider plugin to use.
 
@@ -115,7 +115,7 @@ environmentDefaults:
 
 ### `environmentDefaults.providers[].environments[]`
 
-[environmentDefaults](#environmentdefaults) > [providers](#environmentdefaults.providers[]) > environments
+[environmentDefaults](#environmentdefaults) > [providers](#environmentdefaultsproviders) > environments
 
 If specified, this provider will only be used in the listed environments. Note that an empty array effectively disables the provider. To use a provider in all environments, omit this field.
 
@@ -334,7 +334,7 @@ DEPRECATED - Please use the top-level `providers` field instead, and if needed u
 
 ### `environments[].providers[].name`
 
-[environments](#environments) > [providers](#environments[].providers[]) > name
+[environments](#environments) > [providers](#environmentsproviders) > name
 
 The name of the provider plugin to use.
 
@@ -352,7 +352,7 @@ environments:
 
 ### `environments[].providers[].environments[]`
 
-[environments](#environments) > [providers](#environments[].providers[]) > environments
+[environments](#environments) > [providers](#environmentsproviders) > environments
 
 If specified, this provider will only be used in the listed environments. Note that an empty array effectively disables the provider. To use a provider in all environments, omit this field.
 
@@ -592,7 +592,7 @@ build:
 
 ### `build.dependencies[].name`
 
-[build](#build) > [dependencies](#build.dependencies[]) > name
+[build](#build) > [dependencies](#builddependencies) > name
 
 Module name to build ahead of this module.
 
@@ -602,7 +602,7 @@ Module name to build ahead of this module.
 
 ### `build.dependencies[].copy[]`
 
-[build](#build) > [dependencies](#build.dependencies[]) > copy
+[build](#build) > [dependencies](#builddependencies) > copy
 
 Specify one or more files or directories to copy from the built dependency to this module.
 
@@ -612,7 +612,7 @@ Specify one or more files or directories to copy from the built dependency to th
 
 ### `build.dependencies[].copy[].source`
 
-[build](#build) > [dependencies](#build.dependencies[]) > [copy](#build.dependencies[].copy[]) > source
+[build](#build) > [dependencies](#builddependencies) > [copy](#builddependenciescopy) > source
 
 POSIX-style path or filename of the directory or file(s) to copy to the target.
 
@@ -622,7 +622,7 @@ POSIX-style path or filename of the directory or file(s) to copy to the target.
 
 ### `build.dependencies[].copy[].target`
 
-[build](#build) > [dependencies](#build.dependencies[]) > [copy](#build.dependencies[].copy[]) > target
+[build](#build) > [dependencies](#builddependencies) > [copy](#builddependenciescopy) > target
 
 POSIX-style path or filename to copy the directory or file(s).
 

diff --git a/docs/reference/glossary.md b/docs/reference/glossary.md
@@ -34,7 +34,7 @@ For a comprehensive list of providers available in Garden, check out the [Refere
 
 #### Service
 The unit of deployment in Garden. Services are defined in their parent [module](#module)'s `garden.yml`, each
-exposing [one or more ingress endpoints](./config.md#container).
+exposing [one or more ingress endpoints](./module-types/container.md#servicesingresses).
 
 Services may depend on services defined in other modules, in which case those services will be deployed first, and
 their deployment output made available to the requiring service's deploy step.