feat: new link checking method

.github/workflows/links.yml

@@ -0,0 +1,54 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025 Cisco and/or its affiliates.
+# SPDX-License-Identifier: Apache-2.0
+
+name: Links
+
+on:
+  repository_dispatch:
+  workflow_dispatch:
+  schedule:
+    - cron: "00 06 * * *"
+
+jobs:
+  linkChecker:
+    runs-on: ubuntu-latest
+    permissions:
+      issues: write
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          submodules: 'recursive'
+
+      - name: Setup Golang
+        uses: actions/setup-go@v5
+        with:
+          go-version: '1.23.1'
+
+      - name: Setup Taskfile
+        shell: bash
+        run: |
+          sh -c "$(curl --location https://taskfile.dev/install.sh)" -- -d -b ~/.local/bin
+
+      - name: Setup UV
+        shell: bash
+        run: |
+          curl -LsSf https://astral.sh/uv/install.sh | sh
+
+      - name: Update GITHUB_PATH
+        shell: bash
+        run: echo "$HOME/.local/bin" >> $GITHUB_PATH
+
+      - name: Build docs
+        shell: bash
+        run: |
+          task build
+
+      - name: Link Checker
+        id: lychee
+        uses: lycheeverse/lychee-action@v2
+        with:
+          args: '--config lychee.toml .build/site'
+          fail: false
+

.github/workflows/pr-links.yml

@@ -0,0 +1,72 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025 Cisco and/or its affiliates.
+# SPDX-License-Identifier: Apache-2.0
+
+name: PR Links
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+    branches: [main, master]
+  workflow_dispatch:
+
+jobs:
+  linkChecker:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          submodules: 'recursive'
+
+      - name: Setup Golang
+        uses: actions/setup-go@v5
+        with:
+          go-version: '1.23.1'
+
+      - name: Setup Taskfile
+        shell: bash
+        run: |
+          sh -c "$(curl --location https://taskfile.dev/install.sh)" -- -d -b ~/.local/bin
+
+      - name: Setup UV
+        shell: bash
+        run: |
+          curl -LsSf https://astral.sh/uv/install.sh | sh
+
+      - name: Update GITHUB_PATH
+        shell: bash
+        run: echo "$HOME/.local/bin" >> $GITHUB_PATH
+
+      - name: Build docs
+        shell: bash
+        run: |
+          task build
+
+      - name: Check links in PR changes
+        uses: lycheeverse/lychee-action@v2
+        with:
+          # Remap live URLs to build directory because the links are potentially not live yet
+          args: |
+            --config lychee.toml
+            --root-dir $PWD/.build/site
+            --exclude-all-private
+            --remap 'https://docs\.agntcy\.org/(.*)/ file://'$PWD'/.build/site/$1/index.html'
+            .build/site/
+          fail: true
+          output: lychee/out.md
+
+      - name: Comment Broken Links
+        if: failure()
+        uses: marocchino/sticky-pull-request-comment@v2
+        with:
+          path: lychee/out.md
+
+      - name: Suggestions
+        if: failure()
+        run: |
+          echo -e "\nPlease review the links reported in the 'Check links in PR changes' step above."
+          echo -e "If a link is valid but fails due to a CAPTCHA challenge, IP blocking, login requirements, etc.,"
+          echo -e "consider adding such links to lychee.toml exclude list to bypass future checks.\n"
+          exit 1
+

.gitignore

@@ -17,3 +17,6 @@ generated/
 # Python cache
 __pycache__/
 *.pyc
+
+# Lychee cache
+.lycheecache

.pymarkdown

@@ -8,12 +8,12 @@ plugins:
     enabled: true
     siblings_only: true
   md030:
-    enabled: true
+    enabled: false
   md031:
     enabled: false  
   md033:
-    enabled: true
-    allowed_elements: [details, summary, img, br, sub, sup]
+    enabled: false
+    allowed_elements: [details, summary, img, br, sub, sup, div]
   md041:
     enabled: false
   md046:
@@ -22,3 +22,7 @@ plugins:
     enabled: false
   md007:  
     enabled: false
+  md034:
+    enabled: true
+  md036:
+    enabled: false

Taskfile.yml

@@ -52,12 +52,13 @@ tasks:
       - echo "All documentation tests passed!"
 
   lint:
-    desc: Run all linting checks (spelling, markdown)
+    desc: Run all linting checks (spelling, markdown, links)
     deps:
       - deps/patch
     cmds:
       - task: lint:spelling
       - task: lint:markdown
+      - task: lint:links
 
   lint:spelling:
     desc: Check spelling in documentation
@@ -77,6 +78,12 @@ tasks:
     cmds:
       - uv run pymarkdown --config ../.pymarkdown scan ../docs
 
+  lint:links:
+    desc: Check for broken links in markdown documentation
+    internal: true
+    cmds:
+      - lychee --config lychee.toml docs/
+
   lint:fix:
     desc: Auto-fix spelling and markdown issues where possible
     deps:

docs/coffee-agntcy/get-started.md

