Lint markdown files for broken links. (#497)

## Ticket

Resolves #490

## Changes

* Add a lint `make` target for markdown files. Add a linter that checks
for broken links.
* Fix broken link in markdown files found by this linter.

## Context for reviewers

PLEASE: double check the fixed links to ensure I found the right one. 🙂 

This linter only checks broken links. There are other markdown linters
we can consider adding should the need arise. This linter will be run
when running the specific make command `make infra-lint-markdown` as
well as the general lint command `make infra-lint`. Therefore, it will
also be picked up as part of the CI pipeline which runs all the linters.

For the action, I largely copied the action used in
[GoogleChrome](https://github.com/GoogleChrome/lighthouse/blob/main/.github/workflows/cron-weekly.yml).

## Testing

### Before

Running locally before fixing the errors (snippet image)
<img width="897" alt="image"
src="https://github.com/navapbc/template-infra/assets/5387486/571de648-5d10-49b3-8ebd-10efaf6c249f">

And see the CI failing for just this new check before fixing the errors
it finds:
<img width="972" alt="image"
src="https://github.com/navapbc/template-infra/assets/5387486/39ce0034-eb81-409f-b4ca-fbf9b1b0550f">

Snippet of failing checks
<img width="625" alt="image"
src="https://github.com/navapbc/template-infra/assets/5387486/b5358832-2480-4873-a3e1-eb745d661342">

### After

Locally, `make` command completes without error when finding no issues.
<img width="395" alt="image"
src="https://github.com/navapbc/template-infra/assets/5387486/08452792-8659-44f7-ba57-2105a85f9432">

All the beautiful checks in the CI for PRs pass! (Love those green
checkmarks!)
<img width="892" alt="image"
src="https://github.com/navapbc/template-infra/assets/5387486/512e31e1-5218-41c1-a297-b984ac301cd0">

.github/workflows/ci-docs.yml

@@ -0,0 +1,20 @@
+name: CI Documentation Checks
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+
+
+jobs:
+  lint-markdown:
+    name: Lint markdown
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      # This is the GitHub Actions-friendly port of the linter used in the Makefile.
+      - uses: gaurav-nelson/github-action-markdown-link-check@1.0.15
+        with:
+          use-quiet-mode: 'yes'  # errors only.
+          config-file: '.github/workflows/markdownlint-config.json'

.github/workflows/markdownlint-config.json

@@ -0,0 +1,13 @@
+{
+    "ignorePatterns" : [
+        {
+            "pattern": "0005-example.md"
+        }
+    ],
+    "replacementPatterns": [
+        {
+            "pattern": "^/",
+            "replacement": "{{BASEURL}}/"
+        }
+  ]
+}

Makefile

@@ -39,6 +39,7 @@ __check_defined = \
 	infra-configure-network \
 	infra-format \
 	infra-lint \
+	infra-lint-markdown \
 	infra-lint-scripts \
 	infra-lint-terraform \
 	infra-lint-workflows \
@@ -139,7 +140,10 @@ infra-check-compliance-checkov: ## Run checkov compliance checks
 infra-check-compliance-tfsec: ## Run tfsec compliance checks
 	tfsec infra
 
-infra-lint: infra-lint-scripts infra-lint-terraform infra-lint-workflows ## Lint infra code
+infra-lint: infra-lint-markdown infra-lint-scripts infra-lint-terraform infra-lint-workflows ## Lint infra code
+
+infra-lint-markdown: ## Lint Markdown docs for broken links
+	./bin/lint-markdown.sh
 
 infra-lint-scripts: ## Lint shell scripts
 	shellcheck bin/**

README.md

@@ -31,7 +31,7 @@ This template assumes that you have an application to deploy. See [application r
 
 After downloading and installing the template into your project:
 
-1. Follow the steps in [`docs/infra/README.md`](./docs/infra/README.md) to setup the infrastructure for your application.
+1. Follow the steps in [infra/README.md](/infra/README.md) to setup the infrastructure for your application.
 1. After setting up AWS resources, you can [set up GitHub Actions workflows](./template-only-docs/set-up-ci.md).
 1. After configuring GitHub Actions, you can [set up continuous deployment](./template-only-docs/set-up-cd.md).
 1. At any point, [set up your team workflow](./template-only-docs/set-up-team-workflow.md).

bin/lint-markdown.sh

@@ -0,0 +1,18 @@
+#!/bin/bash
+
+# To make things simpler, ensure we're in the repo's root directory (one directory up) before
+# running, regardless where the user is when invoking this script.
+
+# Grab the full directory name for where this script lives.
+SCRIPT_DIR=$(readlink -f "$0" | xargs dirname)
+
+# Move up to the root since we want to do everything relative to that. Note that this only impacts
+# this script, but will leave the user wherever they were when the script exists.
+cd "${SCRIPT_DIR}/.." >/dev/null || exit 1
+
+
+LINK_CHECK_CONFIG=".github/workflows/markdownlint-config.json"
+
+# Recursively find all markdown files (*.md) in this directory. Pass them in as args to the lint
+# command using the handy `xargs` command.
+find . -name \*.md -print0 | xargs -0 -n1 markdown-link-check --config $LINK_CHECK_CONFIG

docs/infra/set-up-infrastructure-tools.md

@@ -22,7 +22,7 @@ Then install the version of Terraform you need.
 tfenv install 1.4.6
 ```
 
-If you are unfamiliar with Terraform, check out this [basic introduction to Terraform](./introduction-to-terraform.md).
+If you are unfamiliar with Terraform, check out this [basic introduction to Terraform](./intro-to-terraform.md).
 
 ### Install AWS CLI
 
@@ -44,11 +44,17 @@ brew install gh
 
 ### Install linters
 
-[Shellcheck](https://github.com/koalaman/shellcheck) and [actionlint](https://github.com/rhysd/actionlint) are optional utilites for running infrastructure linters locally.
+We have several optional utilities for running infrastructure linters locally. These are run as part of the CI pipeline, therefore, it is often simpler to test them locally first.
+
+* [Shellcheck](https://github.com/koalaman/shellcheck)
+* [actionlint](https://github.com/rhysd/actionlint)
+* [markdown-link-check](https://github.com/tcort/markdown-link-check)
 
 ```bash
+
 brew install shellcheck
 brew install actionlint
+npm install -g markdown-link-check
 ```
 
 ## AWS Authentication

template-only-docs/application-requirements.md

@@ -3,7 +3,7 @@
 In order to use the template infrastructure, you need an application that meets the following requirements.
 
 * The application's source code lives in a folder that lives in the project root folder e.g. `/app`.
-* The application folder needs to have a `Makefile` that has a build target `release-build` that takes in a Makefile variable `OPTS`, and passes those `OPTS` as options to the `docker build` command. The top level [Makefile](./Makefile) in this repo will call the application's `release-build` make target passing in release tags to tag the docker image with.
+* The application folder needs to have a `Makefile` that has a build target `release-build` that takes in a Makefile variable `OPTS`, and passes those `OPTS` as options to the `docker build` command. The top level [Makefile](/Makefile) in this repo will call the application's `release-build` make target passing in release tags to tag the docker image with.
 * The web application needs to listen on the port defined by the environment variable `PORT`, rather than hardcode the `PORT`. This allows the infrastructure to configure the application to listen on a container port specified by the infrastructure. See [The Twelve-Factor App](https://12factor.net/) to learn more about designing applications to be portable to different infrastructure environments using environment variables.
 * The web application needs to have a health check endpoint at `/health` that returns an HTTP 200 OK response when the application is healthy and ready to accept requests.
 * The Docker image needs to have `wget` installed. This is used in the container task defintion's healthcheck configuration in order to ping the application's `/health` endpoint. If you want to use a different healthcheck command (e.g. `curl`) then you'll need to modify the `healthCheck` configuration in the `aws_ecs_task_definition` resource in [modules/service/main.tf](/infra/modules/service/main.tf).
@@ -22,7 +22,7 @@ If your application needs a database, it must also:
 
 ## Example Application
 
-The infra template includes an example "hello, world" application that works with the template. This application is fully deployed and can be viewed at the endpoint <http://app-dev-2068097977.us-east-1.elb.amazonaws.com/>. The source code for this test application is at <https://github.com/navapbc/platform-test>.
+The infra template includes an example "hello, world" application that works with the template. This application is fully deployed and can be viewed at the endpoint <http://app-dev-459811935.us-east-1.elb.amazonaws.com/>. The source code for this test application is at <https://github.com/navapbc/platform-test>.
 
 ## Template Applications