refactor : Rename and split up Collector installation page #8370

adity1raut · 2025-11-09T11:17:28Z

Description

This PR Fixed #8353 refactors the Collector installation documentation by renaming, restructuring, and splitting the existing installation page into multiple focused sections. The goal is to improve clarity, organization, and navigation within the documentation.

Changes ...

Changes

Rename the page and update front matter:

Move and rename the file to index.md.

Add an alias in the front matter:

aliases: [/docs/collector/installation/]

Create new child pages:
- content/en/docs/collector/install/docker.md — Install the Collector with Docker
- content/en/docs/collector/install/kubernetes.md — Install the Collector with Kubernetes
- index.md — Install from a Collector binary
- content/en/docs/collector/install/binary/linux.md — Install the Collector on Linux
- content/en/docs/collector/install/binary/macos.md — Install the Collector on macOS
- content/en/docs/collector/install/binary/windows.md — Install the Collector on Windows

Each new child page includes front matter with a redirect from the old location.

Content migration:

Keep the page title and first two paragraphs on /install/.
Move Docker, Docker Compose, Kubernetes, Linux, macOS, and Windows installation instructions to their respective child pages.
Retain the “Build from Source” section on /install/.
Remove the Nomad section.

Update cross-references:

Fix references to /docs/collector/installation/ in quick-start.md (line 131) and anywhere else within the English documentation.

Related Issues / References

N/A (Add issue link if applicable)

Additional Notes

This restructuring improves the logical flow and maintainability of Collector installation documentation.
Run npm run fix:all locally to ensure style and formatting compliance.

Preview: https://deploy-preview-8370--opentelemetry.netlify.app/docs/collector/install/
Redirect test: https://deploy-preview-8370--opentelemetry.netlify.app/docs/collector/installation/

Signed-off-by: adity1raut <araut7798@gmail.com>

adity1raut · 2025-11-09T11:21:19Z

PTAL @tiffany76

tiffany76

This is looking pretty good, @adity1raut! I've left some comments based on my first-pass review. Once we address those, I'll take a closer look. Thanks!

content/en/docs/collector/Install/_index.md

tiffany76 · 2025-11-13T01:17:08Z

content/en/docs/collector/Install/binary/linux.md

@@ -0,0 +1,140 @@
+---
+title: Install the Collector on Linux
+aliases: [../installation/#linux]


@chalin I know this alias won't work because the source is a fragment. How do we keep the fragment's target and point it to an alert about refactoring?

content/en/docs/collector/install/_index.md

content/en/docs/collector/install/binary/linux.md

Signed-off-by: adity1raut <araut7798@gmail.com>

adity1raut · 2025-11-15T03:51:49Z

@tiffany76 Can you please Give me review

content/en/docs/collector/install/_index.md

content/en/docs/collector/install/binary/_index.md

chalin

@tiffany76 - is there a reason to prefer naming the section install vs the original installation? If we keep the original name then we won't need any aliases.

(And your right, there should be a single alias in this refactoring.)

tiffany76 · 2025-11-17T19:00:37Z

@chalin All of the top level pages that instruct people how to do things will be verbs: Install, Configure, Deploy, Manage, Extend. I'd like the iA to be uniform.

chalin · 2025-11-17T19:07:44Z

@tiffany76 - that works for me. Then this PR should have a single alias in the install/_index.md file. As you know, we can't redirect fragments/hashes (at least not using just Netlify's redirect facility ... which is what we want to stick to -- we're just trying to prevent 404s). Folks will figure out what subpage to visit.

chalin

If @tiffany76 agrees with the linkTitles, add appropriate linkTitle entries to each page based on the examples I have given in the comments below.

content/en/docs/collector/install/binary/_index.md

content/en/docs/collector/install/binary/linux.md

content/en/docs/collector/install/_index.md

chalin · 2025-11-17T19:13:26Z

/fix:refcache

otelbot · 2025-11-17T19:21:12Z

ℹ️ fix:refcache made no changes. Nothing to commit.

tiffany76 · 2025-11-18T01:19:27Z

If @tiffany76 agrees with the linkTitles, add appropriate linkTitle entries to each page based on the examples I have given in the comments below.

I think they're probably good, but I'd like to get the page weights sorted out so I can see how the nav looks in the preview before settling for sure on the linkTitles.

tiffany76

Hi @adity1raut! I've made some suggested changes to address the outstanding issues. If you commit them, I'll do a final review and we can hopefully get this merged. Thanks!

content/en/docs/collector/install/binary/linux.md

content/en/docs/collector/install/binary/macos.md

content/en/docs/collector/install/binary/windows.md

content/en/docs/collector/install/docker.md

content/en/docs/collector/install/kubernetes.md

content/en/docs/collector/install/binary/_index.md

tiffany76 · 2025-11-21T22:06:37Z

The link checker also found that a 2024 blog post is referring to the old installation page. If you can update the reference in blog/2024/llm-observability/index.html to point to the new URL, that should resolve the current CI failure. Thanks.

Signed-off-by: adity1raut <araut7798@gmail.com>

content/en/docs/collector/install/kubernetes.md

content/en/docs/collector/install/docker.md

Co-authored-by: Patrice Chalin <chalin@users.noreply.github.com>

content/en/docs/collector/install/binary/_index.md

content/en/docs/collector/install/binary/linux.md

tiffany76 · 2025-11-26T02:03:44Z

@adity1raut I'm repasting my earlier comment. This PR is very close, but you'll need to fix the following issue before we can move forward. Thanks!

The link checker also found that a 2024 blog post is referring to the old installation page. If you can update the reference in blog/2024/llm-observability/index.html to point to the new URL, that should resolve the current CI failure. Thanks.

content/en/docs/collector/install/_index.md

Signed-off-by: Tiffany Hrabusa <tiffany.hrabusa@grafana.com>

tiffany76

Hi @adity1raut - I updated the 2024 blog post on your branch because we need to get this merged.

Thanks for your contribution!

otelbot · 2025-12-03T19:02:21Z

Thank you for your contribution @adity1raut! 🎉 We would like to hear from you about your experience contributing to OpenTelemetry by taking a few minutes to fill out this survey.

…metry#8370) Signed-off-by: adity1raut <araut7798@gmail.com> Signed-off-by: Tiffany Hrabusa <tiffany.hrabusa@grafana.com> Co-authored-by: Tiffany Hrabusa <30397949+tiffany76@users.noreply.github.com> Co-authored-by: Patrice Chalin <chalin@users.noreply.github.com> Co-authored-by: Tiffany Hrabusa <tiffany.hrabusa@grafana.com>

Update Installation

5dd9ad8

Signed-off-by: adity1raut <araut7798@gmail.com>

adity1raut requested a review from a team as a code owner November 9, 2025 11:17

github-project-automation bot added this to SIG Comms: PRs & Issues Nov 9, 2025

github-actions bot added the sig:collector label Nov 9, 2025

otelbot-docs bot requested review from a team and codeboten and removed request for a team November 9, 2025 11:17

Solve

0068fe7

Signed-off-by: adity1raut <araut7798@gmail.com>

otelbot-docs bot requested a review from a team November 9, 2025 11:19

theletterf requested a review from tiffany76 November 11, 2025 08:43

tiffany76 reviewed Nov 13, 2025

View reviewed changes

pdate After REview

d9d0fc7

Signed-off-by: adity1raut <araut7798@gmail.com>

adity1raut requested a review from tiffany76 November 13, 2025 06:09

Solve The Confige:

8f9f006

Signed-off-by: adity1raut <araut7798@gmail.com>

tiffany76 reviewed Nov 17, 2025

View reviewed changes

content/en/docs/collector/install/_index.md Outdated Show resolved Hide resolved

tiffany76 reviewed Nov 17, 2025

View reviewed changes

content/en/docs/collector/install/binary/_index.md Outdated Show resolved Hide resolved

chalin force-pushed the install branch from 8f9f006 to 3bb3cd6 Compare November 17, 2025 18:50

chalin reviewed Nov 17, 2025

View reviewed changes

svrnm mentioned this pull request Nov 20, 2025

rename and split the installation page #8454

Closed

2 tasks

tiffany76 reviewed Nov 21, 2025

View reviewed changes

tiffany76 added this to the otelcol-phase-1 milestone Nov 21, 2025

github-project-automation bot moved this to Backlog in SIG Comms + SIG Collector: Doc refactoring Nov 21, 2025

tiffany76 moved this from Backlog to In progress in SIG Comms + SIG Collector: Doc refactoring Nov 21, 2025

tiffany76 added the sig:collector:refactor These issues are part of the Collector documentation refactoring project. label Nov 21, 2025

Update Ater Review

e6dff0c

Signed-off-by: adity1raut <araut7798@gmail.com>

adity1raut force-pushed the install branch from 3bb3cd6 to e6dff0c Compare November 22, 2025 08:28

adity1raut requested review from chalin and tiffany76 November 22, 2025 08:29

tiffany76 reviewed Nov 26, 2025

View reviewed changes

content/en/docs/collector/install/kubernetes.md Outdated Show resolved Hide resolved

content/en/docs/collector/install/docker.md Outdated Show resolved Hide resolved

Apply suggestions from code review

7d5a702

Co-authored-by: Patrice Chalin <chalin@users.noreply.github.com>

tiffany76 reviewed Nov 26, 2025

View reviewed changes

content/en/docs/collector/install/binary/_index.md Show resolved Hide resolved

content/en/docs/collector/install/binary/linux.md Show resolved Hide resolved

Apply suggestions from code review

9983fd7

tiffany76 moved this from In progress to In review in SIG Comms + SIG Collector: Doc refactoring Nov 26, 2025

chalin reviewed Nov 26, 2025

View reviewed changes

content/en/docs/collector/install/_index.md Outdated Show resolved Hide resolved

chalin and others added 3 commits November 26, 2025 11:35

Update content/en/docs/collector/install/_index.md

c9c6397

Merge branch 'main' into install

0243389

Update 2024 blog

233bb3f

Signed-off-by: Tiffany Hrabusa <tiffany.hrabusa@grafana.com>

github-actions bot added the blog label Dec 3, 2025

otelbot-docs bot requested a review from a team December 3, 2025 18:51

tiffany76 approved these changes Dec 3, 2025

View reviewed changes

tiffany76 added this pull request to the merge queue Dec 3, 2025

tiffany76 mentioned this pull request Dec 3, 2025

[otelcol docs] Rename and split up Collector installation page #8353

Closed

17 tasks

Merged via the queue into open-telemetry:main with commit ec1657d Dec 3, 2025
22 checks passed

github-project-automation bot moved this from In review to Done in SIG Comms + SIG Collector: Doc refactoring Dec 3, 2025

github-project-automation bot moved this to Done in SIG Comms: PRs & Issues Dec 3, 2025

tiffany76 mentioned this pull request Dec 3, 2025

[docs] Copy edit Collector installation page (#8354) #8542

Open

2 tasks

jaehanbyun mentioned this pull request Dec 7, 2025

[Collector] Standardize distribution in Quick Start & Installation #8430

Merged

refactor : Rename and split up Collector installation page #8370

refactor : Rename and split up Collector installation page #8370

Uh oh!

Conversation

adity1raut commented Nov 9, 2025 • edited by chalin Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Changes

Related Issues / References

Additional Notes

Uh oh!

adity1raut commented Nov 9, 2025

Uh oh!

tiffany76 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

tiffany76 Nov 13, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

adity1raut commented Nov 15, 2025

Uh oh!

Uh oh!

Uh oh!

chalin left a comment • 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!

tiffany76 commented Nov 17, 2025

Uh oh!

chalin commented Nov 17, 2025

Uh oh!

chalin left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

chalin commented Nov 17, 2025

Uh oh!

otelbot bot commented Nov 17, 2025

Uh oh!

tiffany76 commented Nov 18, 2025

Uh oh!

tiffany76 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

tiffany76 commented Nov 21, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

tiffany76 commented Nov 26, 2025

Uh oh!

Uh oh!

tiffany76 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

otelbot bot commented Dec 3, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

adity1raut commented Nov 9, 2025 •

edited by chalin

Loading

chalin left a comment •

edited

Loading