diff --git a/.github/workflows/afdocs-checks.yml b/.github/workflows/afdocs-checks.yml index 6af091a1..2b87a462 100644 --- a/.github/workflows/afdocs-checks.yml +++ b/.github/workflows/afdocs-checks.yml @@ -51,42 +51,3 @@ jobs: echo "**Deploy URL:** ${{ steps.wait-for-netlify.outputs.url }}" >> $GITHUB_STEP_SUMMARY echo "" >> $GITHUB_STEP_SUMMARY echo "Run locally: \`DEPLOY_URL=${{ steps.wait-for-netlify.outputs.url }} npm run afdocs:verbose\`" >> $GITHUB_STEP_SUMMARY - - redirect-tests: - name: Redirect Tests - runs-on: ubuntu-latest - steps: - - name: Checkout - uses: actions/checkout@v4 - - - name: Setup Node.js - uses: actions/setup-node@v4 - with: - node-version: '24' - cache: 'npm' - - - name: Install dependencies - run: npm ci - - - name: Wait for Netlify Deploy - uses: jakepartusch/wait-for-netlify-action@v1.4 - id: wait-for-netlify - with: - site_name: redpanda-documentation - max_timeout: 600 - - - name: Run redirect tests - env: - DEPLOY_URL: ${{ steps.wait-for-netlify.outputs.url }} - run: npm run test:redirects:verbose - - - name: Post results summary - if: always() - run: | - echo "## Redirect Tests" >> $GITHUB_STEP_SUMMARY - echo "" >> $GITHUB_STEP_SUMMARY - echo "**Deploy URL:** ${{ steps.wait-for-netlify.outputs.url }}" >> $GITHUB_STEP_SUMMARY - echo "" >> $GITHUB_STEP_SUMMARY - echo "Validates redirect rules in netlify.toml" >> $GITHUB_STEP_SUMMARY - echo "" >> $GITHUB_STEP_SUMMARY - echo "Run locally: \`DEPLOY_URL=${{ steps.wait-for-netlify.outputs.url }} npm run test:redirects:verbose\`" >> $GITHUB_STEP_SUMMARY diff --git a/REDIRECT_TESTING.md b/REDIRECT_TESTING.md deleted file mode 100644 index d5cfdb43..00000000 --- a/REDIRECT_TESTING.md +++ /dev/null @@ -1,196 +0,0 @@ -# Redirect Testing Documentation - -## Overview - -This document describes the automated redirect testing infrastructure added to validate the redirect rules in `netlify.toml`. - -## Background - -Following a comprehensive review of the redirect-rules PR (which added 218 lines of redirects to fix 404s from component restructuring), automated testing was identified as a critical gap. While manual testing caught the redirect ordering issue, automated tests prevent future regressions and validate redirect behavior in CI. - -## Review Findings Summary - -### Already Fixed - -1. **Critical Ordering Issue** - Versioned wildcards (`/24.1/*`) are correctly placed AFTER cloud-specific rules (lines 726-759 come after 672-720), ensuring cloud paths like `/24.1/get-started/quick-start-cloud/` redirect to cloud-data-platform, not streaming. - -2. **Two-Hop Redirects** - Explicit single-hop rules for cluster-balancing and fips-compliance already exist at lines 374-382, preventing redirect chains. - -3. **Force Flag** - Verified that Antora does not generate files at redirect source paths, so `force = true` is not needed. - -### Implemented - -4. **Automated Testing** - Comprehensive test suite covering all 7 redirect categories with 50+ test cases. - -## Test Suite - -### Location -- `tests/redirects.test.ts` - Main test suite -- Runs via vitest (already in devDependencies) - -### Test Categories - -The test suite validates 7 categories of redirects: - -1. **Versioned Path Wildcards** (7 tests) - - Verifies `/25.3/*`, `/24.1/*`, etc. redirect to `/streaming/{version}/:splat` - - Example: `/25.3/get-started/architecture/` → `/streaming/25.3/get-started/architecture/` - -2. **Cloud-Specific Override Rules** (6 tests) - - **Critical**: Ensures cloud paths are NOT caught by versioned wildcards - - Example: `/24.1/get-started/quick-start-cloud/` → `/cloud-data-platform/...` (NOT `/streaming/24.1/...`) - -3. **Two-Hop Prevention** (2 tests) - - Verifies cluster-balancing and fips-compliance use single-hop redirects - - Ensures redirect count = 1 (not 2) - -4. **Connect Component Restructure** (6 tests) - - Verifies `/connect/inputs/*` → `/connect/components/inputs/*` - - Covers inputs, outputs, processors, caches, buffers, about page - -5. **Cloud-Data-Platform Path Fixes** (7 tests) - - RPK path corrections: `/cloud-data-platform/rpk/*` → `/cloud-data-platform/reference/rpk/*` - - Connect path drops: `/cloud-data-platform/connect/*` → `/connect/*` - -6. **Streaming Version-less Paths** (6 tests) - - Verifies `/streaming/reference/*` → `/streaming/current/reference/*` - - Covers reference, deploy, develop, manage, upgrade, get-started - -7. **Streaming Current Restructured Paths** (4 tests) - - Licensing → get-started/licensing - - Kubernetes → deploy/.../kubernetes - - Cluster-balancing → cluster-maintenance/... - - FIPS → security/... - -### Test Assertions - -Each test verifies: -1. Final status code is 200 -2. Final URL matches expected destination -3. Redirect chain is single-hop (≤2 including Netlify internal redirects) -4. Response time < 2 seconds - -### Running Tests - -```bash -# Local testing against deploy preview -DEPLOY_URL= npm run test:redirects - -# Verbose output -DEPLOY_URL= npm run test:redirects:verbose - -# Production testing (default) -npm run test:redirects -``` - -## CI Integration - -### Workflow: `.github/workflows/afdocs-checks.yml` - -The redirect tests run as a separate job for clear visibility in PR checks: - -**Two separate jobs:** -1. **Agent-Friendly Docs** - validates agent-friendly documentation standards -2. **Redirect Tests** - validates redirect rules in netlify.toml - -**Trigger**: On pull request (opened, synchronize, reopened) when relevant files change: -- netlify.toml (redirect rules) -- .adoc or .md files (documentation content) -- antora-playbook.yml files (build configuration) -- workflow file itself - -**Each job:** -1. Waits for Netlify deploy preview -2. Runs its test suite -3. Posts results to GitHub Actions summary -4. Fails the check if tests fail (no `continue-on-error`) - -**Benefits:** -- Redirect tests show as a separate PR check (clear visibility) -- Failures are immediately obvious in PR status -- Each test suite can be run/debugged independently - -### Example CI Output - -```markdown -## Documentation Checks Results - -**Deploy URL:** https://deploy-preview-123--redpanda-documentation.netlify.app - -### Agent-Friendly Docs Checks -PASS: All afdocs checks passed! - -### Redirect Tests -PASS: All redirect tests passed! - -**All documentation checks passed!** -``` - -## Redirect Rules Reference - -### Key Sections in netlify.toml - -- **Lines 355-397**: Streaming paths without version (with two-hop prevention) -- **Lines 399-435**: Version root redirects -- **Lines 469-490**: Streaming current restructured paths -- **Lines 575-644**: Cloud-data-platform path fixes -- **Lines 672-720**: Cloud-specific redirects (MUST come before versioned wildcards) -- **Lines 722-759**: Versioned path wildcards (MUST come after cloud-specific rules) -- **Lines 786-838**: Connect component restructure - -### Critical Ordering - -Netlify processes redirects top-to-bottom with first-match-wins behavior. The order MUST be: - -1. Specific rules (e.g., `/24.1/get-started/quick-start-cloud/`) -2. Wildcard rules (e.g., `/24.1/*`) - -This ensures specific paths don't get caught by broader wildcards. - -## Trailing Slash Convention - -**Current Pattern** (intentional): -- `from` paths: Usually NO trailing slash -- `to` paths: Usually WITH trailing slash - -**Rationale**: Netlify treats `/path` and `/path/` as different URLs. The current pattern matches how URLs appear in the wild (e.g., from external links, search engines) and ensures consistent destination URLs. - -**No action needed** unless Slack #docs-redpanda-404 reports suggest otherwise. - -## Maintenance - -### Adding New Redirects - -When adding new redirects to `netlify.toml`: - -1. **Check ordering**: Ensure specific rules come before wildcards -2. **Add test case**: Update `tests/redirects.test.ts` with test for new redirect -3. **Run tests**: Verify locally against deploy preview -4. **Monitor**: Watch #docs-redpanda-404 after merge - -### Test Failures - -If redirect tests fail in CI: - -1. Check deploy preview URL (shown in GitHub Actions summary) -2. Manually test failing URLs in browser -3. Check browser network tab for redirect chain -4. Verify redirect rule order in `netlify.toml` -5. Run locally: `DEPLOY_URL= npm run test:redirects:verbose` - -## Future Enhancements - -Potential improvements: - -1. **Response time monitoring**: Track redirect performance over time -2. **Dead link detection**: Crawl site for broken internal links -3. **Redirect chain analysis**: Identify multi-hop redirects automatically -4. **404 monitoring**: Automated Slack #docs-redpanda-404 analysis -5. **Trailing slash audit**: Automated consistency checking - -## References - -- Original PR review: Comprehensive docs standards review identifying ordering issue -- Netlify redirect docs: https://docs.netlify.com/routing/redirects/ -- Antora playbook: `antora-playbook.yml` -- CI workflow: `.github/workflows/afdocs-checks.yml` diff --git a/antora-playbook.yml b/antora-playbook.yml index c9347cec..ff1a85fe 100644 --- a/antora-playbook.yml +++ b/antora-playbook.yml @@ -81,6 +81,8 @@ content: branches: main - url: https://github.com/redpanda-data/rp-connect-docs branches: main + - url: https://github.com/redpanda-data/adp-docs + branches: main ui: bundle: url: https://github.com/redpanda-data/docs-ui/releases/latest/download/ui-bundle.zip diff --git a/data-platform/modules/ROOT/nav.adoc b/data-platform/modules/ROOT/nav.adoc index 177e6b0f..27f6f899 100644 --- a/data-platform/modules/ROOT/nav.adoc +++ b/data-platform/modules/ROOT/nav.adoc @@ -1,2 +1 @@ * xref:index.adoc[Overview] -* xref:how-to-use-these-docs.adoc[How to Use These Docs] diff --git a/data-platform/modules/ROOT/pages/index.adoc b/data-platform/modules/ROOT/pages/index.adoc index c2dbedff..22d05257 100644 --- a/data-platform/modules/ROOT/pages/index.adoc +++ b/data-platform/modules/ROOT/pages/index.adoc @@ -11,10 +11,6 @@ :page-hero-stat2-text: connectors // === ASK AI SECTION === :hero-ask-placeholder: Ask AI about Redpanda... -:hero-suggestions-label: Try asking: -:hero-suggestion-1: How do I write from Redpanda Streaming to Snowflake? -:hero-suggestion-2: What's the difference between Redpanda and Kafka? -:hero-suggestion-3: How do I create a CDC pipeline from Postgres to Redpanda Cloud? // === CHOOSE SECTION (heading) === :page-choose-heading: Choose how you'll run Redpanda :page-choose-subtitle: Self-Managed or Cloud: same Kafka-compatible engine, different operations model. Both include Redpanda Connect for building data pipelines. diff --git a/home/antora.yml b/home/antora.yml index a8f7e7ec..996db49e 100644 --- a/home/antora.yml +++ b/home/antora.yml @@ -57,3 +57,8 @@ asciidoc: description: 'Integrate data across systems with hundreds of prebuilt connectors, including AI and change data capture (CDC).' urls: - url: 'connect:get-started:quickstarts/rpk.adoc' + - title: 'Agentic Data Plane' + image: adp.svg + description: 'Build, deploy, and govern AI agents at scale with enterprise governance, cost controls, and compliance-grade audit trails.' + urls: + - url: 'agentic-data-plane:home:index.adoc' diff --git a/home/modules/ROOT/images/adp.svg b/home/modules/ROOT/images/adp.svg new file mode 100644 index 00000000..74e66cdb --- /dev/null +++ b/home/modules/ROOT/images/adp.svg @@ -0,0 +1,5 @@ + + + + + diff --git a/home/modules/ROOT/nav.adoc b/home/modules/ROOT/nav.adoc index c37b6d9a..9bc6e792 100644 --- a/home/modules/ROOT/nav.adoc +++ b/home/modules/ROOT/nav.adoc @@ -1,2 +1,2 @@ * xref:index.adoc[Overview] -* xref:data-platform:ROOT:how-to-use-these-docs.adoc[How to Use These Docs] +* xref:ROOT:how-to-use-these-docs.adoc[How to Use These Docs] diff --git a/data-platform/modules/ROOT/pages/how-to-use-these-docs.adoc b/home/modules/ROOT/pages/how-to-use-these-docs.adoc similarity index 90% rename from data-platform/modules/ROOT/pages/how-to-use-these-docs.adoc rename to home/modules/ROOT/pages/how-to-use-these-docs.adoc index efaf1330..95def7c6 100644 --- a/data-platform/modules/ROOT/pages/how-to-use-these-docs.adoc +++ b/home/modules/ROOT/pages/how-to-use-these-docs.adoc @@ -1,41 +1,41 @@ = How to Use These Docs :description: Navigate Redpanda's documentation structure and leverage AI-powered features including MCP server integration, markdown exports, and interactive documentation tools. -:page-aliases: mcp-setup.adoc, home:ROOT:mcp-setup.adoc +:page-aliases: home:ROOT:mcp-setup.adoc, data-platform:ROOT:how-to-use-these-docs.adoc Redpanda's documentation helps you stream data, build pipelines, and deploy AI agents whether you manage infrastructure yourself or run in the cloud. This page explains how our docs are organized, clarifies the relationship between deployment models and products, and shows you how to access documentation through AI-powered tools and programmatic interfaces. == Understand the documentation structure -Redpanda's documentation is organized around the Data Platform, the streaming foundation for everything you build. You can deploy the Data Platform in two ways: as a fully managed Cloud service or as a Self-Managed installation where you control the infrastructure. Regardless of deployment model, you have access to multiple products including Streaming (the broker and Redpanda CLI) and Connect (data pipelines). +Redpanda's documentation is organized around multiple deployment models and products. The Data Platform provides the streaming foundation with Cloud or Self-Managed deployment options. The Agentic Data Plane (ADP) offers a specialized infrastructure for AI agents and agentic workflows. .Documentation hierarchy ---- Redpanda Documentation -└── Data Platform - ├── Cloud (managed by Redpanda) - │ ├── Serverless - │ ├── BYOC - │ └── Dedicated - └── Self-Managed (managed by you) - ├── Streaming (broker, Redpanda CLI) - └── Connect (data pipelines) +├── Data Platform +│ ├── Cloud (managed by Redpanda) +│ │ ├── Serverless +│ │ ├── BYOC +│ │ └── Dedicated +│ └── Self-Managed (managed by you) +│ ├── Streaming (broker, Redpanda CLI) +│ └── Connect (data pipelines) +└── Agentic Data Plane (ADP) + └── AI agent infrastructure and workflows ---- [NOTE] ==== *What changed:* Previously, the software that deployed a Redpanda broker was called "Redpanda Self-Managed". In the new structure, "Self-Managed" refers to the deployment model (you manage the infrastructure), while "Streaming" is the product name for the broker itself. - -* *Old:* "Redpanda Self-Managed" is the broker product -* *New:* "Self-Managed" is deployment model that includes Streaming and Connect products ==== *Key components:* * xref:index.adoc[Data Platform overview]: The streaming foundation -* xref:self-managed:ROOT:index.adoc[Self-Managed documentation]: Deploy and manage yourself -** xref:streaming:home:index.adoc[Streaming documentation]: Broker and Redpanda CLI -** xref:connect:home:index.adoc[Connect documentation]: Data pipelines and integration -* xref:cloud-data-platform:home:index.adoc[Cloud documentation]: Fully managed services +** xref:self-managed:ROOT:index.adoc[Self-Managed documentation]: Deploy and manage yourself +*** xref:streaming:home:index.adoc[Streaming documentation]: Broker and Redpanda CLI +*** xref:connect:home:index.adoc[Connect documentation]: Data pipelines and integration +** xref:cloud-data-platform:home:index.adoc[Cloud documentation]: Fully managed services +* xref:agentic-data-plane:home:index.adoc[Agentic Data Plane (ADP)]: AI agent infrastructure == Choose your path @@ -58,6 +58,11 @@ Find the documentation that matches your use case: * Hundreds of prebuilt connectors including AI and change data capture (CDC) * xref:connect:home:index.adoc[Connect documentation] +*I want to build AI agent infrastructure* → ADP docs + +* Specialized platform for agentic workflows and AI agent orchestration +* xref:agentic-data-plane:home:index.adoc[Get started with ADP] + == AI agent access Redpanda's documentation is optimized for AI agents and LLM consumption. Whether you're building AI agents, IDE plugins, or automation tools, you can access documentation through interactive page features, a Model Context Protocol (MCP) server for real-time queries, and static markdown exports for offline processing. diff --git a/home/modules/ROOT/pages/llms.adoc b/home/modules/ROOT/pages/llms.adoc index 4aceeacf..905c4bc5 100644 --- a/home/modules/ROOT/pages/llms.adoc +++ b/home/modules/ROOT/pages/llms.adoc @@ -14,7 +14,7 @@ 2. **Sitemap**: `{site-url}/sitemap.md` - Contains all documentation pages including this file and all exports. The sitemap index includes `{site-url}/sitemap-llms.md` with all AI-optimized exports. -3. **MCP server**: {site-url}/cloud-data-platform/ai-agents/mcp.md - For Claude Code and MCP-compatible agents, this provides interactive documentation tools. +3. **MCP server**: {site-url}/home/how-to-use-these-docs.md - For Claude Code and MCP-compatible agents, this provides interactive documentation tools. ### Static documentation exports @@ -49,7 +49,7 @@ Redpanda docs serve both new and experienced users, offering detailed technical - **{site-url}/streaming.md[Redpanda Streaming]:** Deploy and manage Redpanda in your environment for ultimate control, high performance, and fault tolerance with Kafka compatibility and advanced enterprise features like Tiered Storage. - **{site-url}/cloud-data-platform.md[Redpanda Cloud]:** Simplify streaming with a fully-managed service: Serverless, Bring Your Own Cloud (BYOC), or Dedicated. Serverless is the fastest and easiest way to start data streaming. Choose BYOC for full data sovereignty. - **{site-url}/connect.md[Redpanda Connect]:** Effortlessly integrate data across systems with hundreds of prebuilt connectors, change data capture (CDC) capabilities, and YAML-configurable workflows. Available as a standalone solution or as part of Redpanda Streaming, Redpanda Connect empowers organizations to build scalable, high-performance data pipelines with minimal complexity. -- **{site-url}/cloud-data-platform/ai-agents.md[Redpanda Agentic Data Plane]:** Enterprise-grade infrastructure for building, deploying, and governing AI agents at scale. Provides Model Context Protocol (MCP) integration, declarative agent configuration, and compliance-grade audit trails for AI agents that need direct access to databases, queues, and business systems. +- **{site-url}/agentic-data-plane/get-started/adp-overview.md[Redpanda Agentic Data Plane]:** Enterprise-grade infrastructure for building, deploying, and governing AI agents at scale. Provides Model Context Protocol (MCP) integration, declarative agent configuration, and compliance-grade audit trails for AI agents that need direct access to databases, queues, and business systems. - **{site-url}/streaming/current/console.md[Redpanda Console]:** Streamline operations with an intuitive Kafka UI for managing topics, partitions, and consumer groups, providing visibility and control over your data pipeline. ## Core documentation @@ -79,11 +79,18 @@ Learn about `rpk`, the comprehensive command-line interface tool for managing Re Build and deploy production-ready AI agents with enterprise governance and compliance. -- {site-url}/cloud-data-platform/ai-agents/adp-overview.md[Agentic Data Plane Overview]: Enterprise infrastructure for AI agents with built-in governance, observability, and compliance. -- {site-url}/cloud-data-platform/ai-agents/mcp.md[Model Context Protocol (MCP)]: Give AI agents direct access to databases, queues, CRMs, and business systems without custom integration code. -- {site-url}/cloud-data-platform/ai-agents/ai-gateway.md[AI Gateway]: Centralized gateway for AI agent interactions with intelligent routing, caching, and cost controls. -- {site-url}/cloud-data-platform/ai-agents.md[Building AI Agents]: Declarative agent configuration using Redpanda Connect connectors - no custom agent code required. -- {site-url}/cloud-data-platform/ai-agents/observability.md[Agent Observability]: Track agent decisions, costs, and compliance with comprehensive audit trails. +- {site-url}/agentic-data-plane/get-started/adp-overview.md[Agentic Data Plane Overview]: Enterprise infrastructure for AI agents with built-in governance, observability, and compliance. +- {site-url}/agentic-data-plane/connect/mcp-overview.md[Model Context Protocol (MCP)]: Give AI agents direct access to databases, queues, CRMs, and business systems without custom integration code. +- {site-url}/agentic-data-plane/gateway/overview.md[AI Gateway]: Centralized gateway for AI agent interactions with intelligent routing, caching, and cost controls. +- {site-url}/agentic-data-plane/connect/agents-overview.md[Building AI Agents]: Declarative agent configuration using Redpanda Connect connectors - no custom agent code required. +- {site-url}/agentic-data-plane/monitor.md[Agent Observability]: Track agent decisions, costs, and compliance with comprehensive audit trails. + +## API references + +- {site-url}/api/doc/admin.md[Admin API]: Manage and monitor Redpanda clusters using this REST API, including operations for configuration, partitions, and node health. +- {site-url}/api/doc/schema-registry.md[Schema Registry API]: Use Redpanda's Kafka-compatible schema registry for managing and evolving schemas in your data streams. +- {site-url}/api/doc/http-proxy.md[HTTP Proxy API]: Simplify interactions with Kafka topics and partitions with Redpanda's HTTP Proxy API, enabling easier data production and consumption over HTTP. +- {site-url}/api/doc/cloud-controlplane.md[Cloud API]: Access and manage Redpanda Cloud resources programmatically, including provisioning clusters, monitoring usage, and configuring deployments. ## Troubleshooting diff --git a/local-antora-playbook.yml b/local-antora-playbook.yml index 3750d5b2..b92b42a6 100644 --- a/local-antora-playbook.yml +++ b/local-antora-playbook.yml @@ -18,25 +18,17 @@ content: - url: . branches: HEAD start_paths: [home, data-platform, self-managed] - - url: https://github.com/redpanda-data/docs branches: [main, v/*, shared, 'site-search', '!v-end-of-life/*'] - - url: https://github.com/redpanda-data/redpanda-labs branches: main start_paths: [docs,'*/docs'] - - # cloud-docs - WIP feature branch - url: https://github.com/redpanda-data/cloud-docs branches: main - - # rp-connect-docs - WIP feature branch - url: https://github.com/redpanda-data/rp-connect-docs branches: main - - # adp-docs - WIP feature branch - #- url: https://github.com/redpanda-data/adp-docs - #branches: feature/platform-badges + - url: https://github.com/redpanda-data/adp-docs + branches: main ui: bundle: url: https://github.com/redpanda-data/docs-ui/releases/latest/download/ui-bundle.zip diff --git a/netlify.toml b/netlify.toml index 42bac750..528501aa 100644 --- a/netlify.toml +++ b/netlify.toml @@ -13,7 +13,7 @@ NODE_OPTIONS = "--max-old-space-size=6144" fail_deploy_on_score_thresholds = "true" [[plugins.inputs.audits]] - path = "streaming/current/home/index.html" + path = "home/index.html" [plugins.inputs.settings] preset = "desktop" @@ -663,6 +663,22 @@ from = "/cloud-data-platform/reference/rpk-acl/*" to = "/cloud-data-platform/reference/rpk/rpk-acl/:splat" status = 301 +# =========Streaming path fixes======== +# Fix high-volume 404s from stale links after the docs restructure. +# :version matches a single path segment (for example, current, 25.3, 24.3). + +# rpk reference pages live under /reference/rpk/ (mirrors the cloud-data-platform fix above) +[[redirects]] +from = "/streaming/:version/rpk/*" +to = "/streaming/:version/reference/rpk/:splat" +status = 301 + +# Data transforms pages live under /develop/data-transforms/ +[[redirects]] +from = "/streaming/:version/data-transforms/*" +to = "/streaming/:version/develop/data-transforms/:splat" +status = 301 + # Connect content under cloud-data-platform should go to connect [[redirects]] from = "/cloud-data-platform/develop/connect/*" diff --git a/package.json b/package.json index ffbb3b93..7fbe626f 100644 --- a/package.json +++ b/package.json @@ -9,9 +9,7 @@ "serve": "wds --node-resolve --open / --watch --root-dir docs", "afdocs": "vitest run agent-docs.test.ts", "afdocs:verbose": "vitest run agent-docs.test.ts --reporter=verbose", - "afdocs:cli": "afdocs check \"${DEPLOY_URL:-https://docs.redpanda.com}\" -v", - "test:redirects": "vitest run tests/redirects.test.ts", - "test:redirects:verbose": "vitest run tests/redirects.test.ts --reporter=verbose" + "afdocs:cli": "afdocs check \"${DEPLOY_URL:-https://docs.redpanda.com}\" -v" }, "dependencies": { "@antora/cli": "^3.1.14", diff --git a/preview-antora-playbook.yml b/preview-antora-playbook.yml index 304e856b..7a0519aa 100644 --- a/preview-antora-playbook.yml +++ b/preview-antora-playbook.yml @@ -31,6 +31,8 @@ content: branches: main - url: https://github.com/redpanda-data/rp-connect-docs branches: main + - url: https://github.com/redpanda-data/adp-docs + branches: main ui: bundle: url: https://github.com/redpanda-data/docs-ui/releases/latest/download/ui-bundle.zip diff --git a/tests/redirects.test.ts b/tests/redirects.test.ts deleted file mode 100644 index f7e359f6..00000000 --- a/tests/redirects.test.ts +++ /dev/null @@ -1,345 +0,0 @@ -import { describe, it, expect, beforeAll } from 'vitest'; - -/** - * Redirect Test Suite - * - * Tests the redirect rules defined in netlify.toml to ensure: - * 1. Redirects resolve to 200 status - * 2. Final URLs match expected destinations - * 3. Redirect chains are single-hop (no multi-hop redirects) - * 4. Cloud-specific rules override versioned wildcards - */ - -const BASE_URL = process.env.DEPLOY_URL || 'https://docs.redpanda.com'; -const MAX_REDIRECT_TIME = 2000; // 2 seconds - -interface RedirectTest { - from: string; - to: string; - description: string; -} - -interface RedirectResult { - finalUrl: string; - redirectCount: number; - statusCode: number; - responseTime: number; -} - -async function testRedirect(path: string): Promise { - const startTime = Date.now(); - let redirectCount = 0; - - const response = await fetch(`${BASE_URL}${path}`, { - redirect: 'manual', - }); - - let currentResponse = response; - let currentUrl = `${BASE_URL}${path}`; - - // Follow redirects manually to count them - while (currentResponse.status >= 300 && currentResponse.status < 400) { - redirectCount++; - const location = currentResponse.headers.get('location'); - if (!location) break; - - // Handle both absolute and relative URLs - currentUrl = location.startsWith('http') ? location : `${BASE_URL}${location}`; - currentResponse = await fetch(currentUrl, { redirect: 'manual' }); - } - - const responseTime = Date.now() - startTime; - - return { - finalUrl: currentUrl, - redirectCount, - statusCode: currentResponse.status, - responseTime, - }; -} - -describe('Redirect Rules', () => { - describe('1. Versioned Path Wildcards', () => { - const tests: RedirectTest[] = [ - { - from: '/25.3/home/', - to: '/streaming/25.3/home/', - description: 'Version 25.3 wildcard redirect' - }, - { - from: '/25.2/get-started/', - to: '/streaming/25.2/get-started/', - description: 'Version 25.2 wildcard redirect' - }, - { - from: '/25.1/manage/security/', - to: '/streaming/25.1/manage/security/', - description: 'Version 25.1 wildcard redirect' - }, - { - from: '/24.3/reference/', - to: '/streaming/24.3/reference/', - description: 'Version 24.3 wildcard redirect' - }, - { - from: '/24.2/deploy/', - to: '/streaming/24.2/deploy/', - description: 'Version 24.2 wildcard redirect' - }, - { - from: '/24.1/develop/', - to: '/streaming/24.1/develop/', - description: 'Version 24.1 wildcard redirect (not cloud path)' - }, - { - from: '/23.3/reference/', - to: '/streaming/23.3/reference/', - description: 'Version 23.3 wildcard redirect (not cloud path)' - }, - ]; - - tests.forEach(({ from, to, description }) => { - it(description, async () => { - const result = await testRedirect(from); - - expect(result.statusCode, `Expected 200 but got ${result.statusCode}`).toBe(200); - expect(result.finalUrl, `Expected ${BASE_URL}${to} but got ${result.finalUrl}`).toContain(to); - expect(result.redirectCount, 'Should be single-hop redirect').toBeLessThanOrEqual(2); - expect(result.responseTime, 'Redirect should be fast').toBeLessThan(MAX_REDIRECT_TIME); - }, 10000); - }); - }); - - describe('2. Cloud-Specific Override Rules (Must NOT Be Caught By Versioned Wildcards)', () => { - const tests: RedirectTest[] = [ - { - from: '/24.1/get-started/quick-start-cloud/', - to: '/cloud-data-platform/get-started/cluster-types/dedicated/quick-start-cloud/', - description: '24.1 cloud quickstart - should NOT redirect to streaming' - }, - { - from: '/23.3/get-started/quick-start-cloud/', - to: '/cloud-data-platform/get-started/cluster-types/dedicated/quick-start-cloud/', - description: '23.3 cloud quickstart - should NOT redirect to streaming' - }, - { - from: '/24.1/develop/http-proxy-cloud/', - to: '/cloud-data-platform/develop/http-proxy/', - description: '24.1 http-proxy-cloud - should NOT redirect to streaming' - }, - { - from: '/23.3/develop/http-proxy-cloud/', - to: '/cloud-data-platform/develop/http-proxy/', - description: '23.3 http-proxy-cloud - should NOT redirect to streaming' - }, - ]; - - tests.forEach(({ from, to, description }) => { - it(description, async () => { - const result = await testRedirect(from); - - expect(result.statusCode, `Expected 200 but got ${result.statusCode}`).toBe(200); - expect(result.finalUrl, `Expected cloud-data-platform path but got ${result.finalUrl}`).toContain('cloud-data-platform'); - expect(result.finalUrl, `Should NOT contain streaming in URL`).not.toContain('/streaming/24.1/'); - expect(result.finalUrl, `Should NOT contain streaming in URL`).not.toContain('/streaming/23.3/'); - expect(result.redirectCount, 'Should be single-hop redirect').toBeLessThanOrEqual(2); - }, 10000); - }); - }); - - describe('3. Two-Hop Prevention (Cluster Balancing & FIPS)', () => { - const tests: RedirectTest[] = [ - { - from: '/streaming/manage/cluster-balancing', - to: '/streaming/current/manage/cluster-maintenance/cluster-balancing/', - description: 'Direct redirect for cluster-balancing (no two-hop via /streaming/manage/*)' - }, - { - from: '/streaming/manage/fips-compliance', - to: '/streaming/current/manage/security/fips-compliance/', - description: 'Direct redirect for fips-compliance (no two-hop via /streaming/manage/*)' - }, - ]; - - tests.forEach(({ from, to, description }) => { - it(description, async () => { - const result = await testRedirect(from); - - expect(result.statusCode, `Expected 200 but got ${result.statusCode}`).toBe(200); - expect(result.finalUrl, `Expected ${BASE_URL}${to} but got ${result.finalUrl}`).toContain(to); - expect(result.redirectCount, 'Must be single-hop (not two-hop)').toBe(1); - expect(result.responseTime, 'Redirect should be fast').toBeLessThan(MAX_REDIRECT_TIME); - }, 10000); - }); - }); - - describe('4. Connect Component Restructure', () => { - const tests: RedirectTest[] = [ - { - from: '/connect/inputs/kafka/', - to: '/connect/components/inputs/kafka/', - description: 'Connect inputs restructure' - }, - { - from: '/connect/outputs/aws_s3/', - to: '/connect/components/outputs/aws_s3/', - description: 'Connect outputs restructure' - }, - { - from: '/connect/processors/mapping/', - to: '/connect/components/processors/mapping/', - description: 'Connect processors restructure' - }, - { - from: '/connect/caches/redis/', - to: '/connect/components/caches/redis/', - description: 'Connect caches restructure' - }, - { - from: '/connect/buffers/memory/', - to: '/connect/components/buffers/memory/', - description: 'Connect buffers restructure' - }, - { - from: '/connect/about', - to: '/connect/components/about/', - description: 'Connect about page restructure' - }, - ]; - - tests.forEach(({ from, to, description }) => { - it(description, async () => { - const result = await testRedirect(from); - - expect(result.statusCode, `Expected 200 but got ${result.statusCode}`).toBe(200); - expect(result.finalUrl, `Expected ${BASE_URL}${to} but got ${result.finalUrl}`).toContain(to); - expect(result.redirectCount, 'Should be single-hop redirect').toBeLessThanOrEqual(2); - }, 10000); - }); - }); - - describe('5. Cloud-Data-Platform Path Fixes', () => { - const tests: RedirectTest[] = [ - { - from: '/cloud-data-platform/rpk/', - to: '/cloud-data-platform/reference/rpk/', - description: 'RPK path correction - missing /reference/' - }, - { - from: '/cloud-data-platform/reference/rpk-profile/', - to: '/cloud-data-platform/reference/rpk/rpk-profile/', - description: 'RPK profile path correction' - }, - { - from: '/cloud-data-platform/reference/rpk-cloud/', - to: '/cloud-data-platform/reference/rpk/rpk-cloud/', - description: 'RPK cloud path correction' - }, - { - from: '/cloud-data-platform/connect/home/', - to: '/connect/home/', - description: 'Connect under cloud-data-platform redirects to /connect/' - }, - { - from: '/cloud-data-platform/develop/connect/home/', - to: '/connect/home/', - description: 'Connect under develop/connect redirects correctly' - }, - { - from: '/cloud-data-platform/develop/components/processors/mapping/', - to: '/connect/components/processors/mapping/', - description: 'Connect components under cloud-data-platform redirects to /connect/' - }, - ]; - - tests.forEach(({ from, to, description }) => { - it(description, async () => { - const result = await testRedirect(from); - - expect(result.statusCode, `Expected 200 but got ${result.statusCode}`).toBe(200); - expect(result.finalUrl, `Expected ${BASE_URL}${to} but got ${result.finalUrl}`).toContain(to); - expect(result.redirectCount, 'Should be single-hop redirect').toBeLessThanOrEqual(2); - }, 10000); - }); - }); - - describe('6. Streaming Version-less Paths', () => { - const tests: RedirectTest[] = [ - { - from: '/streaming/reference/', - to: '/streaming/current/reference/', - description: 'Streaming reference without version' - }, - { - from: '/streaming/deploy/', - to: '/streaming/current/deploy/', - description: 'Streaming deploy without version' - }, - { - from: '/streaming/develop/', - to: '/streaming/current/develop/', - description: 'Streaming develop without version' - }, - { - from: '/streaming/manage/', - to: '/streaming/current/manage/', - description: 'Streaming manage without version (not cluster-balancing)' - }, - { - from: '/streaming/upgrade/', - to: '/streaming/current/upgrade/', - description: 'Streaming upgrade without version' - }, - { - from: '/streaming/get-started/', - to: '/streaming/current/get-started/', - description: 'Streaming get-started without version' - }, - ]; - - tests.forEach(({ from, to, description }) => { - it(description, async () => { - const result = await testRedirect(from); - - expect(result.statusCode, `Expected 200 but got ${result.statusCode}`).toBe(200); - expect(result.finalUrl, `Expected ${BASE_URL}${to} but got ${result.finalUrl}`).toContain(to); - expect(result.redirectCount, 'Should be single-hop redirect').toBeLessThanOrEqual(2); - }, 10000); - }); - }); - - describe('7. Streaming Current Restructured Paths', () => { - const tests: RedirectTest[] = [ - { - from: '/streaming/current/licensing/', - to: '/streaming/current/get-started/licensing/', - description: 'Licensing moved to get-started' - }, - { - from: '/streaming/current/kubernetes/', - to: '/streaming/current/deploy/', - description: 'Kubernetes moved to deploy' - }, - { - from: '/streaming/current/manage/cluster-balancing', - to: '/streaming/current/manage/cluster-maintenance/cluster-balancing/', - description: 'Cluster-balancing moved to cluster-maintenance' - }, - { - from: '/streaming/current/manage/fips-compliance', - to: '/streaming/current/manage/security/fips-compliance/', - description: 'FIPS compliance moved to security' - }, - ]; - - tests.forEach(({ from, to, description }) => { - it(description, async () => { - const result = await testRedirect(from); - - expect(result.statusCode, `Expected 200 but got ${result.statusCode}`).toBe(200); - expect(result.finalUrl, `Expected ${BASE_URL}${to} but got ${result.finalUrl}`).toContain(to); - expect(result.redirectCount, 'Should be single-hop redirect').toBeLessThanOrEqual(2); - }, 10000); - }); - }); -});