Skip to content

Commit b1bba8e

Browse files
ps48ps48
authored
Feat/add documentation site (#49)
1 parent f92b007 commit b1bba8e

175 files changed

Lines changed: 40102 additions & 0 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/workflows/docs-ci.yml‎

Lines changed: 103 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,103 @@
1+
name: Docs CI
2+
3+
on:
4+
push:
5+
branches: [main]
6+
paths:
7+
- 'docs/**'
8+
pull_request:
9+
branches: [main]
10+
paths:
11+
- 'docs/**'
12+
13+
defaults:
14+
run:
15+
working-directory: ./docs
16+
17+
jobs:
18+
test:
19+
name: Test
20+
runs-on: ubuntu-latest
21+
22+
steps:
23+
- name: Checkout code
24+
uses: actions/checkout@v4
25+
26+
- name: Setup Node.js
27+
uses: actions/setup-node@v4
28+
with:
29+
node-version: '20'
30+
cache: 'npm'
31+
cache-dependency-path: docs/package-lock.json
32+
33+
- name: Install dependencies
34+
run: npm ci
35+
36+
- name: Build site
37+
run: npm run build
38+
39+
- name: Run tests with coverage
40+
run: npm run test:coverage
41+
42+
- name: Upload coverage reports to Codecov
43+
uses: codecov/codecov-action@v5
44+
with:
45+
token: ${{ secrets.CODECOV_TOKEN }}
46+
47+
- name: Upload test results
48+
if: always()
49+
uses: actions/upload-artifact@v4
50+
with:
51+
name: test-results
52+
path: docs/coverage/
53+
54+
build:
55+
name: Build
56+
runs-on: ubuntu-latest
57+
needs: test
58+
59+
steps:
60+
- name: Checkout code
61+
uses: actions/checkout@v4
62+
63+
- name: Setup Node.js
64+
uses: actions/setup-node@v4
65+
with:
66+
node-version: '20'
67+
cache: 'npm'
68+
cache-dependency-path: docs/package-lock.json
69+
70+
- name: Install dependencies
71+
run: npm ci
72+
73+
- name: Build site
74+
run: npm run build
75+
76+
- name: Upload build artifacts
77+
uses: actions/upload-artifact@v4
78+
with:
79+
name: dist
80+
path: docs/dist/
81+
retention-days: 7
82+
83+
lint:
84+
name: Lint
85+
runs-on: ubuntu-latest
86+
87+
steps:
88+
- name: Checkout code
89+
uses: actions/checkout@v4
90+
91+
- name: Setup Node.js
92+
uses: actions/setup-node@v4
93+
with:
94+
node-version: '20'
95+
cache: 'npm'
96+
cache-dependency-path: docs/package-lock.json
97+
98+
- name: Install dependencies
99+
run: npm ci
100+
101+
- name: Check formatting
102+
run: npm run format:check || echo "No format check script found"
103+
continue-on-error: true

‎.github/workflows/docs-deploy.yml‎

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
name: Deploy Docs to GitHub Pages
2+
3+
on:
4+
workflow_run:
5+
workflows: ["Docs CI"]
6+
types:
7+
- completed
8+
branches: [main]
9+
workflow_dispatch:
10+
11+
permissions:
12+
contents: read
13+
pages: write
14+
id-token: write
15+
16+
concurrency:
17+
group: "pages"
18+
cancel-in-progress: false
19+
20+
defaults:
21+
run:
22+
working-directory: ./docs
23+
24+
jobs:
25+
build:
26+
name: Build
27+
runs-on: ubuntu-latest
28+
if: ${{ github.event.workflow_run.conclusion == 'success' || github.event_name == 'workflow_dispatch' }}
29+
30+
steps:
31+
- name: Checkout code
32+
uses: actions/checkout@v4
33+
34+
- name: Setup Node.js
35+
uses: actions/setup-node@v4
36+
with:
37+
node-version: '20'
38+
cache: 'npm'
39+
cache-dependency-path: docs/package-lock.json
40+
41+
- name: Setup Pages
42+
uses: actions/configure-pages@v4
43+
44+
- name: Install dependencies
45+
run: npm ci
46+
47+
- name: Install Starlight dependencies
48+
run: npm ci
49+
working-directory: ./docs/starlight-docs
50+
51+
- name: Build main site
52+
run: npm run build:main
53+
54+
- name: Build Starlight docs
55+
run: npm run build
56+
working-directory: ./docs/starlight-docs
57+
58+
- name: Merge Starlight docs into main dist
59+
run: |
60+
mkdir -p dist/docs
61+
cp -r starlight-docs/dist/* dist/docs/
62+
63+
- name: Upload artifact
64+
uses: actions/upload-pages-artifact@v3
65+
with:
66+
path: ./docs/dist
67+
68+
deploy:
69+
name: Deploy
70+
environment:
71+
name: github-pages
72+
url: ${{ steps.deployment.outputs.page_url }}
73+
runs-on: ubuntu-latest
74+
needs: build
75+
76+
steps:
77+
- name: Deploy to GitHub Pages
78+
id: deployment
79+
uses: actions/deploy-pages@v4

‎.github/workflows/docs-pr-preview.yml‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
name: Docs PR Preview
2+
3+
on:
4+
pull_request:
5+
types: [opened, synchronize, reopened]
6+
paths:
7+
- 'docs/**'
8+
9+
defaults:
10+
run:
11+
working-directory: ./docs
12+
13+
jobs:
14+
preview:
15+
name: Build Preview
16+
runs-on: ubuntu-latest
17+
18+
steps:
19+
- name: Checkout code
20+
uses: actions/checkout@v4
21+
22+
- name: Setup Node.js
23+
uses: actions/setup-node@v4
24+
with:
25+
node-version: '20'
26+
cache: 'npm'
27+
cache-dependency-path: docs/package-lock.json
28+
29+
- name: Install dependencies
30+
run: npm ci
31+
32+
- name: Build site
33+
run: npm run build
34+
35+
- name: Run tests
36+
run: npm test
37+
38+
- name: Comment PR
39+
uses: actions/github-script@v7
40+
with:
41+
script: |
42+
github.rest.issues.createComment({
43+
issue_number: context.issue.number,
44+
owner: context.repo.owner,
45+
repo: context.repo.repo,
46+
body: '✅ Docs preview build completed successfully! All tests passed.'
47+
})

‎docs/.gitignore‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
# build output
2+
dist/
3+
dist-serve/
4+
# generated types
5+
.astro/
6+
7+
# dependencies
8+
node_modules/
9+
starlight-docs/node_modules/
10+
11+
# logs
12+
npm-debug.log*
13+
yarn-debug.log*
14+
yarn-error.log*
15+
pnpm-debug.log*
16+
17+
# test coverage
18+
coverage/
19+
*.lcov
20+
21+
# environment variables
22+
.env
23+
.env.production
24+
25+
# macOS-specific files
26+
.DS_Store
27+
28+
# jetbrains setting folder
29+
.idea/
30+
31+
# claude code
32+
.claude/

‎docs/CLAUDE.md‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
# CLAUDE.md
2+
3+
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4+
5+
## Project Overview
6+
7+
Marketing website and documentation for OpenSearch Observability Stack — an OpenTelemetry-native observability platform. Built with Astro 5, React 19, and Tailwind CSS 4.
8+
9+
## Commands
10+
11+
```bash
12+
npm install # Install dependencies
13+
npm run dev # Dev server at localhost:4321
14+
npm run build # Full production build (main site + Starlight docs)
15+
npm run build:main # Build main site only
16+
npm run build:starlight # Build Starlight docs only (runs npm ci in starlight-docs/)
17+
npm test # Run all tests (vitest --run)
18+
npx vitest --run src/components/Hero.test.ts # Run a single test file
19+
npm run test:watch # Run tests in watch mode
20+
npm run test:coverage # Run tests with v8 coverage
21+
```
22+
23+
## Architecture
24+
25+
### Two-Site Build
26+
27+
The project produces two separate Astro builds merged into one output:
28+
29+
1. **Main marketing site** (`src/`) — Astro + React + Tailwind. Single-page landing at `/opensearch-agentops-website/`. Configured in root `astro.config.mjs`.
30+
2. **Documentation site** (`starlight-docs/`) — Astro Starlight. Served at `/opensearch-agentops-website/docs/`. Has its own `package.json` and `astro.config.mjs`. The `build` script runs both and copies Starlight output into `dist/docs/`.
31+
32+
Both sites use `base: '/opensearch-agentops-website'` (or `/opensearch-agentops-website/docs`) for GitHub Pages deployment. All internal links must respect this base path.
33+
34+
### Component Patterns
35+
36+
- **Astro components** (`.astro`) handle static markup and layout (Hero, Features, Navigation, Footer, etc.)
37+
- **React components** (`.tsx`) handle interactive/client-side behavior (CyclingTagline, IntegrationPathsTabs, DeveloperTestimonials)
38+
- Components and their tests live side-by-side in `src/components/`
39+
40+
### Testing
41+
42+
- **Framework**: Vitest with happy-dom environment
43+
- **Setup**: `vitest.setup.ts` imports `@testing-library/jest-dom/vitest`
44+
- **Test location**: Co-located with source files (e.g., `Hero.astro` → `Hero.test.ts`, `Hero.unit.test.ts`)
45+
- **React component tests**: Use `@testing-library/react` (`.test.tsx` files)
46+
- **Astro component tests**: Test HTML output as strings (`.test.ts` / `.unit.test.ts` files)
47+
- **Coverage**: Includes only `src/**/*.{ts,tsx}`, excludes `.astro` files
48+
49+
### Starlight Docs
50+
51+
Documentation content lives in `starlight-docs/src/content/docs/` organized by section directories (get-started, send-data, investigate, apm, dashboards, alerts, etc.). Pages are Markdown/MDX with required frontmatter (`title`, `description`). Sidebar is auto-generated from directory structure via `starlight-docs/astro.config.mjs`.
52+
53+
To dev the docs site independently:
54+
```bash
55+
cd starlight-docs && npm install && npm run dev
56+
```

0 commit comments

Comments
 (0)