haystack/docs-website/CONTRIBUTING.md

# Contributing to Haystack Docs

This guide explains how to contribute to the Haystack documentation in this repository. It complements the main Haystack contribution guide in `deepset-ai/haystack` and focuses on authoring, reviewing, and maintaining docs.

If you plan to contribute code, tests, or integration changes, see the [main contribution guide](https://github.com/deepset-ai/haystack/blob/main/CONTRIBUTING.md) in the Haystack repository instead. For docs-related PRs that touch both code and docs, please follow both guides.

## What you’ll need

- Node.js 18+ and npm (recommended)
- Optional: [Vale](https://github.com/errata-ai/vale) for prose/style linting. See [Prose/style linting with Vale](#prose-style-linting-with-vale) section for more details.

Install Node.js and npm (macOS examples):

- Recommended (using nvm): see [nvm docs](https://github.com/nvm-sh/nvm#installing-and-updating)

```bash
brew install nvm
mkdir -p ~/.nvm
echo 'export NVM_DIR="$HOME/.nvm"' >> ~/.zshrc
echo '[ -s "/opt/homebrew/opt/nvm/nvm.sh" ] && . "/opt/homebrew/opt/nvm/nvm.sh"' >> ~/.zshrc
exec $SHELL -l
nvm install 18
nvm use 18
node -v && npm -v
```

- Alternative (Homebrew or official installer):

```bash
brew install node
```

Or download an installer from the Node.js website: [nodejs.org/download](https://nodejs.org/en/download)

Start a local dev server:

```bash
npm ci
npm run start
```

Build and preview the production site locally:

```bash
npm run build
npm run serve
```

## Repository structure (docs highlights)

- `docs/`: Narrative documentation (guides, concepts, how-tos)
  - `docs/_templates/`: Authoring templates you can copy when creating new pages
- `reference/`: API reference docs (organized by a separate docs plugin)
- `sidebars.js`: Sidebar for `docs/`
- `reference-sidebars.js`: Sidebar for `reference/`
- `versions.json`, `versioned_docs/`, `versioned_sidebars/`: Docusaurus versioning
- `.vale/` and `.vale.ini`: Prose linting configuration (Vale)

## Writing and style

Adhere to our internal Writing Guidelines (American English; Google developer style; concise, active voice; accessible; inclusive). Key expectations:

- Use second person (you) and present tense.
- Prefer simple words; avoid intensifiers and slang.
- Capitalization:
  - Use title case for page titles and headings.
  - Capitalize Haystack component class names exactly as in code (for example, `OpenAIAnswerGenerator`).
  - Do not capitalize generic terms like pipeline or component when used generically.
- Code and API names:
  - Use backticks for parameters, classes, and methods in running text; include parentheses for methods (for example, `PreProcessor.process()`).
  - Ensure code samples are runnable and tested.
- Lists and headings:
  - Make list items parallel; prefer short sentences.
  - Avoid overly deep heading hierarchies (limit to three levels where possible).
- GUI text:
  - Use Click in bold for buttons and tabs (for example, Click **Save**). Use Select in italics for lists/options (for example, Select *Workspace*).
- Links:
  - Use descriptive link text, not bare URLs. Add related links at the end when appropriate.
- Images:
  - Use alt text; place images after the instruction they illustrate; keep file sizes small.

## Authoring new or updated pages

1. Decide where the content belongs in the navigation structure.
2. Create or update the file in the appropriate folder.
3. Add required frontmatter:

   ```md
   ---
   title: "Page Title"
   id: "page-title"
   description: "1–2 sentences, used for SEO and previews"
   slug: "/target-url"
   ---
   ```

4. Update navigation:
   - For `docs/`, edit `sidebars.js` to add the new page in the right category.
   - For `reference/`, update `reference-sidebars.js` if needed (some sections may be autogenerated).
5. Use templates when applicable:
   - Copy from `docs/_templates/` and move the copy to the final location under `docs/`.

### Linking and anchors

- Prefer relative links to other docs files; avoid absolute URLs where a relative link is possible.
- Use explicit anchors for headings if you need stable cross-links.

### Admonitions (callouts)

Use Docusaurus admonitions sparingly and only for supporting information:

```mdx
:::tip
Short tip that helps the reader succeed.
:::

:::info
Useful but non-blocking background.
:::

:::warning
Risky settings or potential pitfalls.
:::

:::danger
Data loss or security-impacting issues.
:::
```

## Prose/style linting with Vale

Vale runs in CI on pull requests and pushes to `main`. PRs fail on error-level alerts; warnings and suggestions are annotated but don't fail. Run it locally to catch issues early.

Our Vale configuration aims to align with our internal writing rules (Google style + Haystack-specific checks).

If you encounter a StylesPath error, ensure the styles folder path in `.vale.ini` matches the repository layout.

Install Vale (macOS example):

```bash
brew install vale
```

For better MDX linting locally, also install `mdx2vast`:

```bash
npm install -g mdx2vast
```

Run Vale at the repo root:

```bash
vale --config .vale.ini "**/*.{md,mdx}"
```

CI behavior:

- Runs on PRs and pushes as a GitHub Check with annotations.
- The job fails on error-level alerts (`fail_on_error: true`); suggestions and warnings annotate but don't fail.
- Maintainers can switch to PR review comments by using the `github-pr-review` reporter.

## Local build checks

Before you open a PR, ensure the site builds cleanly:

```bash
npm run build
```

Address warnings about broken links, anchors, and duplicate routes before submitting.

## Moving or removing pages

- Keep existing URLs stable whenever possible. If you move a page, retain its `slug` so the path does not change.
- Update `sidebars.js` or `reference-sidebars.js` accordingly.
- If a URL must change, coordinate with maintainers to set up a redirect strategy and avoid broken inbound links.

## Images and assets

- Place shared images in `static/img/` or per-section assets in `docs/assets/`.
- Use descriptive filenames and alt text.
- Prefer optimized images; the site uses responsive image tooling to reduce payload size.

## API Reference contributions

- The API documentation is automatically generated from Python docstrings in the Haystack codebase. To change API docs, edit the relevant docstrings in the [Haystack repository](https://github.com/deepset-ai/haystack) and open a PR there.
- Do not edit files under `reference/` in this repository. They are regenerated and any manual changes will be overwritten.

## Accessibility and inclusivity checklist

- Alt text for images
- Descriptive link text
- Clear, concise sentences; avoid jargon when possible
- Inclusive language and examples

## Pull request checklist

Before submitting your PR:

- Content follows our writing and style rules.
- Navigation updated (`sidebars.js` / `reference-sidebars.js`).
- Internal links verified (no broken anchors).
- Code samples tested and language tags set on code blocks.
- Images optimized and include alt text.
- Local build passes (`npm run build`).
- Vale checks pass (CI) or are locally resolved.
- Conventional commit message used in the PR title (for example, `docs: add X`, `docs: fix Y`).

## Review process

- Open a PR from your branch. Include context, screenshots (if UI changes are shown), and link to related issues.
- Maintainers may request changes for clarity, accuracy, scope, or style.
- Once approved and checks pass, a maintainer will merge. Preview deployments may be available on the PR.