Skip to content

[FEATURE] Set up GitHub Pages for Observability Stack documentation #22

@anirudha

Description

@anirudha

Is your feature request related to a problem?

As the project matures, there is no documentation site for users and contributors to reference. We need a proper GitHub Pages site to publish component docs, user guides, and version mapping — kept current with each code release.

What solution would you like?

Enable GitHub Pages for the repo with a static site generator (e.g. MkDocs with Material theme or Jekyll). The site should include:

  • Getting Started: Installation, quickstart, prerequisites
  • Components: OpenSearch, Data Prepper, OTel Collector, Prometheus, OpenSearch Dashboards — what each does and how it's configured in the stack
  • User Guide: Configuration options, enabling examples, enabling OTel Demo, custom instrumentation, Helm deployment
  • Architecture: Stack topology, data flow, networking
  • Version Mapping: Table mapping each Observability Stack release version to the specific component versions (OpenSearch, Data Prepper, OTel Collector, Prometheus, etc.). The stack version is independent of individual component versions.
  • Contributing: Link back to CONTRIBUTING.md

Example version mapping table:

Stack Version OpenSearch Data Prepper OTel Collector Prometheus Dashboards
1.0.0 2.x.x 2.x.x 0.x.x 2.x.x 2.x.x

Implementation:

  • Source docs from a docs/ directory in the repo
  • GitHub Actions workflow to build and deploy on push to main or on release tags
  • Support versioned documentation tied to stack releases

What alternatives have you considered?

  • Keeping docs only in-repo as markdown files (doesn't scale, not user-friendly)
  • External hosted docs (adds operational overhead outside the project)

Do you have any additional context?

Acceptance criteria:

  • GitHub Pages site is live and accessible
  • Docs cover all sections listed above
  • Version mapping table is present and accurate for the current release
  • CI workflow auto-deploys docs on merge to main
  • Docs are reviewable via PR (source lives in repo)

Metadata

Metadata

Assignees

Labels

enhancementNew feature or request

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions