doc: add markdownlint and link workflow and update the md file

.github/workflows/ci-markdown-link.yml

@@ -0,0 +1,17 @@
+name: Markdown Lint & Link Check
+
+on:
+  pull_request:
+
+jobs:
+  markdown-link-check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: "MarkDown Link Check"
+        uses: gaurav-nelson/github-action-markdown-link-check@v1
+        with:
+          config-file: '.markdown-link-check.json'
+          use-quiet-mode: 'yes'
+          use-verbose-mode: 'yes'

.github/workflows/ci-markdownlint.yml

@@ -0,0 +1,20 @@
+name: Markdown Lint & Link Check
+
+on:
+  pull_request:
+
+jobs:
+  markdownlint-check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      # equivalent cli: markdownlint-cli2  "**/*.md" "#**/CHANGELOG.md"  --config .markdownlint.json
+      - name: "MarkDown Lint Check"
+        uses: DavidAnson/markdownlint-cli2-action@v16
+        with:
+          fix: false
+          globs: |
+            **/*.md
+            !**/CHANGELOG.md
+          continue-on-error: true

.instrumentation_generator/templates/Readme.md.tt

@@ -6,7 +6,7 @@ Todo: Add a description.
 
 Install the gem using:
 
-```
+```console
 gem install opentelemetry-instrumentation-<%= instrumentation_name %>
 ```
 
@@ -38,7 +38,7 @@ Example usage can be seen in the `./example/trace_demonstration.rb` file [here](
 
 The `opentelemetry-instrumentation-<%= instrumentation_name %>` gem source is [on github][repo-github], along with related gems including `opentelemetry-api` and `opentelemetry-sdk`.
 
-The OpenTelemetry Ruby gems are maintained by the OpenTelemetry-Ruby special interest group (SIG). You can get involved by joining us in [GitHub Discussions][discussions-url] or attending our weekly meeting. See the [meeting calendar][community-meetings] for dates and times. For more information on this and other language SIGs, see the OpenTelemetry [community page][ruby-sig].
+The OpenTelemetry Ruby gems are maintained by the OpenTelemetry-Ruby special interest group (SIG). You can get involved by joining us on our [GitHub Discussions][discussions-url], [Slack Channel][slack-channel] or attending our weekly meeting. See the [meeting calendar][community-meetings] for dates and times. For more information on this and other language SIGs, see the OpenTelemetry [community page][ruby-sig].
 
 ## License
 
@@ -49,4 +49,5 @@ The `opentelemetry-instrumentation-<%= instrumentation_name %>` gem is distribut
 [license-github]: https://github.com/open-telemetry/opentelemetry-ruby-contrib/blob/main/LICENSE
 [ruby-sig]: https://github.com/open-telemetry/community#ruby-sig
 [community-meetings]: https://github.com/open-telemetry/community#community-meetings
+[slack-channel]: https://cloud-native.slack.com/archives/C01NWKKMKMY
 [discussions-url]: https://github.com/open-telemetry/opentelemetry-ruby/discussions

.markdown-link-check.json

@@ -0,0 +1,10 @@
+{
+  "ignorePatterns": [
+    {
+      "pattern": "^http://localhost"
+    }
+  ],
+  "timeout": "5s",
+  "retryOn429": true,
+  "aliveStatusCodes": [200, 206, 429]
+}

.markdownlint.json

@@ -0,0 +1,13 @@
+{
+  "emphasis-style": false,
+  "line-length": false,
+  "link-fragments": false,
+  "list-marker-space": false,
+  "no-emphasis-as-heading": false,
+  "no-hard-tabs": false,
+  "no-inline-html": false,
+  "no-trailing-punctuation": false,
+  "no-trailing-spaces": true,
+  "custom-rules-below-this-point": false,
+  "trim-code-block-and-unindent": true
+}

CONTRIBUTING.md

@@ -168,7 +168,7 @@ bundle exec rake yard
 
 ## Instrumentation author's guide
 
-Please make sure that you review the [Instrumentation author's guide](.instrumentation/CONTRIBUTING.md) before submitting a new instrumentation.
+Please make sure that you review the [Instrumentation author's guide](instrumentation/CONTRIBUTING.md) before submitting a new instrumentation.
 
 ## Create a pull request
 
@@ -209,10 +209,11 @@ make the project that much better. Respond to the feedback and work with your
 reviewer(s) to resolve any issues.
 
 The some of the things the code owners are looking for include:
+
 * a signed [CNCF CLA][cncf-cla]
 * a passing CI build
 * adherence to the principles and features outlined in the
-  [instrumentation author's guide](.instrumentation/CONTRIBUTING.md)
+  [instrumentation author's guide](instrumentation/CONTRIBUTING.md)
 
 Reviewers are responsible for ensuring that each merged PR's commit message
 conforms to [conventional commits](https://conventionalcommits.org). This may

README.md

@@ -60,6 +60,7 @@ multiple instrumentation libraries.
 
 - [MySQL](helpers/mysql/)
 - [SQL Obfuscation](helpers/sql-obfuscation/)
+
 ## Additional Libraries
 
 This repository also contains libraries to aid with interoperability with vendor specific tracing solutions:
@@ -103,17 +104,14 @@ Apache 2.0 - See [LICENSE][license-url] for more information.
 [otel-ruby]: https://github.com/open-telemetry/opentelemetry-ruby
 [otel-ruby-releases]: https://github.com/open-telemetry/opentelemetry-ruby/releases
 [otel-ruby-contrib-releases]: https://github.com/open-telemetry/opentelemetry-ruby-contrib/releases
-[ci-image]: https://github.com/open-telemetry/opentelemetry-ruby-contrib/workflows/CI/badge.svg?event=push
-[examples-github]: https://github.com/open-telemetry/opentelemetry-ruby-contrib/tree/main/examples
+[ci-image]: https://github.com/open-telemetry/opentelemetry-ruby-contrib/workflows/CI%20Contrib/badge.svg?event=push
 [getting-started]: https://opentelemetry.io/docs/languages/ruby/getting-started/
 [issues-good-first-issue]: https://github.com/open-telemetry/opentelemetry-ruby-contrib/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22
 [issues-help-wanted]: https://github.com/open-telemetry/opentelemetry-ruby-contrib/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22
 [license-image]: https://img.shields.io/badge/license-Apache_2.0-green.svg?style=flat
 [license-url]: https://github.com/open-telemetry/opentelemetry-ruby-contrib/blob/main/LICENSE
 [ruby-sig]: https://github.com/open-telemetry/community#ruby-sig
-[opentelemetry-instrumentation-all-publishing]: https://github.com/open-telemetry/opentelemetry-ruby-contrib/tree/main/instrumentation/all#publishing
 [slack-image]: https://img.shields.io/badge/slack-@cncf/otel/ruby-brightgreen.svg?logo=slack
 [slack-url]: https://cloud-native.slack.com/archives/C01NWKKMKMY
 [discussions-url]: https://github.com/open-telemetry/opentelemetry-ruby/discussions
 [otel-versioning]: https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/versioning-and-stability.md
-[otel-specification]: https://github.com/open-telemetry/opentelemetry-specification/tree/main/specification

helpers/mysql/README.md

@@ -22,6 +22,7 @@ end
 ```
 
 Make sure the `Instrumentation` class for your gem contains configuration options for:
