chore: import upstream snapshot with attribution

docs-website/CONTRIBUTING.md

@@ -0,0 +1,474 @@
+# Contributing to Haystack Documentation
+
+Thank you for your interest in contributing to the Haystack documentation! This guide provides everything you need to write, review, and maintain high-quality documentation for the Haystack project.
+
+This guide focuses specifically on documentation contributions. For code contributions, tests, or integrations in the main Haystack codebase, see the [main Haystack contribution guide](https://github.com/deepset-ai/haystack/blob/main/CONTRIBUTING.md).
+
+## TL;DR — Your first docs PR in 10 minutes
+
+1. You won't be able to make changes directly to this repo, so the first step is to [create a fork](../CONTRIBUTING.md#clone-the-git-repository).
+
+2. Once your fork is ready, you can clone a local copy with:
+
+```bash
+git clone https://github.com/YOUR_USERNAME/haystack.git
+cd haystack/docs-website
+```
+
+3. Install and start:
+
+```bash
+npm install
+npm start
+```
+
+**Note:** All subsequent commands in this guide should be run from the `haystack/docs-website` directory unless otherwise specified.
+
+4. Edit under `docs/` for the unstable version, and under `versioned_docs/version-<highest>/` for the latest stable release. If you add a new page, include its ID in `sidebars.js` or the appropriate versioned sidebar.
+
+5. Optional production check:
+
+```bash
+npm run build && npm run serve
+```
+
+6. Commit and push:
+
+```bash
+git checkout -b docs/your-branch
+git add .
+git commit -m "docs: fix <desc>"
+git push -u origin HEAD
+```
+
+7. Open a PR and review the [Pull Request Checklist](#pull-request-checklist).
+
+**Table of Contents**
+
+- [TL;DR — Your first docs PR in 10 minutes](#tldr--your-first-docs-pr-in-10-minutes)
+- [Authoring New or Updated Pages](#authoring-new-or-updated-pages)
+  - [Where should I edit?](#where-should-i-edit)
+  - [Page Frontmatter](#page-frontmatter)
+  - [Updating Navigation](#updating-navigation)
+  - [Linking and Anchors](#linking-and-anchors)
+  - [Admonitions (Callouts)](#admonitions-callouts)
+- [Working with Templates](#working-with-templates)
+- [Testing](#testing)
+  - [Build Testing](#build-testing)
+- [API Reference Contributions](#api-reference-contributions)
+- [Understanding Documentation Versions and Where to Make Changes](#understanding-documentation-versions-and-where-to-make-changes)
+- [Preview Deployments](#preview-deployments)
+- [Troubleshooting](#troubleshooting)
+  - [Blank Page on npm start](#blank-page-on-npm-start)
+  - [Cache Issues](#cache-issues)
+  - [Build Errors](#build-errors)
+- [Moving or Removing Pages](#moving-or-removing-pages)
+- [Images and Assets](#images-and-assets)
+- [Pull Request Process](#pull-request-process)
+  - [Pull Request Checklist](#pull-request-checklist)
+- [Review Process](#review-process)
+- [Accessibility and Inclusivity](#accessibility-and-inclusivity)
+- [Getting Help](#getting-help)
+
+## Authoring New or Updated Pages
+
+### Where should I edit?
+
+| Your change | Edit here | Also edit here |
+|---|---|---|
+| New feature on Haystack `main` | `docs/` | — |
+| Fix in current stable docs | `docs/` | `versioned_docs/version-<highest>/` (for example, `version-2.20`) |
+| API reference content | Edit Python docstrings in main repo | — |
+
+### Page Frontmatter
+
+Every documentation page requires frontmatter at the top:
+
+```md
+---
+title: "Page Title"
+id: "page-id"
+description: "One to two sentences describing the page content for SEO and previews"
+slug: "/target-url"
+---
+```
+
+**Frontmatter fields:**
+
+- `title`: Displayed page title (title case)
+- `id`: Unique identifier for the page
+- `description`: SEO description (1-2 sentences)
+- `slug`: URL path for the page (optional, defaults to file path)
+
+### Updating Navigation
+
+After creating or moving a page, update the sidebar:
+
+**For narrative docs (`docs/`):**
+
+Edit `sidebars.js` and add your page to the appropriate category:
+
+```javascript
+{
+  type: 'category',
+  label: 'Concepts',
+  items: [
+    'concepts/pipelines',
+    'concepts/your-new-page',  // Add here
+  ],
+}
+```
+
+**For API reference (`reference/`):**
+
+Edit `reference-sidebars.js` if needed (however, most sections are auto-generated).
+
+### Linking and Anchors
+
+**Links within `docs/`:**
+
+Use relative paths for links within the same documentation section:
+
+```md
+See the [Pipeline Guide](../concepts/pipelines.mdx)
+See the [Components Overview](./components-overview.mdx)
+```
+
+**Links between `docs/` and `reference/`:**
+
+Because `docs/` and `reference/` are separate Docusaurus plugin instances, you must use absolute paths when linking between them:
+
+```md
+<!-- From docs/ to reference/ -->
+See the [Pipeline API Reference](/reference/haystack-api/pipelines/pipeline)
+
+<!-- From reference/ to docs/ -->
+See the [Pipeline Concepts Guide](/docs/concepts/pipelines)
+```
+
+**Note:** Always use `/docs/` or `/reference/` as the path prefix when linking across sections, not relative paths like `../../reference/`.
+
+**Explicit anchors:**
+
+For stable cross-links, use explicit heading IDs:
+
+```markdown
+## Installation {#install-guide}
+```
+
+Link to it: `[Install](./page.mdx#install-guide)` or `[Install](/docs/overview/quick-start#install-guide)` from `reference/`
+
+### Admonitions (Callouts)
+
+Use Docusaurus admonitions sparingly for supporting information:
+
+```mdx
+:::note[General notes or important information to highlight.]
+:::
+
+:::tip[Short tip that helps the reader succeed.]
+:::
+
+:::info[Useful but non-blocking background information.]
+:::
+
+:::warning[Risky settings or potential pitfalls.]
+:::
+
+:::danger[Data loss or security-impacting issues.]
+:::
+```
+
+## Working with Templates
+
+Starter templates are available in `docs/_templates/`:
+
+- `component-template.mdx` - For new component documentation
+- `document-store-template.mdx` - For new document store guides
+
+**How to use templates:**
+
+1. Copy the appropriate template from `docs/_templates/`
+2. Move the copy to its final location under `docs/`
+3. Update the frontmatter (title, id, description, slug)
+4. Fill in all sections marked with placeholders
+5. Update the sidebar to include your new page
+
+**Do not:**
+- Commit new documentation under `_templates/`
+- Leave template placeholder text in production docs
+
+## Testing
+
+### Build Testing
+
+We strongly recommend building the site locally before opening a PR:
+
+```bash
+npm run build
+```
+
+This command:
+- Builds production-ready static files
+- Validates all links and anchors
+- Reports broken links, duplicate routes, and errors
+
+**Fix all warnings before submitting your PR.** For minor changes like typo fixes, you may skip the local build and rely on CI feedback, but for substantial changes (new pages, restructuring, multiple edits), a local build helps catch issues early and saves CI time.
+
+## API Reference Contributions
+
+The API reference documentation is automatically generated from Python docstrings in the main Haystack codebase.
+
+**To update API documentation:**
+
+1. Edit docstrings in the [Haystack repository](https://github.com/deepset-ai/haystack)
+2. Open a PR in the main Haystack repo
+3. After merge, the API reference will be automatically synced through CI
+
+**Do not:**
+- Manually edit files in `reference/` or `reference_versioned_docs/`
+- Commit changes to auto-generated API documentation
+- Any manual changes will be overwritten by the next sync
+
+## Understanding Documentation Versions and Where to Make Changes
+
+The documentation structure supports multiple Haystack versions. Haystack releases new versions monthly, and documentation versioning is handled automatically through GitHub workflows during the release process.
+
+**Documentation directories:**
+- `docs/` - Unstable/next version (corresponds to Haystack's `main` branch)
+- `versioned_docs/version-X.Y/` - Stable release documentation for version X.Y
+
+**Note:** The highest version number in `versioned_docs/` represents the current stable release. For example, if you see `version-2.20`, `version-2.19`, and `version-2.18`, then version 2.20 is the current stable release, and older versions are for reference.
+
+**When to edit which version:**
+
+**Scenario 1: New feature or change in Haystack main branch**
+
+If you're documenting a new feature or change that exists in Haystack's `main` branch (next release):
+
+✅ Edit files in `docs/` (the unstable version)
+
+Example: A new component was added to Haystack main → document it in `docs/pipeline-components/`
+
+**Scenario 2: Bug fix or correction for current release**
+
+If you're fixing an error in the current release documentation (for example, incorrect information, broken link, typo):
+
+✅ Edit files in BOTH locations:
+1. `docs/` (so the fix persists in future versions)
+2. `versioned_docs/version-<highest>/` (the highest-numbered version directory)
+
+Example: A code example has a bug in the Pipelines guide → fix it in both `docs/concepts/pipelines.mdx` AND `versioned_docs/version-2.20/concepts/pipelines.mdx` (if 2.20 is the current stable release)
+
+**Pro tip:** When fixing bugs in current release docs, make the change in `docs/` first, then copy it to the highest-numbered versioned directory to ensure consistency.
+
+## Preview Deployments
+
+Pull requests that modify documentation will generate preview deployments once authorized by a maintainer. Once authorized, check your PR for a preview link, which allows you and reviewers to see the changes in a live environment before merging.
+
+Preview deployments include:
+- Full site build with your changes
+- All versions and navigation
+- Identical to production except for the URL
+
+## Troubleshooting
+
+### Blank Page on npm start
+
+If you see a blank page when running `npm start`:
+
+```bash
+# Clear Docusaurus cache
+npm run clear
+npm start
+```
+
+If the issue persists, build once to generate route metadata:
+
+```bash
+npm run build
+npm start
+```
+
+This is necessary because Docusaurus needs to generate internal routing metadata for versioned docs on first run.
+
+### Cache Issues
+
+Clear cached data if something looks off:
+
+```bash
+npm run clear
+```
+
+This removes:
+- `.docusaurus/` directory
+- Build cache
+- Generated metadata
+
+### Build Errors
+
+**Broken links:**
+- Check that all internal links use correct relative paths
+- Verify file names and paths match exactly (case-sensitive)
+- Ensure linked pages have proper frontmatter with `id` field
+
+**Duplicate routes:**
+- Check for duplicate `slug` values in frontmatter
+- Ensure no two pages map to the same URL path
+
+**Missing images:**
+- Verify image paths are correct
+- Check that images exist in `static/img/` or local `assets/` directories
+- Use relative paths from the markdown file location
+
+## Moving or Removing Pages
+
+**Moving a page:**
+
+1. Keep the existing URL stable by retaining the `slug` in frontmatter
+2. Update `sidebars.js` or `reference-sidebars.js` to reflect new file location
+3. Update any internal links that reference the moved page
+
+**Removing a page:**
+
+1. Remove the file from `docs/`
+2. Remove references from `sidebars.js`
+3. Check for and update any links pointing to the removed page
+4. Coordinate with maintainers for redirect setup if the URL was public
+
+**If a URL must change:**
+- Coordinate with maintainers to set up redirect rules
+- Avoid breaking inbound links from external sites
+
+## Images and Assets
+
+Shared images are stored in `static/img/`.
+
+**Best practices:**
+- Use descriptive filenames (for example, `pipeline-architecture.png`)
+- Optimize images before committing (use tools like ImageOptim, TinyPNG)
+- Prefer modern formats (WebP, optimized PNG/JPEG)
+- Always include alt text for accessibility
+
+**Adding images:**
+
+Use the `ClickableImage` component for all images. Import it at the top of your MDX file:
+
+```mdx
+import ClickableImage from "@site/src/components/ClickableImage";
+
+<ClickableImage
+  src="/img/pipeline-architecture.png"
+  alt="Pipeline architecture diagram"
+/>
+```
+
+**For zoomable images** (diagrams, screenshots that users may want to see in detail), use `size="large"`:
+
+```mdx
+<ClickableImage
+  src="/img/detailed-architecture.png"
+  alt="Detailed architecture diagram"
+  size="large"
+/>
+```
+
+**Images with transparent backgrounds:**
+
+For transparent PNGs that need better visibility in dark mode, add a background class:
+
+```mdx
+<!-- White background in dark mode -->
+<div className="img-white-bg">
+  <ClickableImage src="/img/logo.png" alt="Logo" />
+</div>
+
+<!-- Light grey background (softer) -->
+<div className="img-light-bg">
+  <ClickableImage src="/img/diagram.png" alt="Diagram" />
+</div>
+```
+
+**Youtube Embed**
+
+For embedding YouTube videos, use the `YouTubeEmbed` component:
+
+```mdx
+import YouTubeEmbed from "@site/src/components/YouTubeEmbed";
+
+<YouTubeEmbed videoId="dQw4w9WgXcQ" title="Example Video" />
+```
+
+## Pull Request Process
+
+### Pull Request Checklist
+
+Before submitting your PR, verify:
+
+- [ ] Content follows writing and style guidelines
+- [ ] Navigation updated (`sidebars.js` or `reference-sidebars.js`)
+- [ ] Internal links verified (no broken anchors)
+- [ ] Code samples tested and include language tags
+- [ ] Images optimized and include alt text
+- [ ] Local build passes (`npm run build`) - recommended for substantial changes
+- [ ] Vercel preview deployment succeeds (fix any deployment errors)
+- [ ] Conventional commit message format used in PR title
+- [ ] PR description includes context and related issues
+
+**PR title format:**
+
+Use conventional commits in the PR title:
+
+```
+docs: add troubleshooting guide for pipelines
+docs: fix typo in installation instructions
+docs: update API reference links
+```
+
+**PR description:**
+
+Include:
+- Summary of changes
+- Screenshots (if UI changes are visible)
+- Related issues (for example, "Fixes #123")
+- Testing performed
+- Notes for reviewers
+
+## Review Process
+
+1. Open a PR from your branch to `main`
+2. Automated checks will run (build validation)
+3. Maintainers will review your changes
+4. Address any requested changes
+5. Once approved and checks pass, a maintainer will merge
+6. Your changes will be deployed automatically
+
+## Accessibility and Inclusivity
+
+Ensure your documentation is accessible to all users:
+
+- **Alt text:** Provide descriptive alt text for all images
+- **Link text:** Use descriptive link text (not "click here")
+- **Language:** Use clear, concise sentences; avoid jargon where possible
+- **Examples:** Use inclusive language and diverse examples
+- **Headings:** Use proper heading hierarchy (don't skip levels)
+- **Code blocks:** Include language tags for proper syntax highlighting
+
+## Getting Help
+
+**Questions about contributing:**
+- Review this guide and the [main Haystack contribution guide](../CONTRIBUTING.md)
+- Check the [README](./README.md) for documentation site specifics
+- Check existing [issues](https://github.com/deepset-ai/haystack/issues) and [discussions](https://github.com/deepset-ai/haystack/discussions)
+- Ask in the [Discord community](https://discord.com/invite/haystack)
+
+**Technical issues:**
+- Search existing issues first
+- Open a new issue with the `documentation` label
+- Provide reproduction steps and environment details
+
+**Style or writing questions:**
+- Refer to the [Google Developer Documentation Style Guide](https://developers.google.com/style)
+- Ask maintainers for clarification in your PR
+
+Thank you for contributing to Haystack documentation! Your efforts help make Haystack more accessible and easier to use for everyone.