ci: adds lint check and fixed bad links

We should quote any example links and only add links for things that are
always up, or will be up due following instructions.

For example, we should add exceptions for localhost services that run in
result of test commands for zipkin or the UI.

See openzipkin/zipkin-gcp#212 for the first impl
of this.

Signed-off-by: Adrian Cole <adrian@tetrate.io>

.github/CONTRIBUTING.md

@@ -9,7 +9,7 @@ When submitting code, please apply [Square Code Style](https://github.com/square
 ## License
 
 By contributing your code, you agree to license your contribution under
-the terms of the [APLv2](LICENSE).
+the terms of the [APLv2](../LICENSE).
 
 All files are released with the Apache 2.0 license.
 

.github/workflows/test_markdown.yml

@@ -0,0 +1,33 @@
+# yamllint --format github .github/workflows/test_markdown.yml
+---
+name: test_markdown
+
+on:  # yamllint disable-line rule:truthy
+  push:  # non-tagged pushes to master
+    branches:
+      - master
+    tags-ignore:
+      - '*'
+    paths:
+      - '**/*.md'
+      - ./build-bin/mlc_config.json
+  pull_request:  # pull requests targeted at the master branch.
+    branches:
+      - master
+    paths:
+      - '**/*.md'
+      - ./build-bin/mlc_config.json
+
+jobs:
+  test-markdown:
+    name: Test Markdown
+    runs-on: ubuntu-22.04  # newest available distribution, aka jellyfish
+    # skip commits made by the release plugin
+    if: "!contains(github.event.head_commit.message, 'maven-release-plugin')"
+    steps:
+      - name: Checkout Repository
+        uses: actions/checkout@v4
+      - name: Check Markdown links
+        uses: gaurav-nelson/github-action-markdown-link-check@v1
+        with:
+          config-file: './build-bin/mlc_config.json'

README.md

@@ -44,11 +44,11 @@ You can also start Zipkin via Docker.
 docker run -d -p 9411:9411 openzipkin/zipkin
 ```
 
-Once the server is running, you can view traces with the Zipkin UI at `http://your_host:9411/zipkin/`.
+Once the server is running, you can view traces with the Zipkin UI at http://localhost:9411/zipkin.
 
 If your applications aren't sending traces, yet, configure them with [Zipkin instrumentation](https://zipkin.io/pages/tracers_instrumentation) or try one of our [examples](https://github.com/openzipkin?utf8=%E2%9C%93&q=example).
 
-Check out the [`zipkin-server`](/zipkin-server) documentation for configuration details, or [Docker examples](docker/examples) for how to use docker-compose.
+Check out the [`zipkin-server`](zipkin-server/README.md) documentation for configuration details, or [Docker examples](docker/examples) for how to use docker-compose.
 
 ### Zipkin Slim
 
@@ -213,10 +213,10 @@ commits to master.
 
 ### Docker Images
 Released versions of zipkin-server are published to Docker Hub as `openzipkin/zipkin` and GitHub
-Container Registry as `ghcr.io/openzipkin/zipkin`. See [docker](./docker) for details.
+Container Registry as `ghcr.io/openzipkin/zipkin`. See [docker](docker) for details.
 
 ### Helm Charts
-Helm charts are available at https://zipkin.io/zipkin-helm.
+Helm charts are available via `helm repo add zipkin https://zipkin.io/zipkin-helm`.
 See [zipkin-helm](https://github.com/openzipkin/zipkin-helm) for details.
 
 ### Javadocs

build-bin/README.md

@@ -22,6 +22,15 @@ On deploy:
 * Besides production Docker images, this project includes [../docker/test-images].
   * [docker_push] pushes test-images, but only to ghcr.io
 
+### Markdown validation
+
+[mlc_config.json](mlc_config.json) is run by GitHub Action, but you can also run it locally,
+assuming you installed markdown-link-check via NPM.
+
+```bash
+$ find . -name \*.md |grep -v node|xargs markdown-link-check -c ./build-bin/mlc_config.json
+```
+
 [//]: # (Below here should be standard for all projects)
 
 ## Build Overview

build-bin/mlc_config.json

@@ -0,0 +1,25 @@
+{
+  "ignorePatterns": [
+    {
+      "pattern": "https://oss.sonatype.org/content/repositories/snapshots"
+    },
+    {
+      "pattern": "http://localhost:9411/api/v[12]/spans"
+    },
+    {
+      "pattern": "http://localhost:9411/zipkin"
+    },
+    {
+      "pattern": "http://localhost:9411/zipkin?serviceName=backend"
+    },
+    {
+      "pattern": "http://localhost:8081"
+    },
+    {
+      "pattern": "http://localhost:9000/api"
+    },
+    {
+      "pattern": "http://localhost:3000"
+    }
+  ]
+}

docker/README.md

@@ -41,7 +41,7 @@ We also provide [example compose files](examples/README.md) that integrate colle
 such as Kafka or Elasticsearch.
 
 ## Configuration
-Configuration is via environment variables, defined by [zipkin-server](https://github.com/openzipkin/zipkin/blob/master/zipkin-server/README.md). Notably, you'll want to look at the `STORAGE_TYPE` environment variables, which
+Configuration is via environment variables, defined by [zipkin-server](../zipkin-server/README.md). Notably, you'll want to look at the `STORAGE_TYPE` environment variables, which
 include "cassandra", "mysql" and "elasticsearch".
 
 Note: the `openzipkin/zipkin-slim` image only supports "elasticsearch" storage. To use other storage types, you must use the main image `openzipkin/zipkin`.
@@ -102,7 +102,7 @@ The above is mentioned only for historical reasons. The OpenZipkin community
 do not support Docker's deprecated container links.
 
 ### MySQL
-If using an external MySQL server or image, ensure schema and other parameters match the [docs](https://github.com/openzipkin/zipkin/tree/master/zipkin-storage/mysql-v1#applying-the-schema).
+If using an external MySQL server or image, ensure schema and other parameters match the [docs](../zipkin-storage/mysql-v1/README.md#applying-the-schema).
 
 ## Building images
 

docker/examples/README.md

@@ -83,7 +83,7 @@ To add Kafka configuration, run:
 $ docker-compose -f docker-compose-kafka.yml up
 ```
 
-Then configure the [Kafka sender](https://github.com/openzipkin/zipkin-reporter-java/blob/master/kafka11/src/main/java/zipkin2/reporter/kafka11/KafkaSender.java) using a `bootstrapServers` value of `host.docker.internal:9092` if your application is inside the same docker network or `localhost:19092` if not, but running on the same host.
+Then configure the [Kafka sender](https://github.com/openzipkin/zipkin-reporter-java/blob/master/kafka/src/main/java/zipkin2/reporter/kafka/KafkaSender.java) using a `bootstrapServers` value of `host.docker.internal:9092` if your application is inside the same docker network or `localhost:19092` if not, but running on the same host.
 
 In other words, if you are running a sample application on your laptop, you would use `localhost:19092` bootstrap server to send spans to the Kafka broker running in Docker.
 
@@ -141,9 +141,9 @@ $ docker-compose -f docker-compose.yml -f docker-compose-example.yml up
 ```
 
 Once the services start, open http://localhost:8081/
-* This calls the backend (http://127.0.0.1:9000/api) and shows its result: a formatted date.
+* This calls the backend (http://localhost:9000/api) and shows its result: a formatted date.
 
-Afterward, you can view traces that went through the backend via http://127.0.0.1:9411/zipkin?serviceName=backend
+Afterward, you can view traces that went through the backend via http://localhost:9411/zipkin?serviceName=backend
 
 ## UI
 

zipkin-collector/activemq/RATIONALE.md

@@ -25,7 +25,7 @@ easier in the same way as bundling elasticsearch does.
 
 ## On a potential single-transport client
 
-This package is using the normal activemq-jms client. During a [mail thread](http://activemq.2283324.n4.nabble.com/Interest-in-using-ActiveMQ-as-a-trace-data-transport-for-Zipkin-td4749755.html), we learned the
+This package is using the normal activemq-jms client. During a [mail thread](https://marc.info/?l=activemq-users&m=155356007513108), we learned the
 the STOMP and AMQP 1.0 protocol are the more portable options for a portable integration as
 ActiveMQ, Artemis and RabbitMQ all support these. On the other hand Kafka does not support these
 protocols. Any future portability work could be limited by this. Meanwhile, using the standard JMS

zipkin-lens/README.md

@@ -37,7 +37,7 @@ It correctly bundles React in production mode and optimizes the build for the be
 ## Localization
 
 We use [LinguiJS](https://lingui.js.org/) for localization of the UI. Translations for strings are
-found in the JSON files under [here](./src/translations). The Javascript files in the directory are
+found in the JSON files under [here](src/translations). The Javascript files in the directory are
 compiled from the JSON files. We're always excited to have help maintaining these translations - if
 you see a string in the UI that is not translated or mistranslated, please feel free to send a PR to
 the JSON file to fix it. If you can, please run `yarn run compile` to also compile the translation
@@ -46,13 +46,13 @@ of it.
 
 ### Adding a new locale
 
-To add a new translated locale, first edit [.linguirc](./.linguirc) and add the locale to the
+To add a new translated locale, first edit [.linguirc](.linguirc) and add the locale to the
 `locales` section. Next, run `yarn run extract` to extract a new file under `src/translations` for
 the locale. Translate as many strings in the JSON file as you can. Then run `yarn run compile` to
 compile the strings.
 
-Finally, edit [App.jsx](./src/components/App/App.jsx) and
-[LanguageSelector.tsx](./src/components/App/LanguageSelector.tsx) to import the new translation and
+Finally, edit [App.tsx](src/components/App/App.tsx) and
+[LanguageSelector.tsx](src/components/App/LanguageSelector.tsx) to import the new translation and
 add an entry to the language selector respectively.
 
 ## Dev Tools