Fix broken external links found with automated link checking

.github/workflows/build-and-stage.yml

@@ -25,7 +25,8 @@ jobs:
     name: Build and publish app
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v6
+    - name: Git checkout
+      uses: actions/checkout@v6
       with:
         persist-credentials: false
 

.github/workflows/check-links.yml

@@ -0,0 +1,67 @@
+name: Check external links
+
+on:
+  workflow_dispatch:
+  pull_request:
+    paths:
+      - '**.md'
+      - 'docs/**'
+      - '.github/workflows/check-links.yml'
+      - 'lychee.toml'
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  check-links:
+    name: Check external links in documentation
+    runs-on: ubuntu-latest
+    steps:
+      - name: Git checkout
+        uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+
+      # To bust the lychee cache for a PR, replace `<pull-request-number>` with the PR number and run in pwsh:
+      # $ids = gh api repos/SteeltoeOSS/Documentation/actions/caches `
+      #   --paginate `
+      #   --jq '.actions_caches[]
+      #         | select(.key | startswith("cache-lychee-<pull-request-number>-"))
+      #         | .id'
+      # $ids | ForEach-Object {
+      #   gh api -X DELETE "repos/SteeltoeOSS/Documentation/actions/caches/$_"
+      #   Write-Host "Deleted cache $_"
+      # }
+      - name: Restore lychee cache
+        uses: actions/cache@v4
+        with:
+          path: .lycheecache
+          key: cache-lychee-${{ github.event.pull_request.number || 'manual' }}-${{ github.sha }}
+          restore-keys: cache-lychee-${{ github.event.pull_request.number || 'manual' }}-
+
+      - name: Check external links with lychee
+        uses: lycheeverse/lychee-action@v2
+        with:
+          args: --no-progress '**/*.md'
+          fail: false
+          failIfEmpty: true
+          jobSummary: false
+
+      - name: Add link checking results to job summary
+        if: always()
+        run: |
+          if [ -f ./lychee/out.md ]; then
+            sed 's/^# Summary$/# External link checking results/' ./lychee/out.md | tee -a "$GITHUB_STEP_SUMMARY" > ./lychee/results.md
+          fi
+
+      - name: Comment on PR with link check results
+        if: always() && github.event_name == 'pull_request'
+        uses: mshick/add-pr-comment@v2
+        with:
+          message-id: external-links-check
+          message-path: ./lychee/results.md

.gitignore

