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 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 for prose/style linting. See Prose/style linting with Vale section for more details.

Install Node.js and npm (macOS examples):

• Recommended (using nvm): see nvm docs

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):

brew install node

Or download an installer from the Node.js website: nodejs.org/download

Start a local dev server:

npm ci
npm run start

Build and preview the production site locally:

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:

   ---
   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:

:::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):

brew install vale

For better MDX linting locally, also install mdx2vast:

npm install -g mdx2vast

Run Vale at the repo root:

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:

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 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.