@@ -99,5 +99,4 @@ graph LR
     GC <--> TF[Tatooine Farm Agent]
 ```
 
-
 Learn more on how to deploy Lungo locally by visiting the [Lungo Deployment Guide](https://github.com/agntcy/coffeeAgntcy/blob/main/coffeeAGNTCY/coffee_agents/lungo/README.md)

docs/coffee-agntcy/slim-coffee-agntcy.md

@@ -23,22 +23,22 @@ transport = factory.create_transport("SLIM", endpoint=SLIM_ENDPOINT, name="defau
 
 Where:
 
-* `AgntcyFactory` initializes the factory for the agent.  
-* `create_transport("SLIM", ...)` provisions a SLIM transport instance connected to the configured endpoint.  
+- `AgntcyFactory` initializes the factory for the agent.  
+- `create_transport("SLIM", ...)` provisions a SLIM transport instance connected to the configured endpoint.  
 
 ## Sending Messages  
 
 SLIM accommodates both targeted and broadcast messaging within the same API:  
 
-* **1-to-1 Message**
+- **1-to-1 Message**
 
     Used when the supervisor agent needs to send a request to a single farm agent:  
 
     ```python
     response = await client.send_message(request)
     ```
 
-* **Publisher/Subscriber Pattern**
+- **Publisher/Subscriber Pattern**
 
     Used when the auction supervisor sends the same request to multiple farm agents and waits for all the responses:
 
@@ -52,10 +52,10 @@ SLIM accommodates both targeted and broadcast messaging within the same API:
 
     Where:
 
-    * `broadcast_topic` is the topic to which the message is broadcasted.
-    * `recipients` is the list of agents to which the message is sent.
+    - `broadcast_topic` is the topic to which the message is broadcasted.
+    - `recipients` is the list of agents to which the message is sent.
 
-    ### Streaming Publisher/Subscriber
+  ### Streaming Publisher/Subscriber
 
     For real-time responses as farms reply, use the streaming variant:
 
@@ -69,7 +69,7 @@ SLIM accommodates both targeted and broadcast messaging within the same API:
 
     This returns a stream of data from the farms.
 
-* **Group Communication Pattern**
+- **Group Communication Pattern**
 
     Used when multiple agents participate in a group chat session, where all agents can send messages and listen to communications from other agents in the group:
 
@@ -85,13 +85,13 @@ SLIM accommodates both targeted and broadcast messaging within the same API:
 
     Where:
 
-    * `init_message` is the initial message to start the group chat.
-    * `group_channel` is the unique channel ID for the group chat session.
-    * `participants` is the list of agent topics participating in the group chat.
-    * `end_message` is the message that signals the end of the group chat.
-    * `timeout` is the timeout for the group chat session in seconds.
+    - `init_message` is the initial message to start the group chat.
+    - `group_channel` is the unique channel ID for the group chat session.
+    - `participants` is the list of agent topics participating in the group chat.
+    - `end_message` is the message that signals the end of the group chat.
+    - `timeout` is the timeout for the group chat session in seconds.
 
-    ### Streaming Group Communication
+  ### Streaming Group Communication
 
     For real-time order state transitions as each agent processes the order:
 

docs/contributing.md

@@ -8,8 +8,7 @@ reporting bugs that we ask you to review.
 Before reporting a new issue, please ensure that the issue was not already reported or fixed by searching through our
 [issues list](https://github.com/agntcy/docs/issues).
 
-When creating a new issue, please be use the **New Issue** template, and provide as much relevant information as
-possible.
+When creating a new issue, use the **New Issue** template and provide as much relevant information as possible.
 
 ## Sending Pull Requests
 
@@ -27,7 +26,7 @@ If you move or rename a documentation file, **you must add a redirect** to prese
 
 To add a redirect:
 
-1. Open `mkdocs/mkdocs.yml`
+1. Open `mkdocs/mkdocs.yml`.
 1. Add an entry to the `redirect_maps` under the `redirects` plugin:
 
     ```yaml
@@ -37,32 +36,48 @@ To add a redirect:
             'old/path/to/file.md': 'new/path/to/file.md'
     ```
 
-1. Test the redirect locally by running `task build` or `task run` and verifying the old URL redirects to the new location
+1. Test the redirect locally by running `task build` or `task run` and verifying the old URL redirects to the new location.
 
 !!! warning
 
     Failing to add redirects will result in broken links and a poor user experience. Always add redirects when moving content.
 
+## Linting and Running the Documentation Site Locally
+
+The documentation site is built using [MkDocs](https://www.mkdocs.org/) and [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/). It also uses [Lychee](https://github.com/lycheeverse/lychee) to check for broken links and Taskfile to run the documentation site locally and lint the documentation.
+
+To run the documentation site locally and lint the documentation, you need the following prerequisites:
+
+- [Taskfile](https://taskfile.dev/)
+- [Uv](https://docs.astral.sh/uv/getting-started/installation/)
+- [Python version 3.13 or higher](https://www.python.org/)
+- [Lychee](https://github.com/lycheeverse/lychee)
+
+To run the documentation site locally, use `task run`. This will start a live-reloading server at `http://localhost:8000`, allowing you to view the documentation site in your browser in real time.
+
+To lint and check for errors in the documentation, use `task lint`. This checks for broken links, spelling errors, and markdown syntax errors.
+
 ## Markdown and Writing Style
 
