Add mdformat-mkdocs plugin and fix formatting

[marcinwolder-miquido]

Description:

• Add mdformat-mkdocs to the docs extra so mdformat respects MkDocs admonitions and image attributes.
• Update docs-format target to run mdformat with default wrap (keep) across README and docs.
• Reformat README and docs pages to align with mkdocs-aware mdformat output (admonitions and images preserved).
• Refresh uv.lock to capture the new docs dependency.

[coderabbitai]

Walkthrough

This PR updates documentation formatting infrastructure and applies consistent indentation across all markdown files. The Makefile's docs-format target is modified to remove the --wrap 100 constraint from mdformat, the mdformat-mkdocs plugin (version >=5.1.1) is added as a docs dependency in pyproject.toml, and whitespace/indentation adjustments are applied across multiple README and documentation files to achieve consistent formatting.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10-15 minutes

Rationale: While the diff spans many files (15+), the changes are highly homogeneous and repetitive—primarily indentation adjustments with no logic, control flow, or functional modifications. The tooling changes in Makefile and pyproject.toml are straightforward additions. Review focus is on verifying consistency and formatting correctness rather than analyzing varied logic patterns.

• Makefile: Verify the removal of --wrap 100 constraint aligns with the new mdformat-mkdocs plugin behavior
• pyproject.toml: Confirm the new mdformat-mkdocs dependency version constraint is appropriate

Possibly related PRs

• Update dependencies #440: Modifies the docs formatting workflow and Makefile docs-format target configuration
• Add docs #377: Adjusts documentation tooling configuration in Makefile and pyproject.toml docs extras

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately summarizes the main changes: adding the mdformat-mkdocs plugin and applying formatting fixes to align with the new plugin's output.
Description check	✅ Passed	The description is directly related to the changeset, providing clear context about adding the mdformat-mkdocs dependency, updating the Makefile target, and reformatting documentation files.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch feature/docs

---

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: ASSERTIVE

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between c5ead6c and 3529b18.

⛔ Files ignored due to path filters (1)

• uv.lock is excluded by !**/*.lock

📒 Files selected for processing (16)

• Makefile (1 hunks)
• README.md (1 hunks)
• docs/getting-started/index.md (2 hunks)
• docs/getting-started/installation.md (1 hunks)
• docs/getting-started/multimodal-data.md (4 hunks)
• docs/getting-started/printing-data.md (2 hunks)
• docs/guides/BasicConversation.md (1 hunks)
• docs/guides/BasicEvaluation.md (4 hunks)
• docs/guides/BasicModelGeneration.md (2 hunks)
• docs/guides/BasicStageUsage.md (1 hunks)
• docs/guides/ComprehensiveEvaluation.md (1 hunks)
• docs/guides/MultimodalContent.md (5 hunks)
• docs/guides/Postgres.md (3 hunks)
• docs/guides/Templates.md (3 hunks)
• docs/index.md (3 hunks)
• pyproject.toml (1 hunks)

🧰 Additional context used

📓 Path-based instructions (1)

docs/**/*.md

📄 CodeRabbit inference engine (AGENTS.md)

Add usage snippets that exercise async scopes; readers should see how to wire states through ctx

Files:

• docs/guides/MultimodalContent.md
• docs/guides/BasicConversation.md
• docs/getting-started/installation.md
• docs/guides/BasicModelGeneration.md
• docs/guides/Postgres.md
• docs/getting-started/index.md
• docs/getting-started/printing-data.md
• docs/index.md
• docs/guides/BasicStageUsage.md
• docs/getting-started/multimodal-data.md
• docs/guides/ComprehensiveEvaluation.md
• docs/guides/Templates.md
• docs/guides/BasicEvaluation.md

🧠 Learnings (12)

📓 Common learnings

Learnt from: CR
Repo: miquido/draive PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-02T14:30:08.757Z
Learning: Site is built with MkDocs + Material and `mkdocstrings` for API docs; lint with `make docs-lint` and format with `make docs-format` after editing

Learnt from: CR
Repo: miquido/draive PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-02T14:30:08.757Z
Learning: If behavior/API changes, update relevant docs under `docs/` and examples; update `mkdocs.yml` navigation when adding new documentation pages

📚 Learning: 2025-12-02T14:30:08.757Z

Learnt from: CR
Repo: miquido/draive PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-02T14:30:08.757Z
Learning: If behavior/API changes, update relevant docs under `docs/` and examples; update `mkdocs.yml` navigation when adding new documentation pages

Applied to files:

• docs/guides/MultimodalContent.md
• docs/guides/ComprehensiveEvaluation.md
• pyproject.toml

📚 Learning: 2025-12-02T14:30:08.757Z

Learnt from: CR
Repo: miquido/draive PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-02T14:30:08.757Z
Learning: Draive is built on top of Haiway for state, context, observability, and config management; understand and leverage its abstractions