+
 - `:span_name`: The type of span name desired for the trace.
   Example: `option :span_name, default: :statement_type, validate: %I[statement_type db_name db_operation_and_name]`
 
@@ -43,7 +44,7 @@ end
 
 The `opentelemetry-helpers-mysql` gem source is [on github][repo-github], along with related gems including `opentelemetry-instrumentation-mysql2` and `opentelemetry-instrumentation-trilogy`.
 
-The OpenTelemetry Ruby gems are maintained by the OpenTelemetry-Ruby special interest group (SIG). You can get involved by joining us on our [gitter channel][ruby-gitter] or attending our weekly meeting. See the [meeting calendar][community-meetings] for dates and times. For more information on this and other language SIGs, see the OpenTelemetry [community page][ruby-sig].
+The OpenTelemetry Ruby gems are maintained by the OpenTelemetry-Ruby special interest group (SIG). You can get involved by joining us on our [GitHub Discussions][discussions-url], [Slack Channel][slack-channel] or attending our weekly meeting. See the [meeting calendar][community-meetings] for dates and times. For more information on this and other language SIGs, see the OpenTelemetry [community page][ruby-sig].
 
 ## License
 
@@ -53,4 +54,5 @@ The `opentelemetry-helpers-mysql` gem is distributed under the Apache 2.0 licens
 [license-github]: https://github.com/open-telemetry/opentelemetry-ruby-contrib/blob/main/LICENSE
 [ruby-sig]: https://github.com/open-telemetry/community#ruby-sig
 [community-meetings]: https://github.com/open-telemetry/community#community-meetings
