Documentation Structure & Workflow

Follow these conventions when creating or editing documentation:

1. Docs live in docs/ • Use Markdown (.md) files.
   • Images and other assets go in docs/_static/.

2. Section Folders mirror MkDocs navigation (see mkdocs.yml): • 🚀 Get Started → docs/getstarted/
   • 📚 Core Concepts → docs/concepts/
   • 🧪 Experimental → docs/experimental/
   • 🛠️ How-to Guides → docs/howtos/
   • 📖 References → docs/references/
   • Community → docs/community/

   Place new pages in the appropriate folder and update mkdocs.yml nav: so the page appears in navigation.

3. Notebook-to-Markdown • Convert notebooks to Markdown with docs/ipynb_to_md.py.
   • Commit the generated .md; notebooks themselves should not live in docs/.

4. Local preview / build • Run make build-docs to build HTML, make serve-docs to preview locally (defined in DEVELOPMENT.md).

5. Style & Assets • Use relative links (../) within docs.
   • Reference images via _static/… paths so they work in both dev and hosted docs.
   • Custom templates/CSS live in docs/extra/ — avoid editing material theme defaults directly.

6. API References (mkdocstrings) • Always use public API paths in [ClassName][ragas.module.ClassName] references. • Check what's exported in __init__.py — if a class isn't in __all__, mkdocstrings can't link to it. • Example: Use [BasePrompt][ragas.prompt.BasePrompt] not [BasePrompt][ragas.prompt.base.BasePrompt] or internal module paths.

7. Do not modify generated or third-party files in _static/, extra/overrides/, or extra/components/ without good reason.

---

Formatting Guidelines

• When introducing a list with text ending in a colon (e.g., "This will:"), always add a blank line before the first list item.
• In a numbered list, do not add any new line between the items.