Applied to files:

• docs/getting-started/installation.md
• README.md
• docs/getting-started/index.md
• docs/index.md
• docs/guides/BasicEvaluation.md

📚 Learning: 2025-06-16T10:28:07.434Z

Learnt from: KaQuMiQ
Repo: miquido/draive PR: 338
File: src/draive/lmm/__init__.py:1-2
Timestamp: 2025-06-16T10:28:07.434Z
Learning: The draive project requires Python 3.12+ as specified in pyproject.toml with "requires-python = ">=3.12"" and uses Python 3.12+ specific features like PEP 695 type aliases and generic syntax extensively throughout the codebase.

Applied to files:

• docs/guides/BasicModelGeneration.md
• docs/guides/BasicEvaluation.md

📚 Learning: 2025-05-28T17:41:57.460Z

Learnt from: KaQuMiQ
Repo: miquido/draive PR: 327
File: src/draive/helpers/instruction_preparation.py:28-34
Timestamp: 2025-05-28T17:41:57.460Z
Learning: The draive project uses and requires Python 3.12+, so PEP-695 generic syntax with square brackets (e.g., `def func[T: Type]()`) is valid and should be used instead of the older TypeVar approach.

Applied to files:

• docs/guides/BasicModelGeneration.md
• docs/guides/BasicEvaluation.md

📚 Learning: 2025-12-02T14:30:08.757Z

Learnt from: CR
Repo: miquido/draive PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-02T14:30:08.757Z
Learning: Applies to src/draive/__init__.py : Centralize public exports in `src/draive/__init__.py`; update this file when adding or modifying public APIs

Applied to files:

• docs/getting-started/index.md

📚 Learning: 2025-12-02T14:30:08.757Z

Learnt from: CR
Repo: miquido/draive PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-02T14:30:08.757Z
Learning: Site is built with MkDocs + Material and `mkdocstrings` for API docs; lint with `make docs-lint` and format with `make docs-format` after editing

Applied to files:

• Makefile
• pyproject.toml

📚 Learning: 2025-12-02T14:30:08.757Z

Learnt from: CR
Repo: miquido/draive PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-02T14:30:08.757Z
Learning: Run `make format` to format code and `make lint` to check types/lint before committing; ensure all checks pass

Applied to files:

• Makefile

📚 Learning: 2025-12-02T14:30:08.757Z

Learnt from: CR
Repo: miquido/draive PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-02T14:30:08.757Z
Learning: Applies to src/draive/**/*.py : Use context scoping (`ctx.scope(...)`) to bind scoped `Disposables`, active `State` instances, and avoid global state

Applied to files:

• docs/index.md

📚 Learning: 2025-12-02T14:30:08.757Z

Learnt from: CR
Repo: miquido/draive PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-02T14:30:08.757Z
Learning: Applies to docs/**/*.md : Add usage snippets that exercise async scopes; readers should see how to wire states through `ctx`

Applied to files:

• docs/guides/BasicStageUsage.md

📚 Learning: 2025-12-02T14:30:08.757Z

Learnt from: CR
Repo: miquido/draive PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-02T14:30:08.757Z
Learning: Use Python 3.13+; manage virtualenv with uv (available at `./.venv`, assume already set up); format with Ruff formatter; lint with Ruff, Bandit, and Pyright (strict); test with pytest

Applied to files:

• pyproject.toml

📚 Learning: 2025-12-02T14:30:08.757Z

Learnt from: CR
Repo: miquido/draive PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-02T14:30:08.757Z
Learning: Applies to **/*.py : Ensure structured concurrency concepts and valid coroutine usage; rely on haiway and asyncio packages

Applied to files:

• docs/guides/BasicEvaluation.md

🪛 LanguageTool

docs/getting-started/multimodal-data.md

[style] ~168-~168: Using many exclamation marks might seem excessive (in this case: 15 exclamation marks for a text that’s 2747 characters long)
Context: ...:400px; margin:auto; display: block;"} !!! tip There are ready-to-use methods...

(EN_EXCESSIVE_EXCLAMATION)

🔇 Additional comments (15)

docs/guides/BasicConversation.md (1)

82-86: Formatting improvements approved.

The indentation adjustments to lines 83 and 86 properly align bullet point continuations with markdown standards. These changes are consistent with the PR objective to apply mdformat formatting.

The file already demonstrates async scopes and proper ctx usage (lines 49–64), meeting the coding guideline for docs/**/*.md files to show how to wire states through ctx.

Makefile (1)

84-84: Makefile docs-format target now uses mdformat with default wrap behavior. ✓

Removing the --wrap 100 constraint aligns with the PR objective and allows the mdformat-mkdocs plugin to handle line wrapping without breaking MkDocs-specific syntax (admonitions, image attributes, etc.).

