Catch link definition and reference mismatches (#914)

To stop myself from messing these up and having to create PRs like #913.
I'm not sure if involved Markdown linting is worth bundling in skuba
itself, but we can locally benefit from `remark-lint` in the meantime.

I also looked into `markdownlint` and `textlint` but couldn't readily
find an equivalent rule.

docs/about.md

@@ -68,7 +68,6 @@ Here are some highlights:
 [@seek/db-client]: https://github.com/SEEK-Jobs/db-client
 [@seek/graphql-utils]: https://github.com/SEEK-Jobs/graphql-utils
 [@seek/logger]: https://github.com/seek-oss/logger
-[@seek/node-authentication]: https://github.com/SEEK-Jobs/node-authentication
 [@seek/node-s2sauth-issuer]: https://github.com/SEEK-Jobs/node-s2sauth-issuer
 [@seek/typegen]: https://github.com/SEEK-Jobs/typegen
 [@seek/zactive-directory]: https://github.com/SEEK-Jobs/zactive-directory

docs/cli/index.md

@@ -37,5 +37,4 @@ yarn format
 [gradle]: https://gradle.org/
 [make]: https://www.gnu.org/software/make/
 [package.json]: https://nodejs.dev/learn/the-package-json-guide
-[sku]: https://github.com/seek-oss/sku
 [tsc]: https://www.typescriptlang.org/docs/handbook/compiler-options.html

docs/cli/test.md

@@ -40,4 +40,3 @@ See our [Jest guide] for a more detailed configuration breakdown.
 [github annotations]: ../deep-dives/github.md#github-annotations
 [jest]: https://jestjs.io
 [jest guide]: ../deep-dives/jest.md
-[projects]: https://jestjs.io/docs/configuration#projects-arraystring--projectconfig

docs/deep-dives/buildkite.md

@@ -19,7 +19,7 @@ as well as common issues faced when running your project on a Buildkite agent.
 **skuba** can output issues detected by [`skuba lint`] as [Buildkite annotations].
 
 This can be enabled by propagating Buildkite environment variables and the `buildkite-agent` binary.
-For example, with the Docker plugin:
+For example, with the [Docker Buildkite plugin]:
 
 ```yaml
 steps:

docs/deep-dives/github.md

@@ -18,7 +18,7 @@ This topic details GitHub integration features baked into **skuba**.
 
 This can be enabled by propagating Buildkite environment variables and a GitHub API token.
 At SEEK, this token can be configured through a `:tw` repository suffix in BuildAgency.
-For example, with the Docker plugin:
+For example, with the [Docker Buildkite plugin]:
 
 ```yaml
 steps:

package.json

@@ -69,6 +69,8 @@
     "jsonfile": "6.1.0",
     "koa": "2.13.4",
     "memfs": "3.4.6",
+    "remark-cli": "11.0.0",
+    "remark-preset-lint-recommended": "6.1.2",
     "semver": "7.3.7",
     "supertest": "6.2.3",
     "type-fest": "2.13.1"
@@ -98,6 +100,28 @@
     }
   },
   "private": false,
+  "remarkConfig": {
+    "plugins": [
+      "remark-preset-lint-recommended",
+      [
+        "remark-lint-list-item-indent",
+        false
+      ],
+      [
+        "remark-lint-no-shortcut-reference-link",
+        false
+      ],
+      [
+        "remark-lint-no-undefined-references",
+        {
+          "allow": [
+            " ",
+            "x"
+          ]
+        }
+      ]
+    ]
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/seek-oss/skuba.git"
@@ -109,7 +133,8 @@
     "build": "ts-node --transpile-only src/skuba build && scripts/postbuild.sh",
     "deploy": "scripts/deploy.sh",
     "format": "yarn skuba format",
-    "lint": "yarn skuba lint",
+    "lint": "yarn skuba lint && yarn lint:md",
+    "lint:md": "remark --frail --quiet .",
     "release": "yarn build && changeset publish",
     "stage": "changeset version && yarn format",
     "skuba": "yarn build && node lib/skuba",

template/greeter/README.md

@@ -35,8 +35,8 @@ or serve as a starting point for a backend project if the other built-in templat
 
 It's a barebones Node.js application that comprises:
 
-- A [src/app.ts] that can be run locally to greet the user
-- A [src/app.test.ts] that demonstrates rudimentary Jest usage
+- A [src/app.ts](src/app.ts) that can be run locally to greet the user
+- A [src/app.test.ts](src/app.test.ts) that demonstrates rudimentary Jest usage
 
 ## Development