feat(docs): add linting and testing configurations for documentation

.codespellrc

@@ -0,0 +1,6 @@
+[codespell]
+skip = .git,.build,node_modules,*.png,*.jpg,*.jpeg,*.svg,*.ico,*.drawio,mkdocs/site,schema
+ignore-words-list = agntcy,oasf,acp,mcp,slim,csit,ioa,mas,agws,griffe,outshift,galileo,langchain,agentic,interop,verifiable,authn,authz,pubsub,grpc,protobuf,uuid,uuids,repo,repos,github,localhost,oauth,jwt,ssl,tls,mkdocs,pymdown,autodoc,docstring,namespace,metadata,orchestration,kubectl,kubernetes,observability,telemetry,workflow,workflows,schemas,cli,api,apis,json,yaml,ui,ux,url,urls,uri,uris,http,https,pytho
+count = 
+check-filenames = 
+check-hidden = 

.pymarkdown

@@ -0,0 +1,22 @@
+plugins:
+  md013:
+    enabled: false
+    line_length: 120
+    code_blocks: false
+    tables: false
+  md024:
+    enabled: true
+    siblings_only: true
+  md030:
+    enabled: true
+  md031:
+    enabled: false  
+  md033:
+    enabled: true
+    allowed_elements: [details, summary, img, br, sub, sup]
+  md041:
+    enabled: false
+  md046:
+    enabled: false
+  md051:
+    enabled: false

Taskfile.yml

@@ -40,6 +40,70 @@ tasks:
     cmds:
       - pushd mkdocs && uv run mkdocs serve
 
+  ##
+  ## Testing and Linting
+  ##
+  test:
+    desc: Run all documentation tests and linting checks
+    deps:
+      - deps/patch
+    cmds:
+      - task: lint
+      - echo "All documentation tests passed!"
+
+  lint:
+    desc: Run all linting checks (spelling, markdown)
+    deps:
+      - deps/patch
+    cmds:
+      - task: lint:spelling
+      - task: lint:markdown
+
+  lint:spelling:
+    desc: Check spelling in documentation
+    internal: true
+    deps:
+      - deps/patch
+    dir: mkdocs
+    cmds:
+      - uv run codespell --config ../.codespellrc ../docs
+
+  lint:markdown:
+    desc: Check Markdown syntax and style
+    internal: true
+    deps:
+      - deps/patch
+    dir: mkdocs
+    cmds:
+      - uv run pymarkdown --config ../.pymarkdown scan ../docs
+
+  lint:fix:
+    desc: Auto-fix spelling and markdown issues where possible
+    deps:
+      - deps/patch
+    dir: mkdocs
+    cmds:
+      - task: lint:fix:spelling
+      - task: lint:fix:markdown
+
+  lint:fix:spelling:
+    desc: Auto-fix spelling issues only
+    internal: true
+    deps:
+      - deps/patch
+    dir: mkdocs
+    cmds:
+      - uv run codespell --config ../.codespellrc ../docs --write-changes
+
+  lint:fix:markdown:
+    desc: Auto-fix markdown issues only
+    internal: true
+    deps:
+      - deps/patch
+    dir: mkdocs
+    cmds:
+      - uv run pymarkdown --config ../.pymarkdown fix -r ../docs
+
   ##
   ## Dependencies
   ##

mkdocs/mkdocs.yml

@@ -40,6 +40,39 @@ plugins:
             - griffe_pydantic:
                 schema: true
   swagger-ui-tag:
+  htmlproofer:
+    ignore_urls:
+      # Local development URLs
+      - "http://localhost*"
+      - "https://localhost*"
+      - "*127.0.0.1*"
+
+      # Generic file patterns and placeholders
+      - "*/screenshot.png"
+      - "*/image.png" 
+      - "*/docs/path/to/file.md"
+      - "https://api.NODE/*"
+
+      # External URLs with false negatives (rate limiting/blocking)
+      - "https://docs.agntcy.org/*"
+      - "https://www.npmjs.com/"
+      - "https://httpbin.org/"
+
+      # Auto-generated anchors from API documentation
+      - "#agntcy*"       # Covers all agntcy protobuf types
+      - "#google*"       # Covers all Google protobuf types
+      - "#uint32"
+      - "#string"
+      - "#bytes" 
+      - "#bool"
+      - "#top"
+
+      # Cross-file API references (both source and build formats)
+      - "dir-*-v1-api.md#*"    # Source format
+      - "../dir-*-v1-api/#*"   # Build format
+    raise_error: false
+    raise_error_after_finish: false
+    validate_external_urls: true
 theme:
   name: material
   custom_dir: overrides

mkdocs/pyproject.toml

@@ -22,4 +22,8 @@ dependencies = [
     "agntcy-iomapper==0.2.2",
     "beautifulsoup4>=4.13.3",
     "mkdocs-swagger-ui-tag==0.7.1",
+    # Linting and testing tools
+    "codespell>=2.2.0",
+    "pymarkdownlnt>=0.9.0",
+    "mkdocs-htmlproofer-plugin>=1.0.0",
 ]