-[ruby-gitter]: https://gitter.im/open-telemetry/opentelemetry-ruby
+[slack-channel]: https://cloud-native.slack.com/archives/C01NWKKMKMY
+[discussions-url]: https://github.com/open-telemetry/opentelemetry-ruby/discussions

helpers/sql-obfuscation/README.md

@@ -24,6 +24,7 @@ end
 ```
 
 Make sure the `Instrumentation` class for your gem contains configuration options for:
+
 - `:obfuscation_limit`: the length at which the obfuscated SQL string will be truncated.
   Example: `option :obfuscation_limit, default: 2000, validate: :integer`
 
@@ -48,7 +49,7 @@ OpenTelemetry::Helpers::SqlObfuscation.obfuscate_sql(sql, obfuscation_limit: con
 
 The `opentelemetry-helpers-sql-obfuscation` gem source is [on github][repo-github], along with related gems including `opentelemetry-instrumentation-pg` and `opentelemetry-instrumentation-trilogy`.
 
-The OpenTelemetry Ruby gems are maintained by the OpenTelemetry-Ruby special interest group (SIG). You can get involved by joining us on our [gitter channel][ruby-gitter] or attending our weekly meeting. See the [meeting calendar][community-meetings] for dates and times. For more information on this and other language SIGs, see the OpenTelemetry [community page][ruby-sig].
+The OpenTelemetry Ruby gems are maintained by the OpenTelemetry-Ruby special interest group (SIG). You can get involved by joining us on our [GitHub Discussions][discussions-url], [Slack Channel][slack-channel] or attending our weekly meeting. See the [meeting calendar][community-meetings] for dates and times. For more information on this and other language SIGs, see the OpenTelemetry [community page][ruby-sig].
 
 ## License
 
@@ -59,4 +60,5 @@ The `opentelemetry-helpers-sql-obfuscation` gem is distributed under the Apache
 [license-github]: https://github.com/open-telemetry/opentelemetry-ruby-contrib/blob/main/LICENSE
 [ruby-sig]: https://github.com/open-telemetry/community#ruby-sig
 [community-meetings]: https://github.com/open-telemetry/community#community-meetings
-[ruby-gitter]: https://gitter.im/open-telemetry/opentelemetry-ruby
+[slack-channel]: https://cloud-native.slack.com/archives/C01NWKKMKMY
+[discussions-url]: https://github.com/open-telemetry/opentelemetry-ruby/discussions

instrumentation/CONTRIBUTING.md

@@ -403,7 +403,7 @@ The `instrumentation_generator` creates a `README.md` file for your instrumentat
 
 In addition to that, there should also be redundant `yardoc` comments in the entrypoint of your gem, i.e. the subclass `OpenTelemetry::Instrumentation::Base`.
 
-> :information_source: See the `Sidekiq::Instrumentation` [class description](./sidekiq/lib/opentelemetry/instrumentation/sidekiq/instrumentation.rb) for a comprehensive example. 
+> :information_source: See the `Sidekiq::Instrumentation` [class description](./sidekiq/lib/opentelemetry/instrumentation/sidekiq/instrumentation.rb) for a comprehensive example.
 
 ### Examples
 

instrumentation/README.md

@@ -19,19 +19,15 @@ To get started with a single instrumentation library, for example `opentelemetry
 ### 1. Install the gem
 
 ```console
-
 gem install opentelemetry-instrumentation-rack
-
 ```
 
 ### 2. Configure OpenTelemetry to use the instrumentation
 
-```console
-
+```ruby
 OpenTelemetry::SDK.configure do |c|
   c.use 'OpenTelemetry::Instrumentation::Rack'
 end
