Add prefer-blockquote-vs-docsy-alerts rule, apply rule to en pages, plus some copyedits (#9659)

Author: chalin

.cspell.yml

@@ -89,7 +89,7 @@ words:
   - Crossplane
   - crosspost
   - desaturate
-  - Docsy
+  - docsy
   - errorf
   - excerpter
   - favicons

.cspell/en-words.txt

@@ -16,6 +16,7 @@ autoloaded
 autoloader
 autoloading
 backoff
+blockquotes
 caml
 cartservice
 cassandra

.markdownlint-cli2.yaml

@@ -1,4 +1,5 @@
 customRules:
+  - ./scripts/_md-rules/prefer-blockquote-vs-docsy-alerts/index.mjs
   - ./scripts/_md-rules/alert-type-not-translated.mjs
   - ./scripts/_md-rules/unindent-code-blocks.js
   - ./scripts/_md-rules/trim-code-blank-lines.js

.markdownlint.yaml

@@ -41,6 +41,10 @@ table-column-style: false # Causes problems in ja and zh pages
 
 gh-url-hash: false
 
+# Prefer blockquote alerts in English docs; enabled under content/en only. See
+# content/en/.markdownlint.yaml.
+prefer-blockquote-vs-docsy-alerts: false
+
 # Custom rules registered in .markdownlint-cli2.yaml are enabled by default
 # (via `default: true` above). Only list custom rules here to disable them or
 # to provide configuration. Rules that need no config can be omitted.

content/en/.markdownlint.yaml

@@ -0,0 +1,3 @@
+extends: ../../.markdownlint.yaml
+
+prefer-blockquote-vs-docsy-alerts: true

content/en/docs/contributing/sig-practices.md

@@ -5,7 +5,7 @@ description:
   Learn how approvers and maintainers manage issues and contributions.
 weight: 999
 # prettier-ignore
-cSpell:ignore: Comms contribfest docsy hotfixes inactivitiy onboarded triager triagers
+cSpell:ignore: Comms contribfest hotfixes inactivitiy onboarded triager triagers
 ---
 
 This pages includes guidelines and some common practices used by approvers and

content/en/docs/contributing/style-guide.md

@@ -130,6 +130,10 @@ To enforce standards and consistency for Markdown files, all files should follow
 certain rules, enforced by [markdownlint][]. For a full list, check the
 [.markdownlint.yaml][] and [.markdownlint-cli2.yaml][] files.
 
+When legitimate exceptions to a rule exists, use `markdownlint-disable`
+directive to suppress the rule warnings. For details, see the
+[markdownlint documentation](https://github.com/DavidAnson/markdownlint#configuration).
+
 We also enforce Markdown [file format](#file-format) and strip files of trailing
 whitespace. This precludes the [line break syntax][] of 2+ spaces; use `<br>`
 instead or reformat your text.

content/en/docs/languages/dotnet/exporters.md

@@ -275,34 +275,30 @@ var meterProvider = Sdk.CreateMeterProviderBuilder()
     .Build();
 ```
 
-{{% alert title=Note %}}
-
-Make sure Prometheus is started with the OTLP receiver enabled:
-
-```sh
-./prometheus --web.enable-otlp-receiver
-```
-
-Or when using Docker:
-
-```sh
-docker run -p 9090:9090 prom/prometheus --web.enable-otlp-receiver
-```
-
-{{% /alert %}}
+> [!NOTE]
+>
+> Make sure Prometheus is started with the OTLP receiver enabled:
+>
+> ```sh
+> ./prometheus --web.enable-otlp-receiver
+> ```
+>
+> Or when using Docker:
+>
+> ```sh
+> docker run -p 9090:9090 prom/prometheus --web.enable-otlp-receiver
+> ```
 
 #### Using Prometheus Exporter (Pull/Scrape) {#prometheus-exporter}
 
 This approach exposes a metrics endpoint in your application (e.g., `/metrics`)
 that Prometheus scrapes at regular intervals.
 
-{{% alert color="warning" title="Warning" %}}
-
-This exporter is still under development and doesn't support exemplars. For
-production environments, consider using the
-[OTLP exporter approach](#prometheus-otlp) instead.
-
-{{% /alert %}}
+> [!WARNING]
+>
+> This exporter is still under development and doesn't support exemplars. For
+> production environments, consider using the
+> [OTLP exporter approach](#prometheus-otlp) instead.
 
 ##### Dependencies {#prometheus-dependencies}
 

content/en/docs/languages/go/exporters.md

@@ -70,22 +70,20 @@ func main() {
 }
 ```
 
-{{% alert title="Note" color="info" %}}
-
-The standard OTLP exporter packages (`otlptracegrpc`, `otlptracehttp`, etc.)
-already read most OTLP environment variables such as
-`OTEL_EXPORTER_OTLP_ENDPOINT`, `OTEL_EXPORTER_OTLP_HEADERS`,
-`OTEL_EXPORTER_OTLP_TIMEOUT`, and `OTEL_EXPORTER_OTLP_COMPRESSION`.
-
-The `autoexport` package adds support for the **exporter selector variables**
-(`OTEL_TRACES_EXPORTER`, `OTEL_METRICS_EXPORTER`, `OTEL_LOGS_EXPORTER`) that
-choose _which_ exporter implementation to use. This separation keeps binary
-sizes smaller by not bundling exporter dependencies (like gRPC) unless
-explicitly imported.
-
-Also note that `OTEL_SDK_DISABLED` is not currently supported by the Go SDK.
-
-{{% /alert %}}
+> [!NOTE]
+>
+> The standard OTLP exporter packages (`otlptracegrpc`, `otlptracehttp`, etc.)
+> already read most OTLP environment variables such as
+> `OTEL_EXPORTER_OTLP_ENDPOINT`, `OTEL_EXPORTER_OTLP_HEADERS`,
+> `OTEL_EXPORTER_OTLP_TIMEOUT`, and `OTEL_EXPORTER_OTLP_COMPRESSION`.
+>
+> The `autoexport` package adds support for the **exporter selector variables**
+> (`OTEL_TRACES_EXPORTER`, `OTEL_METRICS_EXPORTER`, `OTEL_LOGS_EXPORTER`) that
+> choose _which_ exporter implementation to use. This separation keeps binary
+> sizes smaller by not bundling exporter dependencies (like gRPC) unless
+> explicitly imported.
+>
+> Also note that `OTEL_SDK_DISABLED` is not currently supported by the Go SDK.
 
 For a complete overview of which environment variables are supported by the Go
 SDK and contrib packages, see the

content/en/docs/languages/go/sampling.md

@@ -8,8 +8,7 @@ spans that are generated by a system. The exact sampler you should use depends
 on your specific needs, but in general you should make a decision at the start
 of a trace, and allow the sampling decision to propagate to other services.
 
-A [`Sampler`](https://pkg.go.dev/go.opentelemetry.io/otel/sdk/trace#Sampler) can
-be set on the tracer provider using the
+A [`Sampler`][] can be set on the tracer provider using the
 [`WithSampler`](https://pkg.go.dev/go.opentelemetry.io/otel/sdk/trace#WithSampler)
 option, as follows:
 
@@ -46,31 +45,27 @@ the `TraceIDRatioBased` sampler.
 ## Custom samplers
 
 If the built-in samplers don't meet your needs, you can create a custom sampler
-by implementing the
-[`Sampler`](https://pkg.go.dev/go.opentelemetry.io/otel/sdk/trace#Sampler)
-interface. A custom sampler must implement two methods:
+by implementing the [`Sampler`][] interface. A custom sampler must implement two
+methods:
 
 - `ShouldSample(parameters SamplingParameters) SamplingResult`: Makes the
   sampling decision based on the provided parameters.
 - `Description() string`: Returns a description of the sampler.
 
-### Preserving tracestate
-
-{{% alert title="Critical: Preserve tracestate" color="warning" %}}
-
-When implementing a custom sampler, you **must** preserve the parent's
-tracestate in your `SamplingResult`. Failing to do so breaks context propagation
-in distributed systems that rely on tracestate for passing vendor-specific or
-application-specific trace data.
-
-Always extract the tracestate from the parent span context:
-
-```go
-psc := trace.SpanContextFromContext(parameters.ParentContext)
-// Use psc.TraceState() in your SamplingResult
-```
-
-{{% /alert %}}
+> [!IMPORTANT] Preserve parent tracestate
+>
+> In `ShouldSample`, you _must_ preserve the parent's tracestate in your
+> `SamplingResult`. Failing to do so breaks context propagation in distributed
+> systems that rely on tracestate for passing vendor-specific or
+> application-specific trace data.
+>
+> Extract the tracestate from the parent span context:
+>
+> ```go
+> psc := trace.SpanContextFromContext(parameters.ParentContext)
+> ```
+>
+> Pass `psc.TraceState()` through when you build your `SamplingResult`.
 
 ### Example
 
@@ -167,3 +162,5 @@ When implementing custom samplers, keep these points in mind:
 2. **Heavy computations in ShouldSample**: The `ShouldSample` function is called
    synchronously for every span creation. Avoid expensive operations like
    network calls or complex computations that could impact performance.
+
+[`Sampler`]: https://pkg.go.dev/go.opentelemetry.io/otel/sdk/trace#Sampler