docs/guides/MultimodalContent.md (1)

20-22: Markdown formatting changes are correctly applied.

All indentation adjustments are mechanical output from mdformat-mkdocs and follow standard markdown list continuation structure. The file already includes an async example (lines 166–182) demonstrating ctx.scope usage as per documentation guidelines.

Also applies to: 85-85, 106-107, 139-140, 191-192, 194-195, 197-197

docs/getting-started/installation.md (1)

45-46: Markdown list formatting is correct.

Indentation adjustments follow standard markdown continuation format. Installation instructions and code examples remain accurate and complete.

Also applies to: 49-50, 51-52

docs/guides/ComprehensiveEvaluation.md (1)

10-10: Formatting changes maintain document structure and readability.

All indentation adjustments preserve list and prose hierarchy. The evaluator examples, including stateful evaluation with Haiway (lines 158–175), demonstrate proper async patterns and remain intact.

Also applies to: 12-12, 14-14, 106-107, 109-110, 111-112

README.md (1)

70-71: Formatting updates maintain README clarity.

Indentation adjustments to feature descriptions follow standard markdown formatting. The quick start example (lines 22–43) already demonstrates async context scoping with ctx, meeting documentation guidelines.

Also applies to: 72-73, 74-75, 76-77, 79-80

docs/guides/Postgres.md (1)

74-75: Postgres guide formatting is properly applied.

List continuation indentation is correct throughout. Async examples with ctx.scope (lines 22–31, 216–239) demonstrate proper context wiring patterns. SQL schemas and technical setup instructions remain clear and accurate.

Also applies to: 76-77, 79-80, 107-108, 109-110, 111-112, 144-145, 146-147, 148-149

docs/getting-started/index.md (1)

9-9: Getting started index formatting is correct.

Indentation adjustments follow standard markdown hierarchy. Conceptual descriptions of state management, context scoping, and core architecture remain clear and unchanged. Formatting supports readability without altering content.

Also applies to: 11-11, 14-14, 29-29, 32-32, 37-38, 40-42, 44-45

docs/guides/BasicEvaluation.md (1)

1-298: Formatting-only changes; content and examples remain intact.

The indentation and line-wrapping adjustments throughout this guide align with the mdformat-mkdocs standardization. Code examples continue to properly demonstrate async scope usage with ctx.scope(...) and evaluator composition patterns. No functional or semantic issues detected.

docs/index.md (1)

1-116: Formatting-only bullet-list indentation; content and references unchanged.

The indentation adjustments to bullet lists in the Key capabilities and Architecture essentials sections improve consistency without altering the substance. The quick-start example maintains proper ctx.scope context binding. All descriptions of features, providers, and architectural patterns remain accurate.

docs/getting-started/multimodal-data.md (1)

1-173: Markdown formatting and image attributes properly aligned with mdformat-mkdocs standards.

Indented code blocks, admonition syntax preservation (!!!), and image style attribute formatting are all correctly applied per the mdformat-mkdocs tooling. The content describing multimodal data structures, tags, and model I/O relationships remains semantically intact. The static analysis flag for "excessive exclamation marks" at line 168 is a false positive on the admonition syntax (!!! tip), which is valid MkDocs formatting.

docs/guides/BasicModelGeneration.md (1)

1-124: Formatting-only indentation adjustments; examples maintain proper async context binding.

Line-wrapping indentation changes throughout the prerequisites and customization sections align with mdformat standards. Code examples continue to correctly demonstrate ctx.scope(...) usage with provider configuration and DataModel validation. No functional or semantic issues detected.

docs/getting-started/printing-data.md (1)

1-158: Admonition content indentation properly formatted for mdformat consistency.

The indentation adjustments in the Note and Important admonition blocks align with mdformat standards. Code examples demonstrating string conversion helpers (.to_str(), .to_mapping(), .to_json()) and multimodal content rendering remain accurate and clear.

docs/guides/BasicStageUsage.md (1)

1-342: Formatting-only indentation; examples demonstrate excellent async scope and context binding patterns.

The indentation adjustments in the Core Concepts section align with mdformat standards. Code examples throughout—from basic completion stages to the end-to-end pipeline—properly demonstrate ctx.scope(...) usage with disposables, tool management, caching, retries, and observability. The examples align well with the coding guideline to show how to wire states through ctx. No functional or semantic issues detected.

docs/guides/Templates.md (1)

1-123: Formatting-only indentation adjustments; template usage and migration guidance remain clear.

The indentation changes throughout the template basics, repository configuration, and migration sections align with mdformat standards. Code examples correctly demonstrate async template resolution and TemplatesRepository state management within ctx.scope(...). The migration guidance from InstructionsRepository is preserved and remains accurate.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}