-
 ```
 
 Instrumentation-specific documentation can be found in each subdirectory's `README.md`.
@@ -55,7 +51,7 @@ The source for all OpenTelemetry Ruby instrumentation gems is [on github](https:
 
 If you are interested in helping out with an instrumentation, you can see instrumentations that have been requested but are not currently in-progress [here](https://github.com/open-telemetry/opentelemetry-ruby-contrib/issues?q=is%3Aopen+label%3Ainstrumentation+label%3A%22help+wanted%22).
 
-The OpenTelemetry Ruby gems are maintained by the OpenTelemetry-Ruby special interest group (SIG). You can get involved by joining us in [GitHub Discussions][discussions-url] or attending our weekly meeting. See the [meeting calendar][community-meetings] for dates and times. For more information on this and other language SIGs, see the OpenTelemetry [community page][ruby-sig].
+The OpenTelemetry Ruby gems are maintained by the OpenTelemetry-Ruby special interest group (SIG). You can get involved by joining us on our [GitHub Discussions][discussions-url], [Slack Channel][slack-channel] or attending our weekly meeting. See the [meeting calendar][community-meetings] for dates and times. For more information on this and other language SIGs, see the OpenTelemetry [community page][ruby-sig].
 
 ## License
 
@@ -64,4 +60,5 @@ All OpenTelemetry Ruby instrumentation gems are distributed under the Apache 2.0
 [license-github]: https://github.com/open-telemetry/opentelemetry-ruby-contrib/blob/main/LICENSE
 [ruby-sig]: https://github.com/open-telemetry/community#ruby-sig
 [community-meetings]: https://github.com/open-telemetry/community#community-meetings
+[slack-channel]: https://cloud-native.slack.com/archives/C01NWKKMKMY
 [discussions-url]: https://github.com/open-telemetry/opentelemetry-ruby/discussions

instrumentation/action_mailer/README.md

@@ -50,13 +50,15 @@ See the table below for details of what [Rails Framework Hook Events](https://gu
 ### Options
 
 ActionMailer instrumentation doesn't expose email addresses by default, but if email addresses are needed, simply use `:email_address` option:
+
 ```ruby
 OpenTelemetry::SDK.configure do |c|
   c.use 'OpenTelemetry::Instrumentation::ActionMailer', { email_address: :include }
 end
 ```
 
 If only want to hide certain attributes from the notifications payload for email address:
+
 ```ruby
 OpenTelemetry::SDK.configure do |c|
   c.use 'OpenTelemetry::Instrumentation::ActionMailer', { email_address: :include, disallowed_notification_payload_keys: ['email.to.address'] }
@@ -78,16 +80,16 @@ The following attributes from the notification payload for the `deliver.action_m
 | `email.from.address` | Array | Sender for mail (omit by default, include when `email_address` set to `:include`) |
 | `email.cc.address` | Array | mail CC (omit by default, include when `email_address` set to `:include`) |
 | `email.bcc.address` | Array | mail BCC (omit by default, include when `email_address` set to `:include`)  |
+
 ## Examples
 
 Example usage can be seen in the `./example/trace_request_demonstration.ru` file [here](https://github.com/open-telemetry/opentelemetry-ruby-contrib/blob/main/instrumentation/action_mailer/example/trace_request_demonstration.ru)
 
-
 ## How can I get involved?
 
 The `opentelemetry-instrumentation-action_mailer` gem source is [on GitHub][repo-github], along with related gems including `opentelemetry-api` and `opentelemetry-sdk`.
 
-The OpenTelemetry Ruby gems are maintained by the OpenTelemetry-Ruby special interest group (SIG). You can get involved by joining us in [GitHub Discussions][discussions-url] or attending our weekly meeting. See the [meeting calendar][community-meetings] for dates and times. For more information on this and other language SIGs, see the OpenTelemetry [community page][ruby-sig].
+The OpenTelemetry Ruby gems are maintained by the OpenTelemetry-Ruby special interest group (SIG). You can get involved by joining us on our [GitHub Discussions][discussions-url], [Slack Channel][slack-channel] or attending our weekly meeting. See the [meeting calendar][community-meetings] for dates and times. For more information on this and other language SIGs, see the OpenTelemetry [community page][ruby-sig].
 
 ## License
 
@@ -99,4 +101,5 @@ The `opentelemetry-instrumentation-action_mailer` gem is distributed under the A
 [license-github]: https://github.com/open-telemetry/opentelemetry-ruby-contrib/blob/main/LICENSE
 [ruby-sig]: https://github.com/open-telemetry/community#ruby-sig
 [community-meetings]: https://github.com/open-telemetry/community#community-meetings
+[slack-channel]: https://cloud-native.slack.com/archives/C01NWKKMKMY
 [discussions-url]: https://github.com/open-telemetry/opentelemetry-ruby/discussions

instrumentation/action_pack/README.md

@@ -6,7 +6,7 @@ The Action Pack instrumentation is a community-maintained instrumentation for th
 
 Install the gem using:
 
-```
+```console
 gem install opentelemetry-instrumentation-action_pack
 ```
 