@@ -459,3 +459,6 @@ src/Steeltoe.io/wwwroot/*xrefmap.yml
 
 # Temporary workaround until a proper DocFX build supporting .NET 10 is available.
 docfx-net10-binaries/
+
+# lychee link-checker cache
+.lycheecache

AGENTS.md

@@ -40,5 +40,5 @@ This repository hosts the [Steeltoe website](https://steeltoe.io/): documentatio
 ## Resources
 
 - **Canonical instructions:** [README.md](README.md), [build/README.md](build/README.md), [docs/README.md](docs/README.md).
-- [docfx documentation](https://dotnet.github.io/docfx) · [docfx Flavored Markdown](https://dotnet.github.io/docfx/docs/markdown.html)
+- [docfx documentation](https://dotnet.github.io/docfx/) · [docfx Flavored Markdown](https://dotnet.github.io/docfx/docs/markdown.html)
 - [Steeltoe website](https://steeltoe.io) · [ASP.NET Core Blazor](https://learn.microsoft.com/aspnet/core/blazor/)

README.md

@@ -4,7 +4,7 @@
 
 This is the home of the [Steeltoe website](https://steeltoe.io/), which hosts documentation and blog articles.
 
-The website is built with [ASP.NET Core Blazor](https://learn.microsoft.com/aspnet/core/blazor/) and [docfx](https://dotnet.github.io/docfx).
+The website is built with [ASP.NET Core Blazor](https://learn.microsoft.com/aspnet/core/blazor/) and [docfx](https://dotnet.github.io/docfx/).
 docfx generates API documentation from triple-slash comments in Steeltoe source code and converts [Markdown](https://dotnet.github.io/docfx/docs/markdown.html) documents to HTML.
 
 ## Building and running the site

build/README.md

@@ -28,3 +28,14 @@ This process can take a while to complete, will display many warnings and may in
    1. This command will produce many yaml files and place them in [docs](../docs), alongside the index pages for each API version
    1. The script offers a parameter to target a single version (for example: `build-metadata.ps1 3`)
 1. Run `docfx build` with [docfx-all.json](../docs/docfx-all.json), which will copy the html files into `wwwroot` of the Steeltoe.io project
+
+## Checking external links locally
+
+Check external links in markdown files with the same tools CI uses (no build required):
+
+```pwsh
+pwsh build/check-external-links.ps1
+```
+
+Requires [lychee](https://lychee.cli.rs/guides/getting-started/).
+Settings are shared between CI and the local script via [`lychee.toml`](../lychee.toml) at the repo root.

build/check-external-links.ps1

@@ -0,0 +1,32 @@
+#!/usr/bin/env pwsh
+# Check external links in markdown files, matching what the check-links CI job does.
+# Run from anywhere in the repo. Requires lychee: https://lychee.cli.rs/guides/getting-started/
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = 'Stop'
+
+if (-not (Get-Command lychee -ErrorAction SilentlyContinue)) {
+    throw 'lychee not found. Install: cargo install lychee, scoop install lychee, or winget install lycheeverse.lychee'
+}
+
+$baseDir = Split-Path -Parent $MyInvocation.MyCommand.Path
+$repoRoot = (Get-Item $baseDir).Parent.FullName
+Push-Location $repoRoot
+
+try {
+    $mdFiles = Get-ChildItem -Path . -Filter '*.md' -Recurse -File
+    if ($mdFiles.Count -eq 0) {
+        throw 'No .md files found in the repository.'
+    }
+
+    Write-Output "Checking external links in $($mdFiles.Count) markdown files ..."
+
+    & lychee '**/*.md'
+
+    if ($LASTEXITCODE -ne 0) {
+        throw "lychee exited with code $LASTEXITCODE"
+    }
+}
+finally {
+    Pop-Location
+}

docs/README.md

@@ -1,6 +1,6 @@
 # Directory Contents
 
