Code block callouts do not render in code

[bmorelli25]

The bug

The ordered list below code blocks work, but the code callouts do not render within the code block.

EDIT: There is an additional bug where a code block and the corresponding list after the code block have both 8 elements. The following error is reported:

Code block has 7 callouts but the following list only has 8

Code block here

receivers: <1>
  # ...
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
      http:
        endpoint: 0.0.0.0:4318
processors: <2>
  # ...
  memory_limiter:
    check_interval: 1s
    limit_mib: 2000
  batch:

exporters:
  debug:
    verbosity: detailed <3>
  otlp: <4>
    # Elastic APM server https endpoint without the "https://" prefix
    endpoint: "${env:ELASTIC_APM_SERVER_ENDPOINT}" <5> <7>
    headers:
      # Elastic APM Server secret token
      Authorization: "Bearer ${env:ELASTIC_APM_SECRET_TOKEN}" <6> <7>

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [..., memory_limiter, batch]
      exporters: [debug, otlp]
    metrics:
      receivers: [otlp]
      processors: [..., memory_limiter, batch]
      exporters: [debug, otlp]
    logs: <8>
      receivers: [otlp]
      processors: [..., memory_limiter, batch]
      exporters: [debug, otlp]

1. The receivers, like the OTLP receiver, that forward data emitted by APM agents, or the host metrics receiver.
2. We recommend using the Batch processor and the memory limiter processor. For more information, see recommended processors.
3. The debug exporter is helpful for troubleshooting, and supports configurable verbosity levels: basic (default), normal, and detailed.
4. Elastic {observability} endpoint configuration. APM Server supports a ProtoBuf payload via both the OTLP protocol over gRPC transport (OTLP/gRPC) and the OTLP protocol over HTTP transport (OTLP/HTTP). To learn more about these exporters, see the OpenTelemetry Collector documentation: OTLP/HTTP Exporter or OTLP/gRPC exporter. When adding an endpoint to an existing configuration an optional name component can be added, like otlp/elastic, to distinguish endpoints as described in the OpenTelemetry Collector Configuration Basics.
5. Hostname and port of the APM Server endpoint. For example, elastic-apm-server:8200.
6. Credential for Elastic APM secret token authorization (Authorization: "Bearer a_secret_token") or API key authorization (Authorization: "ApiKey an_api_key").
7. Environment-specific configuration parameters can be conveniently passed in as environment variables documented here (e.g. ELASTIC_APM_SERVER_ENDPOINT and ELASTIC_APM_SECRET_TOKEN).
8. [preview] To send OpenTelemetry logs to {stack} version 8.0+, declare a logs pipeline.

What I expected

Users should see both the callout in the code and corresponding callout below the code block.

Example

[reakaleek]

@bmorelli25 could you please rephrase the expected output?

Should both show the comment in code and the callout at the bottom be visible?

Or should the corresponding number be at that line of code?

[bmorelli25]

Yes, sorry.

Should both show the comment in code and the callout at the bottom be visible? Or should the corresponding number be at that line of code?

The latter. The corresponding number should be shown in the code block. The number and callout text should be shown below the code block. For example, here's what this feature looks like in our asciidoc system:

[colleenmcginnis]

This is subjective, but I think we should consider styling the numbers below the code snippet differently than a regular ordered list in addition to adding number annotations to the code snippet itself.

[marciw]

This is subjective, but I think we should consider styling the numbers below the code snippet differently than a regular ordered list in addition to adding number annotations to the code snippet itself.

+1 to this -- here's an example where even if the callout numbers were present in the code block, the regular ordered list below it might not look connected https://bookish-dollop-9p66716.pages.github.io/logs-data-stream.html#how-to-use-logsds
(compare https://www.elastic.co/guide/en/elasticsearch/reference/current/logs-data-stream.html#how-to-use-logsds)

[bmorelli25]

Thank you! I see two separate issues here:

1. An issue to fix the bug where code block callouts do not render in code (this issue).
2. A design enhancement to update the styling of code block callouts.

I've opened #328 to address the latter.

[reakaleek]

Will be fixed by #346