-Generic markdown intro (if needed):
-    - [commonmark.org/help/tutorial](https://commonmark.org/help/tutorial/)
-    - [www.markdownguide.org](https://www.markdownguide.org)
+For a general overview of Markdown, see the following resources:
+
+- [commonmark.org/help/tutorial](https://commonmark.org/help/tutorial/)
+- [www.markdownguide.org](https://www.markdownguide.org)
 
-Don't add hard line breaks at a certain line-length, enable line-wrapping in your editor instead. Otherwise searching for sentences in the code becomes a pain.
+Do not add hard line breaks at a certain line-length, enable line-wrapping in your editor instead. Otherwise searching for sentences in the code becomes a pain.
 
 ### Headings
 
 - Start with level 1 heading (#).
 - Use hashmarks for headings.
-- Use title case (`# Start Every Word with Uppercase Except for Articles and Coordinating Conjunctions`)
-- Keep titles reasonably short (they show up in the right-hand toc)
+- Use title case (`# Start Every Word with Uppercase Except for Articles and Coordinating Conjunctions`).
+- Keep titles reasonably short (they show up in the right-hand toc).
 - Do not skip heading levels.
 
 ### Lists
 
-- Use dash (`-`) for bulleted lists
-- Use only `1.` for ordered lists, they are automatically numbered in the output
+- Use dash (`-`) for bulleted lists.
+- Use only `1.` for ordered lists, they are automatically numbered in the output.
 - Indent additional stuff that belongs to a list element by 4 spaces, for example:
 
     ```md
@@ -81,9 +96,14 @@ Don't add hard line breaks at a certain line-length, enable line-wrapping in you
 
 ### Links
 
-- When linking to an external URL, or to a static HTML file within the project, use normal markdown linking `[text](url)`
+- When linking to an external URL, or to a static HTML file within the project, use normal markdown linking `[text](url)`.
 - When linking to a file within the docs, use `[link text](/docs/path/to/file.md)`.
-- Use project-absolute paths in the links/refs: start with a /, then the path relative to the `content` directory, for example: `/docs/getting-started/example.md` (easier to update when a file is moved, and easier to recognize where it is pointing).
+- Use project-absolute paths in the links and references: start with a `/`, then the path relative to the `content` directory.
+
+    !!! example
+        `/docs/getting-started/example.md` (easier to update when a file is moved, and easier to recognize where it is pointing).
+
+- Always check for broken links by running `task lint` before submitting a pull request.
 
 ### Images
 
@@ -134,4 +154,4 @@ Is displayed as:
 
     This is a note.
 
-For more information, see the [Material for MkDocs reference](https://squidfunk.github.io/mkdocs-material/reference/).
+For more information on formatting, see the [Material for MkDocs reference](https://squidfunk.github.io/mkdocs-material/reference/).

docs/dir/dir-api-reference.md

@@ -4,7 +4,7 @@ For detailed API reference, see the following pages:
 
 * [Core API Reference](https://buf.build/agntcy/dir/docs/main:agntcy.dir.core.v1)
 * [Events API Reference](https://buf.build/agntcy/dir/docs/main:agntcy.dir.events.v1)
-*  [Routing API Reference](https://buf.build/agntcy/dir/docs/main:agntcy.dir.routing.v1)
+* [Routing API Reference](https://buf.build/agntcy/dir/docs/main:agntcy.dir.routing.v1)
 * [Search API Reference](https://buf.build/agntcy/dir/docs/main:agntcy.dir.search.v1)
 * [Sign API Reference](https://buf.build/agntcy/dir/docs/main:agntcy.dir.sign.v1)
 * [Store API Reference](https://buf.build/agntcy/dir/docs/main:agntcy.dir.store.v1)

docs/dir/hosted-agent-directory.md

@@ -215,7 +215,7 @@ To be useful, an agent, A2A card, or MCP server record should include at least t
 * Skills, following the [OASF skills schema](https://schema.oasf.outshift.com/skills?extensions=).
 * Previous Record CID: if this is a new or related version to another record, indicate the CID of the related record.
 
-And it will look like this: 
+And it will look like this:
 
 ```json
 {
@@ -388,7 +388,6 @@ dir hub verify <record CID>
 
 For further details on signing, use the `dirctl hub sign --help` command.
 
-
 #### Pulling Agent Directory Records using `dirctl`
 
 You can also pull an Agent Directory record via `dirctl` using the command listed on the agent details page.

docs/glossary.md

@@ -96,7 +96,7 @@ This glossary defines technical terms referenced across the SLIM messaging docum
 
     ---
 
-    Host:port (and scheme) on which a server listens or a client connects. Note that in the configuration the client needs to specify the protocol (e.g. http://localhost:46357), but not the server (e.g. localhost:46357)
+    Host:port (and scheme) on which a server listens or a client connects. Note that in the configuration the client needs to specify the protocol (e.g. `http://localhost:46357`), but not the server (e.g. localhost:46357)
 
 </div>