-The directories below this one are used with [docfx](https://dotnet.github.io/docfx) to generate static HTML files that are served from the `/src/Steeltoe.io/wwwroot` directory.
+The directories below this one are used with [docfx](https://dotnet.github.io/docfx/) to generate static HTML files that are served from the `/src/Steeltoe.io/wwwroot` directory.
 
 | Path | Description |
 | --- | --- |

docs/api/v2/index.md

@@ -23,7 +23,7 @@ Contains several packages that are common to other Steeltoe components.
 
 ## Steeltoe Configuration Providers
 
-[Custom configuration providers](https://docs.microsoft.com/aspnet/core/fundamentals/configuration/#custom-configuration-providers) for use with Microsoft's [application configuration](https://docs.microsoft.com/aspnet/core/fundamentals/configuration) for accessing configuration settings for an application.
+[Custom configuration providers](https://learn.microsoft.com/aspnet/core/fundamentals/configuration/#custom-configuration-provider) for use with Microsoft's [application configuration](https://learn.microsoft.com/aspnet/core/fundamentals/configuration) for accessing configuration settings for an application.
 
 [view](Steeltoe.Extensions.Configuration.yml)
 

docs/api/v3/index.md

@@ -29,7 +29,7 @@ Contains several packages that are common to other Steeltoe components.
 
 ## Steeltoe Configuration Providers
 
-[Custom configuration providers](https://docs.microsoft.com/aspnet/core/fundamentals/configuration/#custom-configuration-providers) for use with Microsoft's [application configuration](https://docs.microsoft.com/aspnet/core/fundamentals/configuration) for accessing configuration settings for an application.
+[Custom configuration providers](https://learn.microsoft.com/aspnet/core/fundamentals/configuration/#custom-configuration-provider) for use with Microsoft's [application configuration](https://learn.microsoft.com/aspnet/core/fundamentals/configuration) for accessing configuration settings for an application.
 
 [view](Steeltoe.Extensions.Configuration.yml)
 

docs/api/v4/index.md

@@ -23,7 +23,7 @@ Various general-purpose facilities, often used by higher-level Steeltoe componen
 
 ## Steeltoe.Configuration
 
-[Custom configuration providers](https://docs.microsoft.com/aspnet/core/fundamentals/configuration/#custom-configuration-providers) for use with Microsoft's [application configuration](https://docs.microsoft.com/aspnet/core/fundamentals/configuration/) for accessing configuration settings for an application.
+[Custom configuration providers](https://learn.microsoft.com/aspnet/core/fundamentals/configuration/#custom-configuration-provider) for use with Microsoft's [application configuration](https://learn.microsoft.com/aspnet/core/fundamentals/configuration/) for accessing configuration settings for an application.
 
 [view](Steeltoe.Configuration.yml)
 

docs/articles/create-dotnet-microservice-projects-automatically-with-steeltoe-initializr.md

@@ -89,7 +89,7 @@ Below is a brief explanation of Initializr's top level endpoints. But the conver
 
   **Service Configuration**
 
-  The config endpoint ([https://start.steeltoe.io/api/config/](https://start.steeltoe.io/api/config/)) provides a way to get how Initializr has been configured. This endpoint has quite a few sub-endpoints that let you drill deeper into specific config values. Say you wanted to know what .NET runtimes are supported as well what the default version is. You could send a request to [https://start.steeltoe.io/api/config/dotNetFrameworks](https://start.steeltoe.io/api/config/dotNetFrameworks) and receive a JSON formatted answer.
+  The config endpoint ([https://start.steeltoe.io/api/uiconfig/](https://start.steeltoe.io/api/uiconfig/)) provides a way to get how Initializr has been configured. This endpoint has quite a few sub-endpoints that let you drill deeper into specific config values. Say you wanted to know what .NET runtimes are supported as well what the default version is. You could send a request to [https://start.steeltoe.io/api/uiconfig/dotNetFrameworks](https://start.steeltoe.io/api/uiconfig/dotNetFrameworks) and receive a JSON formatted answer.
 
   You can create quite a rich set of tooling with the config endpoint. In true cloud-native design, you can run instances of Initializr in different environments while the tooling keeps a consistent experience.
 

docs/articles/index.md

@@ -58,7 +58,7 @@ uid: articles
         </a>
     </li>
     <li class="blog-item">
-        <a href="https://techcommunity.microsoft.com/t5/apps-on-azure/net-and-java-together-in-azure-spring-cloud-with-pet-clinic/ba-p/2087416">
+        <a href="https://techcommunity.microsoft.com/blog/appsonazureblog/-net-and-java-together-in-azure-spring-cloud-with-pet-clinic/2087416">
             <span class="blog-date" href="">January 25 2021</span>
             <div class="blog-author">David Dieruf</div><br>
             <div class="blog-title" style="display:inline-block">.NET and Java together in Azure Spring Cloud with Pet Clinic</div>

docs/articles/pivotal-contributes-steeltoe-to-the-net-foundation.md

@@ -13,7 +13,7 @@ author.name: Zach Brown
 
 # Pivotal Contributes Steeltoe to the .NET Foundation
 
-It’s official: the Steeltoe open source project is joining the [.NET Foundation](https://www.dotnetfoundation.org/). That’s the news from Microsoft’s Connect() conference in New York City today....
+It’s official: the Steeltoe open source project is joining the [.NET Foundation](https://dotnetfoundation.org/). That’s the news from Microsoft’s Connect() conference in New York City today....
 
-| [Read More](https://tanzu.vmware.com/content/blog/pivotal-contributes-steeltoe-to-the-net-foundation) |
+| [Read More](https://blogs.vmware.com/tanzu/pivotal-contributes-steeltoe-to-the-net-foundation/) |
 | :---: |

docs/articles/releases/steeltoe-2-1-boosts-your-net-microservices-with-actuator-endpoints-distributed-tracing-and-deeper-support-for-the-frameworks-that-matter.md

@@ -25,5 +25,5 @@ The new features in Steeltoe 2.1, all based on community feedback, largely fall
 
 Let’s take a deeper look at each category...
 
-| [Read More](https://tanzu.vmware.com/content/blog/steeltoe-2-1-boosts-your-net-microservices-with-actuator-endpoints-distributed-tracing-and-deeper-support-for-the-frameworks-that-matter) |
+| [Read More](https://blogs.vmware.com/tanzu/steeltoe-2-1-boosts-your-net-microservices-with-actuator-endpoints-distributed-tracing-and-deeper-support-for-the-frameworks-that-matter/) |
 | :---: |

docs/articles/releases/steeltoe-2-2-gives-your--microservices-a-boost.md

@@ -19,7 +19,7 @@ My wife and I have an agreement. She doesn't question my fashion sense and I don
 
 While my better half may not be excited about the new Steeltoe, over 2.4 million NuGet downloads and a very active community suggest that lots of .NET developers are eager to dive in.
 
-Each Steeltoe release is always jam-packed with useful new capabilities. [Steeltoe 2.2](http://steeltoe.io/reference/reference-release-notes/), now GA, delivers! Let’s take a spin through the highlights...
+Each Steeltoe release is always jam-packed with useful new capabilities. Steeltoe 2.2, now GA, delivers! Let’s take a spin through the highlights...
 
-| [Read More](https://tanzu.vmware.com/content/blog/steeltoe-2-2-gives-your-net-microservices-a-boost) |
+| [Read More](https://blogs.vmware.com/tanzu/steeltoe-2-2-gives-your-net-microservices-a-boost/) |
 | :---: |

docs/articles/releases/steeltoe-2-4-boosts-dotnet-microservices-development.md

@@ -19,5 +19,5 @@ The Steeltoe framework helps .NET developers create cloud-native applications. A
 
 To this end, we’ve cooked up some nifty things to help you do more with Steeltoe...
 
-| [Read More](https://tanzu.vmware.com/content/blog/steeltoe-2-4-boosts-dotnet-microservices-development) |
+| [Read More](https://blogs.vmware.com/tanzu/steeltoe-2-4-boosts-dotnet-microservices-development/) |
 | :---: |

docs/articles/releases/steeltoe-3-0-packs-a-mighty-punch-with-many-new-features.md

@@ -28,7 +28,7 @@ Steeltoe makes things like production ready database connections a single line o
 
 Steeltoe 3.0 is a product of years of learning. Small businesses and large enterprises have all been benefiting and contributing to this new release. It’s a fresh take on cloud opinions that seemingly never get answered. It’s the next evolution for your microservices to go to cloud ninja status.
 
-> If you’re moving from Steeltoe 2.x and would like a quick comparison with version 3.0, refer to [this page](/docs/v3/welcome/whats-new.md).
+> If you’re moving from Steeltoe 2.x and would like a quick comparison with version 3.0, refer to [this page](../../docs/v3/welcome/whats-new.md).
 
 Let's take a look at the new things included in Steeltoe 3.0. If you’re still wondering how the project fits in your new or existing .NET applications, [learn how here](https://steeltoe.io).
 
@@ -68,7 +68,7 @@ public void Listen(MyCustomObject myObj){
 }
 ```
 
-Once you’ve got the basics down, it’s time to extend and make the design better with things like custom factories. Steeltoe Messaging will take care of the conversion of a message into a structured type but sometimes you want to intercept that conversion and make decisions. You can create your own `DirectRabbitListenerContainer` and customize to your heart's content. Learn more about custom listener container factories [in the docs](/docs/v3/messaging/rabbitmq-intro.md#receiving-a-message).
+Once you’ve got the basics down, it’s time to extend and make the design better with things like custom factories. Steeltoe Messaging will take care of the conversion of a message into a structured type but sometimes you want to intercept that conversion and make decisions. You can create your own `DirectRabbitListenerContainer` and customize to your heart's content. Learn more about custom listener container factories [in the docs](../../docs/v3/messaging/rabbitmq-intro.md#receiving-a-message).
 
 ## Legacy and Modern together in the cloud
 
@@ -147,7 +147,7 @@ public HomeController(IConfiguration config) {
 }
 ```
 
-If you'd like to see more visit the [samples repo](https://github.com/SteeltoeOSS/Samples/tree/3.x), or have a look in the [docs](/docs/v3/welcome/index.md).
+If you'd like to see more visit the [samples repo](https://github.com/SteeltoeOSS/Samples/tree/3.x), or have a look in the [docs](../../docs/v3/welcome/index.md).
 
 ## Generate production ready projects and get going fast
 
@@ -169,7 +169,7 @@ One of the most shocking things to a developer that is new to working with conta
 
 Observability is typically a sum of logs, traces, and metrics. Sometimes you have them all and sometimes not. Sometimes the data is all on one dashboard and (most of the time) it’s distributed between 2 or more dashboards. Regardless of where the data is being observed, a developer should not have to bring in all kinds of custom dependencies to conform to each dashboard used. They should offer the information in a simple, neutral way with little time spent getting it all wired up.
 
-Steeltoe 3.0 continues the management endpoints found in 2.x but takes things to a deeper place. Along with the following examples, you can also get started using Tanzu Observability with Wavefront or create a Grafana dashboard in our [observability guides](/guides/observability/grafana.md).
+Steeltoe 3.0 continues the management endpoints found in 2.x but takes things to a deeper place. Along with the following examples, you can also get started using Tanzu Observability with Wavefront or create a Grafana dashboard in our [observability guides](../../guides/observability/grafana.md).
 
 * Originally OpenCensus was used for creating standard trace data and metrics. That has been superseded by the OpenTelemetry telemetric standard.
 * Creating tracing spans has been simplified to a single line in `startup.cs` ([here is a full example](https://github.com/SteeltoeOSS/Samples/tree/3.x/Management/src/Tracing))
@@ -182,7 +182,7 @@ Steeltoe 3.0 continues the management endpoints found in 2.x but takes things to
   }
   ```
 
-* In addition to the [metrics endpoint](/docs/v3/management/metrics.md), there is a new Prometheus endpoint that offers a simple way for metrics to be scraped. Below is an example prometheus.yml configuration ([here is a full example](https://github.com/SteeltoeOSS/Samples/tree/3.x/Management/src)):
+* In addition to the [metrics endpoint](../../docs/v3/management/metrics.md), there is a new Prometheus endpoint that offers a simple way for metrics to be scraped. Below is an example prometheus.yml configuration ([here is a full example](https://github.com/SteeltoeOSS/Samples/tree/3.x/Management/src)):
 
   ```yaml
   scrape_configs:
@@ -191,7 +191,7 @@ Steeltoe 3.0 continues the management endpoints found in 2.x but takes things to
       scrape_interval: 5s
   ```
 
-* [Dynamic logging](/docs/v3/logging/index.md) can be implemented with a single statement in the `HostBuilder`
+* [Dynamic logging](../../docs/v3/logging/index.md) can be implemented with a single statement in the `HostBuilder`
 
     ```csharp
     public static IHostBuilder CreateHostBuilder(string[] args) =>
@@ -274,6 +274,5 @@ Here are a few examples of new ways to implement things in the `HostBuilder`:
 
 ## Learn more and get started today
 
-To get started with any Steeltoe projects, head over to the [getting started guides](https://steeltoe.io/get-started). Combine this with the samples in the [Steeltoe GitHub repo](https://github.com/SteeltoeOSS/Samples/tree/3.x), and you’ll have .NET microservices up and running before you know it!
+To get started with any Steeltoe projects, head over to the [getting started guides](https://steeltoe.io/guides/). Combine this with the samples in the [Steeltoe GitHub repo](https://github.com/SteeltoeOSS/Samples/tree/3.x), and you’ll have .NET microservices up and running before you know it!
 
-Want to get deeper into creating cloud-native .NET apps? Attend the VMware Pivotal Labs’s [4 -day .NET developer course](https://pivotal.io/platform-acceleration-lab/pal-for-developers-net). You’ll get hands-on cloud-native .NET training learn best practices when creating microservices and become a Steeltoe ninja!