[chore] Standardize markdown by am1r021 · Pull Request #14761 · open-telemetry/opentelemetry-collector

am1r021 · 2026-03-12T18:42:01Z

Description

This change introduces the following Markdown lint standards:

MD001
MD012
MD014

Link to tracking issue

Fixes part of #14731

Testing

No testing is necessary since this mostly touches markdown files.

Documentation

No additional documentation is needed since this fixes styling.

cmd/mdatagen/internal/testdata/readme_with_warnings.md

.markdownlint.yaml

thompson-tomo · 2026-03-13T08:52:39Z

CONTRIBUTING.md

 * Provide a configuration structure which defines the configuration of the component
 * Provide the implementation that performs the component operation

-For more details on components, see the [Adding New Components](https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/main/CONTRIBUTING.md#adding-new-components) document and the tutorial [Building a Trace Receiver](https://opentelemetry.io/docs/collector/trace-receiver/) which provides a detailed example of building a component.


Not sure this is related to mdlint rules.

These links were broken because of the standardization changes shifting what lines the headers were on. It was caught in CI: https://github.com/open-telemetry/opentelemetry-collector/actions/runs/23018206609/job/66847201360. The links referencing specific lines became invalid due to enforcing MD012 since it shifts the lines that references point to.

Also, I'm not sure why the job caught this link breakage just now, since the adding new components header has been removed before this PR. I'd imagine the lines shifting triggered a deeper review of the links since this link wasn't necessarily broken, it just wasn't linking to a specific header, just the file in general.

Shouldn't in this case the link be pointing to Donating New Components which is now a dedicated doc?

I've updated the link to https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/28446b3e2d590451992761222d4c43b7948632d8/docs/new-components.md

cmd/mdatagen/internal/testdata/readme_with_warnings.md

thompson-tomo · 2026-03-13T08:57:07Z

docs/component-status.md

 # Component Status Reporting

-Component status reporting is a collector feature that allows components to report their status (aka health) via status events to extensions. In order for an extension receive these events it must implement the [StatusWatcher interface](https://github.com/open-telemetry/opentelemetry-collector/blob/f05f556780632d12ef7dbf0656534d771210aa1f/extension/extension.go#L54-L63).
+Component status reporting is a collector feature that allows components to report their status (aka health) via status events to extensions. In order for an extension receive these events it must implement the [Watcher interface](https://github.com/open-telemetry/opentelemetry-collector/blob/main/component/componentstatus/status.go).


Why is this link changing?

StatusWatcher was changed to Watcher as per line 1128 in CHANGELOG-API.md. The line references became invalidated due to enforcing MD012.

Line references should still work and be maintained. Also previously this was pinned to a commit rather than main. It would be better to have this pinned to a tag that way the link is less likely to get broken.

I've updated the link to

opentelemetry-collector/component/componentstatus/status.go

Line 35 in 8ae9937

type Watcher interface {

This references the line the new interface is on and also pins to a commit.

thompson-tomo · 2026-03-13T08:57:59Z

docs/component-status.md

-The collector has the concept of a shared component. A shared component is represented as a single component to the collector, but represents multiple logical components elsewhere. The most common usage of this is the OTLP receiver, where a single shared component represents a logical instance for each signal: traces, metrics, and logs (although this can vary based on configuration). When a shared component reports status it must report an event for each of the logical instances it represents. In the current implementation, shared component reports status for all its logical instances during [Start](https://github.com/open-telemetry/opentelemetry-collector/blob/31ac3336d956d93abede6db76453730613e1f076/internal/sharedcomponent/sharedcomponent.go#L89-L98) and [Shutdown](https://github.com/open-telemetry/opentelemetry-collector/blob/31ac3336d956d93abede6db76453730613e1f076/internal/sharedcomponent/sharedcomponent.go#L105-L117). It also [modifies the ReportStatus method](https://github.com/open-telemetry/opentelemetry-collector/blob/31ac3336d956d93abede6db76453730613e1f076/internal/sharedcomponent/sharedcomponent.go#L34-L44) on component.TelemetrySettings to report status for each logical instance when called.
+The collector has the concept of a shared component. A shared component is represented as a single component to the collector, but represents multiple logical components elsewhere. The most common usage of this is the OTLP receiver, where a single shared component represents a logical instance for each signal: traces, metrics, and logs (although this can vary based on configuration). When a shared component reports status it must report an event for each of the logical instances it represents. In the current implementation, shared component reports status for all its logical instances during [Start](https://github.com/open-telemetry/opentelemetry-collector/blob/main/internal/sharedcomponent/sharedcomponent.go) and [Shutdown](https://github.com/open-telemetry/opentelemetry-collector/blob/main/internal/sharedcomponent/sharedcomponent.go). It also [wraps the host's Report method](https://github.com/open-telemetry/opentelemetry-collector/blob/main/internal/sharedcomponent/sharedcomponent.go) to report status for each logical instance when called.


The lines have shifted on this one as well. I'd be happy to update the line references, and as I think of it more, it seems like the way to go, but it's important to note that the CI is not presently and actively picking up when documentation headers are changed and how that interacts with the links throughout the documentation. I'd be happy to take a look into that too.

Yeap update the line numbers & ideally also pin it to a tag rather than main. That way the links are less likely to get broken.

Fixed. Just a heads up, lychee will error out on this because it cannot access the page, even though the link is reachable.

thompson-tomo · 2026-03-13T08:58:34Z

docs/release.md

+1. The [Core](#releasing-opentelemetry-collector-core-release-manager) collector, including the collector builder CLI tool.
+2. The [Contrib](#releasing-opentelemetry-collector-contrib-contrib-release-manager) collector repository, containing Collector components.
+3. The [artifacts](#producing-the-artifacts-releases-release-manager)


These headers were changed in the documentation previously but not updated, and the link discrepancies were picked up in the CI on this PR.

I've updated these links as suggested to point commit as well so that they don't break.

…y-collector into standardize-markdown

docs/release.md

CONTRIBUTING.md

docs/component-status.md

thompson-tomo · 2026-03-17T13:03:40Z

@am1r021 can you also add a lychee remap rule https://lychee.cli.rs/recipes/migration/ to convert

https://github.com/(.*)#L[0-9]+(-[0-9])? to https://github.com/$1 which should fix the CI issue.

Also you might want to add the file used for tests to a .markdownlintignore file.

Co-authored-by: James Thompson <thompson.tomo@outlook.com>

codspeed-hq · 2026-03-25T21:59:03Z

Merging this PR will not alter performance

⚠️

Unknown Walltime execution environment detected

Using the Walltime instrument on standard Hosted Runners will lead to inconsistent data.

For the most accurate results, we recommend using CodSpeed Macro Runners: bare-metal machines fine-tuned for performance measurement consistency.

✅ 7 untouched benchmarks
⏩ 76 skipped benchmarks¹

_{Comparing am1r021:standardize-markdown (53776ce) with main (ba01037)}

76 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩

.github/lychee.toml

cmd/mdatagen/internal/testdata/readme_with_warnings.md

Co-authored-by: James Thompson <thompson.tomo@outlook.com>

codecov · 2026-03-26T17:51:51Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 91.30%. Comparing base (ba01037) to head (53776ce).

Additional details and impacted files

@@            Coverage Diff             @@
##             main   #14761      +/-   ##
==========================================
- Coverage   91.32%   91.30%   -0.03%     
==========================================
  Files         697      697              
  Lines       44459    44459              
==========================================
- Hits        40604    40595       -9     
- Misses       2716     2722       +6     
- Partials     1139     1142       +3

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

mx-psi

Thanks for this PR!

There are some link changes that I would rather not change and that I think are not related to the markdownlint new rules. Could we revert those/fix things differently before moving forward?

mx-psi · 2026-03-27T10:44:00Z

docs/component-status.md

 # Component Status Reporting

-Component status reporting is a collector feature that allows components to report their status (aka health) via status events to extensions. In order for an extension receive these events it must implement the [StatusWatcher interface](https://github.com/open-telemetry/opentelemetry-collector/blob/f05f556780632d12ef7dbf0656534d771210aa1f/extension/extension.go#L54-L63).
+Component status reporting is a collector feature that allows components to report their status (aka health) via status events to extensions. In order for an extension receive these events it must implement the [Watcher interface](https://github.com/open-telemetry/opentelemetry-collector/blob/v0.147.0/component/componentstatus/status.go#L35).


Why is this change needed? The previous link is valid. We don't typically keep RFCs up to date when further changes have happened, I think we should revert this

mx-psi · 2026-03-27T10:44:17Z

docs/component-status.md

 **sharedcomponent**

-The collector has the concept of a shared component. A shared component is represented as a single component to the collector, but represents multiple logical components elsewhere. The most common usage of this is the OTLP receiver, where a single shared component represents a logical instance for each signal: traces, metrics, and logs (although this can vary based on configuration). When a shared component reports status it must report an event for each of the logical instances it represents. In the current implementation, shared component reports status for all its logical instances during [Start](https://github.com/open-telemetry/opentelemetry-collector/blob/31ac3336d956d93abede6db76453730613e1f076/internal/sharedcomponent/sharedcomponent.go#L89-L98) and [Shutdown](https://github.com/open-telemetry/opentelemetry-collector/blob/31ac3336d956d93abede6db76453730613e1f076/internal/sharedcomponent/sharedcomponent.go#L105-L117). It also [modifies the ReportStatus method](https://github.com/open-telemetry/opentelemetry-collector/blob/31ac3336d956d93abede6db76453730613e1f076/internal/sharedcomponent/sharedcomponent.go#L34-L44) on component.TelemetrySettings to report status for each logical instance when called.
+The collector has the concept of a shared component. A shared component is represented as a single component to the collector, but represents multiple logical components elsewhere. The most common usage of this is the OTLP receiver, where a single shared component represents a logical instance for each signal: traces, metrics, and logs (although this can vary based on configuration). When a shared component reports status it must report an event for each of the logical instances it represents. In the current implementation, shared component reports status for all its logical instances during [Start](https://github.com/open-telemetry/opentelemetry-collector/blob/v0.147.0/internal/sharedcomponent/sharedcomponent.go#L89-L98) and [Shutdown](https://github.com/open-telemetry/opentelemetry-collector/blob/v0.147.0/internal/sharedcomponent/sharedcomponent.go#L105-L117). It also [wraps the host's Report method](https://github.com/open-telemetry/opentelemetry-collector/blob/v0.147.0/internal/sharedcomponent/sharedcomponent.go#L34-L44) to report status for each logical instance when called.


ditto, I don't think we should change the links here

mx-psi · 2026-03-27T10:45:11Z

docs/release.md

-1. The [Core](#releasing-opentelemetry-collector) collector, including the collector builder CLI tool.
-2. The [Contrib](#releasing-opentelemetry-collector-contrib) collector repository, containing Collector components.
-3. The [artifacts](#producing-the-artifacts)
+1. The [Core](https://github.com/open-telemetry/opentelemetry-collector/blob/v0.147.0/docs/release.md#releasing-opentelemetry-collector-core-release-manager) collector, including the collector builder CLI tool.
+2. The [Contrib](https://github.com/open-telemetry/opentelemetry-collector/blob/v0.147.0/docs/release.md#releasing-opentelemetry-collector-contrib-contrib-release-manager) collector repository, containing Collector components.
+3. The [artifacts](https://github.com/open-telemetry/opentelemetry-collector/blob/v0.147.0/docs/release.md#producing-the-artifacts-releases-release-manager)


I would rather keep these as relative links

mx-psi · 2026-03-27T10:46:14Z

CONTRIBUTING.md

 * Provide the implementation that performs the component operation

-For more details on components, see the [Donating New Components](https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/main/CONTRIBUTING.md#donating-new-components) document and the tutorial [Building a Trace Receiver](https://opentelemetry.io/docs/collector/trace-receiver/) which provides a detailed example of building a component.
+For more details on components, see the [Donating New Components](https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/v0.147.0/docs/new-components.md) document and the tutorial [Building a Trace Receiver](https://opentelemetry.io/docs/collector/trace-receiver/) which provides a detailed example of building a component.


I would prefer to keep the link to main here. I understand this may not be the best practice for linking to an arbitrary repo, but this is a repo we control so I feel confident we can keep it working

am1r021 added 3 commits March 12, 2026 11:12

Introduce MD001

7752217

Introduce MD012

742dc7f

Introduce MD014

486b5c8

am1r021 requested review from a team, bogdandrutu, codeboten, dmitryax, evan-bradley and mx-psi as code owners March 12, 2026 18:42

am1r021 changed the title ~~Standardize markdown~~ [chore] Standardize markdown Mar 12, 2026

Fix broken links

71ef22f

dmitryax reviewed Mar 12, 2026

View reviewed changes

cmd/mdatagen/internal/testdata/readme_with_warnings.md Outdated Show resolved Hide resolved

thompson-tomo reviewed Mar 13, 2026

View reviewed changes

am1r021 added 7 commits March 13, 2026 09:47

Remove unnecessary config lines

f8a2aad

Merge branch 'main' of https://github.com/open-telemetry/opentelemetr…

4a5fde8

…y-collector into standardize-markdown

Merge branch 'main' of https://github.com/open-telemetry/opentelemetr…

1340ced

…y-collector into standardize-markdown

Fix updated links

743e5b1

Fix capitalization

b2fc773

Fix link

4e52431

Use blob for updated links

b7504b0

am1r021 requested review from dmathieu, dmitryax and thompson-tomo March 16, 2026 18:31

thompson-tomo reviewed Mar 17, 2026

View reviewed changes

docs/release.md Outdated Show resolved Hide resolved

CONTRIBUTING.md Outdated Show resolved Hide resolved

docs/component-status.md Outdated Show resolved Hide resolved

docs/component-status.md Outdated Show resolved Hide resolved

am1r021 and others added 5 commits March 25, 2026 14:19

Update docs/component-status.md

8cd5a8a

Co-authored-by: James Thompson <thompson.tomo@outlook.com>

Update docs/component-status.md

c694758

Co-authored-by: James Thompson <thompson.tomo@outlook.com>

Update CONTRIBUTING.md

dd3114d

Co-authored-by: James Thompson <thompson.tomo@outlook.com>

Update docs/release.md

2e91bc2

Co-authored-by: James Thompson <thompson.tomo@outlook.com>

Merge branch 'main' into standardize-markdown

907ce69

am1r021 added 2 commits March 25, 2026 14:52

Add test files to markdown ignore file

4f78437

Add remapping rule

e7c7ff9

am1r021 force-pushed the standardize-markdown branch from 708eef6 to e7c7ff9 Compare March 25, 2026 21:53

am1r021 requested a review from thompson-tomo March 25, 2026 22:15

thompson-tomo reviewed Mar 25, 2026

View reviewed changes

.github/lychee.toml Outdated Show resolved Hide resolved

cmd/mdatagen/internal/testdata/readme_with_warnings.md Outdated Show resolved Hide resolved

am1r021 and others added 2 commits March 26, 2026 10:38

Update .github/lychee.toml

aaaa683

Co-authored-by: James Thompson <thompson.tomo@outlook.com>

Update cmd/mdatagen/internal/testdata/readme_with_warnings.md

5754fcb

Co-authored-by: James Thompson <thompson.tomo@outlook.com>

am1r021 requested a review from thompson-tomo March 26, 2026 17:38

thompson-tomo approved these changes Mar 27, 2026

View reviewed changes

Merge branch 'main' into standardize-markdown

53776ce

mx-psi reviewed Mar 27, 2026

View reviewed changes

		The collector has the concept of a shared component. A shared component is represented as a single component to the collector, but represents multiple logical components elsewhere. The most common usage of this is the OTLP receiver, where a single shared component represents a logical instance for each signal: traces, metrics, and logs (although this can vary based on configuration). When a shared component reports status it must report an event for each of the logical instances it represents. In the current implementation, shared component reports status for all its logical instances during [Start](https://github.com/open-telemetry/opentelemetry-collector/blob/31ac3336d956d93abede6db76453730613e1f076/internal/sharedcomponent/sharedcomponent.go#L89-L98) and [Shutdown](https://github.com/open-telemetry/opentelemetry-collector/blob/31ac3336d956d93abede6db76453730613e1f076/internal/sharedcomponent/sharedcomponent.go#L105-L117). It also [modifies the ReportStatus method](https://github.com/open-telemetry/opentelemetry-collector/blob/31ac3336d956d93abede6db76453730613e1f076/internal/sharedcomponent/sharedcomponent.go#L34-L44) on component.TelemetrySettings to report status for each logical instance when called.
		The collector has the concept of a shared component. A shared component is represented as a single component to the collector, but represents multiple logical components elsewhere. The most common usage of this is the OTLP receiver, where a single shared component represents a logical instance for each signal: traces, metrics, and logs (although this can vary based on configuration). When a shared component reports status it must report an event for each of the logical instances it represents. In the current implementation, shared component reports status for all its logical instances during [Start](https://github.com/open-telemetry/opentelemetry-collector/blob/main/internal/sharedcomponent/sharedcomponent.go) and [Shutdown](https://github.com/open-telemetry/opentelemetry-collector/blob/main/internal/sharedcomponent/sharedcomponent.go). It also [wraps the host's Report method](https://github.com/open-telemetry/opentelemetry-collector/blob/main/internal/sharedcomponent/sharedcomponent.go) to report status for each logical instance when called.

Conversation

am1r021 commented Mar 12, 2026

Description

Link to tracking issue

Testing

Documentation

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

am1r021 Mar 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

am1r021 Mar 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

am1r021 Mar 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

am1r021 Mar 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

am1r021 Mar 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

am1r021 Mar 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

thompson-tomo commented Mar 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

codspeed-hq bot commented Mar 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Merging this PR will not alter performance

Footnotes

Uh oh!

Uh oh!

Uh oh!

codecov bot commented Mar 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

mx-psi left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

am1r021 Mar 13, 2026 •

edited

Loading

am1r021 Mar 16, 2026 •

edited

Loading

am1r021 Mar 13, 2026 •

edited

Loading

am1r021 Mar 16, 2026 •

edited

Loading

am1r021 Mar 13, 2026 •

edited

Loading

am1r021 Mar 16, 2026 •

edited

Loading

thompson-tomo commented Mar 17, 2026 •

edited

Loading

codspeed-hq bot commented Mar 25, 2026 •

edited

Loading

codecov bot commented Mar 26, 2026 •

edited

Loading