diff --git a/.agents/skills/new-page-scaffold.md b/.agents/skills/new-page-scaffold.md new file mode 100644 index 000000000000..22bf262355b5 --- /dev/null +++ b/.agents/skills/new-page-scaffold.md @@ -0,0 +1,29 @@ +# Skill: `new-page-scaffold` + +Scaffold a new documentation page with correct frontmatter and directory +structure for `opentelemetry.io`. + +## Parameters + +- `title`: The title of the page. +- `description`: A brief description for SEO and site search. +- `path`: The target path relative to `content/en/docs/`. + +## Steps + +1. **Validate path**: Ensure the target directory exists under + `content/en/docs/`. +2. **Determine filename**: Use kebab-case for the filename. If it's a section + landing page, use `_index.md`. +3. **Generate frontmatter**: + ```yaml + --- + title: + description: <description> + weight: <calculated-weight> + --- + ``` +4. **Calculate weight**: Check existing files in the directory to determine the + next logical `weight` (increment by 10 or 5). +5. **Create file**: Write the scaffolding to the calculated path. +6. **Verify**: Run `npm run check:markdown` on the new file. diff --git a/.agents/skills/review-content.md b/.agents/skills/review-content.md new file mode 100644 index 000000000000..da738908d156 --- /dev/null +++ b/.agents/skills/review-content.md @@ -0,0 +1,32 @@ +# Skill: `review-content` + +Review `opentelemetry.io` documentation content for compliance with the OTel +style guide and markdown standards. + +## Parameters + +- `path`: The path to the markdown file to review. + +## Steps + +1. **Format and lint check**: + - Run `npm run check:markdown -- <path>` to verify basic markdown + formatting. + - Run `npm run check:text -- <path>` for terminology and textlint rules. +2. **Style guide alignment**: + - **Alerts**: Verify alert types use the standard `> [!NOTE]`, `> [!TIP]`, + `> [!IMPORTANT]`, `> [!WARNING]`, or `> [!CAUTION]` syntax. + - **Headings**: Ensure each page has exactly one `H1` and that heading + levels follow a logical hierarchy. + - **Heading IDs**: Check if headings have explicit IDs (e.g., + `## Heading {#id}`) as required by the site's Hugo configuration. + - **Inclusive language**: Ensure the content follows inclusive language + principles (e.g., avoiding "master/slave", "whitelist/blacklist"). +3. **Frontmatter validation**: + - Verify mandatory fields: `title`, `description`. + - Check for appropriate `weight` if the page is part of a sequence. +4. **Links and images**: + - Run `npm run check:links -- <path>` to verify all links are valid. + - For images, ensure they have descriptive alt text. +5. **Summarize results**: Provide a clear list of violations and suggested + fixes. diff --git a/.agents/skills/setup-localization.md b/.agents/skills/setup-localization.md new file mode 100644 index 000000000000..6484622d292d --- /dev/null +++ b/.agents/skills/setup-localization.md @@ -0,0 +1,39 @@ +# Skill: `setup-localization` + +Automate the "New localizations" onboarding process for `opentelemetry.io`. + +## Parameters + +- `language_name`: The name of the language (e.g., "Hindi"). +- `language_code`: ISO 639-1 language code (e.g., "hi"). +- `mentor_handle`: GitHub handle of the localization mentor. +- `contributor_handles`: List of GitHub handles for initial contributors. + +## Steps + +1. **Prepare Hugo config**: + - Update `config/_default/hugo.yaml`: Add the new language to the + `languages` block. + - Update `config/_default/module-template.yaml`: Add a content mount for the + new language. +2. **Setup spelling support**: + - Check for an available `@cspell/dict-<language_code>` NPM package. + - If available, install as a dev dependency + (`npm install --save-dev @cspell/dict-<language_code>`). + - Create `.cspell/<language_code>-words.txt` for site-local words. + - Update `.cspell.yml` to import the new dictionary and define the local + word file. +3. **Localize homepage**: + - Create `content/<language_code>/_index.md`. + - Scaffold the file with basic frontmatter including `title` and + `description` in the target language. +4. **Draft initial localization issue**: + - Use the template from `content/en/docs/contributing/localization.md` + section "Localization kickoff". + - Populate fields: Language info, Locale team info, and OTel maintainer + checklist. +5. **Verify**: + - Build the site locally (`npm run build`) to ensure Hugo configuration is + valid. + - Run `npm run check:i18n -- content/<language_code>` to check + synchronization status. diff --git a/content/en/docs/collector/_index.md b/content/en/docs/collector/_index.md index f2f5ba0b3a88..a4b41bbbeb8e 100644 --- a/content/en/docs/collector/_index.md +++ b/content/en/docs/collector/_index.md @@ -8,8 +8,6 @@ cascade: weight: 270 --- -![OpenTelemetry Collector diagram with Jaeger, OTLP and Prometheus integration](img/otel-collector.svg) - ## Introduction The OpenTelemetry Collector offers a vendor-agnostic implementation of how to @@ -18,6 +16,27 @@ and maintain multiple agents/collectors. This works with improved scalability and supports open source observability data formats (e.g. Jaeger, Prometheus, Fluent Bit, etc.) sending to one or more open source or commercial backends. +```mermaid +flowchart TD + subgraph Option1 ["Option 1: Direct Export (Dev/Simple)"] + direction LR + App1(["Application"]) --> B1[("Backend(s)")] + end + + subgraph Option2 ["Option 2: Via Collector (Production)"] + direction LR + App2(["Application"]) --> Rec["Receivers"] + + subgraph Collector ["OpenTelemetry Collector"] + direction LR + Rec --> Proc["Processors"] + Proc --> Exp["Exporters"] + end + + Exp --> B2[("Backend(s)")] + end +``` + ## Objectives - _Usability_: Reasonable default configuration, supports popular protocols,