@@ -42,7 +42,6 @@ See the table below for details of what [Rails Framework Hook Events](https://gu
 | - | - | - | - |
 | `process_action.action_controller` | :white_check_mark: | :x: | It modifies the existing Rack span |
 
-
 ### Error Handling for Action Controller
 
 If an error is triggered by Action Controller (such as a 500 internal server error), Action Pack will typically employ the default `ActionDispatch::PublicExceptions.new(Rails.public_path)` as the `exceptions_app`, as detailed in the [documentation](https://guides.rubyonrails.org/configuring.html#config-exceptions-app).
@@ -57,7 +56,7 @@ Example usage can be seen in the `./example/trace_demonstration.rb` file [here](
 
 The `opentelemetry-instrumentation-action_pack` gem source is [on github][repo-github], along with related gems including `opentelemetry-api` and `opentelemetry-sdk`.
 
-The OpenTelemetry Ruby gems are maintained by the OpenTelemetry-Ruby special interest group (SIG). You can get involved by joining us in [GitHub Discussions][discussions-url] or attending our weekly meeting. See the [meeting calendar][community-meetings] for dates and times. For more information on this and other language SIGs, see the OpenTelemetry [community page][ruby-sig].
+The OpenTelemetry Ruby gems are maintained by the OpenTelemetry-Ruby special interest group (SIG). You can get involved by joining us on our [GitHub Discussions][discussions-url], [Slack Channel][slack-channel] or attending our weekly meeting. See the [meeting calendar][community-meetings] for dates and times. For more information on this and other language SIGs, see the OpenTelemetry [community page][ruby-sig].
 
 ## License
 
@@ -68,4 +67,6 @@ The `opentelemetry-instrumentation-action_pack` gem is distributed under the Apa
 [license-github]: https://github.com/open-telemetry/opentelemetry-ruby-contrib/blob/main/LICENSE
 [ruby-sig]: https://github.com/open-telemetry/community#ruby-sig
 [community-meetings]: https://github.com/open-telemetry/community#community-meetings
+[slack-channel]: https://cloud-native.slack.com/archives/C01NWKKMKMY
 [discussions-url]: https://github.com/open-telemetry/opentelemetry-ruby/discussions
+[rails-home]: https://rubyonrails.org/

instrumentation/action_view/README.md

@@ -6,7 +6,7 @@ The ActionView instrumentation is a community-maintained instrumentation for the
 
 Install the gem using:
 
-```
+```console
 gem install opentelemetry-instrumentation-action_view
 gem install opentelemetry-instrumentation-rails
 ```
@@ -56,7 +56,7 @@ end
 
 The `opentelemetry-instrumentation-action_view` gem source is [on github][repo-github], along with related gems including `opentelemetry-api` and `opentelemetry-sdk`.
 
-The OpenTelemetry Ruby gems are maintained by the OpenTelemetry-Ruby special interest group (SIG). You can get involved by joining us in [GitHub Discussions][discussions-url] or attending our weekly meeting. See the [meeting calendar][community-meetings] for dates and times. For more information on this and other language SIGs, see the OpenTelemetry [community page][ruby-sig].
+The OpenTelemetry Ruby gems are maintained by the OpenTelemetry-Ruby special interest group (SIG). You can get involved by joining us on our [GitHub Discussions][discussions-url], [Slack Channel][slack-channel] or attending our weekly meeting. See the [meeting calendar][community-meetings] for dates and times. For more information on this and other language SIGs, see the OpenTelemetry [community page][ruby-sig].
 
 ## License
 
@@ -68,4 +68,5 @@ The `opentelemetry-instrumentation-action_view` gem is distributed under the Apa
 [license-github]: https://github.com/open-telemetry/opentelemetry-ruby-contrib/blob/main/LICENSE
 [ruby-sig]: https://github.com/open-telemetry/community#ruby-sig
 [community-meetings]: https://github.com/open-telemetry/community#community-meetings
+[slack-channel]: https://cloud-native.slack.com/archives/C01NWKKMKMY
 [discussions-url]: https://github.com/open-telemetry/opentelemetry-ruby/discussions