docs: update documentation to use block quote callouts for admonitions

HosseinNejatiJavaremi · HosseinNejatiJavaremi · commit 008778eaaf84 · 2026-03-13T03:33:56.000+03:30
diff --git a/.cursor/rules/documentation.mdc b/.cursor/rules/documentation.mdc
@@ -78,7 +78,10 @@ def get_item(key: str) -> str | None:
 
 ## Writing Style
 
-- **Admonitions**: use `!!! note`, `!!! tip`, `!!! warning`. `note` supports an optional inline title: `!!! note "Title"`.
+- **Admonitions**: use block quote callouts instead of MkDocs `!!!` admonitions, as PyCharm's markdown formatter strips the required indentation. Format: `> **Type:** message text` where Type is one of `Tip`, `Note`, `Warning`, `Danger`.
+  - Single-line: `> **Tip:** Install the extra before use.`
+  - Multi-line: prefix every line with `>`, use `>` on blank lines to keep the block together.
+  - With nested code block: open with `> **Tip:** intro text`, then `>`, then `> \`\`\`lang ... \`\`\``
 - **Cross-links**: always relative paths (e.g., `[Error Handling](../error_handling.md)`).
 - **Emphasis**: bold (`**term**`) for key terms on first mention. No emoji outside `index.md` and overview pages.
 - **Tables**: use for structured comparison data (extras matrix, config options).
diff --git a/docs/404.md b/docs/404.md
@@ -19,5 +19,4 @@ It may have been moved, renamed, or deleted.
 - [API Reference](api_reference/index.md) — full reference for all public classes
 - [FAQ](community/faq.md) — frequently asked questions
 
-!!! tip "Search the docs"
-Use the search bar at the top of the page to find any topic instantly.
+> **Tip:** Use the search bar at the top of the page to find any topic instantly.
diff --git a/docs/community/contributing.md b/docs/community/contributing.md
@@ -60,9 +60,8 @@ make install
 make install-dev
 ```
 
-!!! tip "Pre-commit Hooks"
-Running `make install-dev` sets up pre-commit hooks that automatically run linting, formatting, and type checking on
-every commit. Use `make pre-commit` to run all hooks manually before opening a pull request.
+> **Tip:** Running `make install-dev` sets up pre-commit hooks that automatically run linting, formatting, and type
+> checking on every commit. Use `make pre-commit` to run all hooks manually before opening a pull request.
 
 ## Contribution Guidelines
 
@@ -229,9 +228,8 @@ New adapters follow a consistent checklist. Use this as your guide when contribu
 
 8. **Update `mkdocs.yml`** — add both new pages under the appropriate `nav:` keys.
 
-!!! note "Issue templates"
-Use the [GitHub issue templates](https://github.com/SyntaxArc/ArchiPy/issues/new/choose) when
-reporting bugs, requesting features, or proposing new adapters.
+> **Note:** Use the [GitHub issue templates](https://github.com/SyntaxArc/ArchiPy/issues/new/choose) when reporting
+> bugs, requesting features, or proposing new adapters.
 
 ## Code of Conduct
 
diff --git a/docs/community/faq.md b/docs/community/faq.md
@@ -201,8 +201,8 @@ REDIS__PORT=6379
 ENVIRONMENT=DEV
 ```
 
-!!! warning "Never commit `.env` to version control"
-Add `.env` to your `.gitignore`. Use `.env.example` to document the required variables without real values.
+> **Warning:** Add `.env` to your `.gitignore`. Use `.env.example` to document the required variables without real
+> values.
 
 ### Can I override configuration at runtime?
 
diff --git a/docs/community/license.md b/docs/community/license.md
@@ -18,9 +18,8 @@ Copyright 2024 [SyntaxArc](https://github.com/SyntaxArc) — Hossein Nejati & Me
 | Sublicense and distribute under a different license               | Preserve all existing copyright, patent, and attribution notices           |
 | Use patents contributed by contributors royalty-free              | Patent rights terminate if you bring patent litigation against the project |
 
-!!! note "Trademark Restriction"
-The Apache 2.0 license does **not** grant permission to use the SyntaxArc trade names, trademarks, or service marks,
-except as required for customary description of the software's origin.
+> **Note:** The Apache 2.0 license does **not** grant permission to use the SyntaxArc trade names, trademarks, or
+> service marks, except as required for customary description of the software's origin.
 
 ## Full License Text
 
diff --git a/docs/community/security.md b/docs/community/security.md
@@ -25,9 +25,8 @@ Include as much detail as possible:
 
 You will receive an acknowledgment within **48 hours** and a status update within **7 days**.
 
-!!! warning "Coordinated Disclosure"
-Please allow the maintainers reasonable time (typically 90 days) to prepare and release a fix before
-disclosing the vulnerability publicly.
+> **Warning:** Please allow the maintainers reasonable time (typically 90 days) to prepare and release a fix before
+> disclosing the vulnerability publicly.
 
 ---
 
diff --git a/docs/getting-started/concepts.md b/docs/getting-started/concepts.md
@@ -27,9 +27,8 @@ graph LR
 | **Helpers**  | `helpers/`  | Pure utilities: decorators, interceptors, JWT, password, datetime               |
 | **Adapters** | `adapters/` | External service integrations: databases, caches, queues, APIs                  |
 
-!!! warning "One-way import rule"
-Imports flow inward only — `configs ← models ← helpers ← adapters`. Inner layers never import
-from outer layers. Violating this rule breaks testability and creates circular dependencies.
+> **Warning:** Imports flow inward only — `configs ← models ← helpers ← adapters`. Inner layers never import from outer
+> layers. Violating this rule breaks testability and creates circular dependencies.
 
 ---
 
@@ -201,16 +200,16 @@ class UserRegistrationLogic:
         ...
 ```
 
-!!! note "Logic layer collaboration rules"
-
-- Logic classes **may call other logic classes** — nested `@atomic` calls reuse the open session.
-- Logic classes **must never import or call a repository from another domain directly**.
-  Cross-domain reads must go through the other domain's logic class.
-
-    ```
-    ✅  OrderCreationLogic  →  UserQueryLogic  →  UserRepository
-    ❌  OrderCreationLogic  →  UserRepository  (bypasses domain boundary)
-    ```
+> **Note:** Logic layer collaboration rules:
+>
+> - Logic classes **may call other logic classes** — nested `@atomic` calls reuse the open session.
+> - Logic classes **must never import or call a repository from another domain directly**.
+    > Cross-domain reads must go through the other domain's logic class.
+    >
+    >     ```
+>     ✅  OrderCreationLogic  →  UserQueryLogic  →  UserRepository
+>     ❌  OrderCreationLogic  →  UserRepository  (bypasses domain boundary)
+>     ```
 
 ---
 
diff --git a/docs/getting-started/installation.md b/docs/getting-started/installation.md
@@ -24,8 +24,8 @@ Before starting, ensure you have:
   uv is a fast Python package installer and resolver. Install it via
   the [official guide](https://docs.astral.sh/uv/getting-started/installation/).
 
-!!! tip "Recommended Package Manager"
-ArchiPy recommends **`uv`** — it is significantly faster than `pip` and provides better dependency resolution.
+> **Tip:** ArchiPy recommends **`uv`** — it is significantly faster than `pip` and provides better dependency
+> resolution.
 
 ## Install ArchiPy
 
@@ -100,14 +100,12 @@ If issues arise, verify:
 3. Build tools are available (UV handles this automatically)
 4. Database-specific dependencies are installed if using database adapters
 
-!!! warning "Python 3.14+ Required"
-ArchiPy uses `X | Y` union syntax, lowercase generics (`list[str]`), and other modern features
-that require Python 3.14 or later. Using an older Python will result in `SyntaxError` at import time.
+> **Warning:** ArchiPy uses `X | Y` union syntax, lowercase generics (`list[str]`), and other modern features that
+> require Python 3.14 or later. Using an older Python will result in `SyntaxError` at import time.
 
-!!! tip "IDE Integration"
-For the best development experience, use an IDE that supports Python type hints, such as PyCharm or VS Code with the
-Python extension. The project uses modern Python type hints and benefits from IDE support for type checking and
-autocompletion.
+> **Tip:** For the best development experience, use an IDE that supports Python type hints, such as PyCharm or VS Code
+> with the Python extension. The project uses modern Python type hints and benefits from IDE support for type checking and
+> autocompletion.
 
 ## See Also
 
diff --git a/docs/getting-started/project_structure.md b/docs/getting-started/project_structure.md
@@ -101,13 +101,13 @@ project-root/
 | `entities/`                  | SQLAlchemy `BaseEntity` subclasses                              | Data structure only — no logic  |
 | `errors/`                    | Domain-specific exceptions extending ArchiPy base errors        | Raise with `raise ... from e`   |
 
-!!! tip "DTO naming conventions"
-
-- **Domain input**: `UserRegistrationInputDTO` — data arriving from the client
-- **Domain output**: `UserRegistrationOutputDTO` — data returned to the client
-- **Repository command**: `CreateUserCommandDTO` — a write operation
-- **Repository query**: `GetUserByIdQueryDTO` — a read operation
-- **Repository response**: `UserResponseDTO` — result from an adapter or repository
+> **Tip:** DTO naming conventions:
+>
+> - **Domain input**: `UserRegistrationInputDTO` — data arriving from the client
+> - **Domain output**: `UserRegistrationOutputDTO` — data returned to the client
+> - **Repository command**: `CreateUserCommandDTO` — a write operation
+> - **Repository query**: `GetUserByIdQueryDTO` — a read operation
+> - **Repository response**: `UserResponseDTO` — result from an adapter or repository
 
 ### `repositories/`
 
diff --git a/docs/getting-started/quickstart.md b/docs/getting-started/quickstart.md
@@ -13,11 +13,11 @@ with a typed config, a Redis adapter, and a TTL cache decorator in under five mi
 - Python 3.14 or later
 - `uv` package manager ([installation guide](https://docs.astral.sh/uv/getting-started/installation/))
 
-!!! tip "Check your Python version"
-
-```bash
-python --version  # must be 3.14+
-```
+> **Tip:** Check your Python version:
+>
+> ```bash
+> python --version  # must be 3.14+
+> ```
 
 ## Step 1 — Create the Project
 
diff --git a/docs/index.md b/docs/index.md
@@ -94,8 +94,7 @@ graph LR
 
 See [Concepts](getting-started/concepts.md) for the full architectural breakdown.
 
-!!! tip "Full examples"
-See the [Tutorials](tutorials/index.md) section for complete, runnable examples for every adapter and helper.
+> **Tip:** See the [Tutorials](tutorials/index.md) section for complete, runnable examples for every adapter and helper.
 
 ## Next Steps
 
diff --git a/docs/tutorials/adapters/elasticsearch.md b/docs/tutorials/adapters/elasticsearch.md
@@ -14,9 +14,8 @@ management with proper error handling and Python 3.14+ type hints.
 uv add "archipy[elasticsearch]"
 ```
 
-!!! tip
-The Elasticsearch adapter is an optional extra. Only install it when you need Elasticsearch support to keep your
-environment lean.
+> **Tip:** The Elasticsearch adapter is an optional extra. Only install it when you need Elasticsearch support to keep
+> your environment lean.
 
 ## Configuration
 
diff --git a/docs/tutorials/adapters/payment_gateways.md b/docs/tutorials/adapters/payment_gateways.md
@@ -14,9 +14,8 @@ with proper error handling and Python 3.14 type hints.
 uv add "archipy[parsian-ipg]"
 ```
 
-!!! tip
-The Parsian Shaparak payment gateway is an optional extra. Install it only when integrating with Iranian payment
-services.
+> **Tip:** The Parsian Shaparak payment gateway is an optional extra. Install it only when integrating with Iranian
+> payment services.
 
 ## Configuration
 
diff --git a/docs/tutorials/adapters/postgres.md b/docs/tutorials/adapters/postgres.md
@@ -14,8 +14,7 @@ configuration, CRUD, transactions, filtering, pagination, async patterns, and te
 uv add "archipy[postgres]"
 ```
 
-!!! tip
-The PostgreSQL adapter is an optional extra. Install it alongside any ORM extras you need, for example
+> **Tip:** The PostgreSQL adapter is an optional extra. Install it alongside any ORM extras you need, for example
 `archipy[postgres]`.
 
 ## Configuration
@@ -145,7 +144,8 @@ from archipy.models.errors import DatabaseConnectionError, DatabaseQueryError
 logger = logging.getLogger(__name__)
 
 
-class UserPostgresAdapter(PostgresSQLAlchemyAdapter, SQLAlchemyFilterMixin, SQLAlchemyPaginationMixin, SQLAlchemySortMixin):
+class UserPostgresAdapter(PostgresSQLAlchemyAdapter, SQLAlchemyFilterMixin, SQLAlchemyPaginationMixin,
+                          SQLAlchemySortMixin):
     """PostgreSQL adapter with filter, pagination, and sort query capabilities for the User domain."""
 
 
@@ -465,9 +465,9 @@ adapter = PostgresSQLAlchemyAdapter()
 
 
 def search_users(
-    search_term: str | None = None,
-    page: int = 1,
-    page_size: int = 20,
+        search_term: str | None = None,
+        page: int = 1,
+        page_size: int = 20,
 ) -> tuple[list[User], int]:
     """Search users with optional full-name filter, pagination, and sorting.
 
@@ -565,8 +565,7 @@ def count_active_users() -> int:
 
 ## Async Usage
 
-!!! tip "Install the async extra"
-Async PostgreSQL support requires the `sqlalchemy-async` extra:
+> **Tip:** Async PostgreSQL support requires the `sqlalchemy-async` extra:
 
 ```bash
 uv add "archipy[postgres,sqlalchemy-async]"
@@ -849,12 +848,12 @@ api_config = PostgresSQLAlchemyConfig(
     DATABASE="mydb",
     USERNAME="myuser",
     PASSWORD="secret",
-    POOL_SIZE=20,           # Keep 20 persistent connections open
-    POOL_MAX_OVERFLOW=10,   # Allow up to 10 additional overflow connections
-    POOL_TIMEOUT=5,         # Fail fast if pool is exhausted (5 s)
+    POOL_SIZE=20,  # Keep 20 persistent connections open
+    POOL_MAX_OVERFLOW=10,  # Allow up to 10 additional overflow connections
+    POOL_TIMEOUT=5,  # Fail fast if pool is exhausted (5 s)
     POOL_RECYCLE_SECONDS=300,  # Recycle connections every 5 min (avoids stale TCP)
-    POOL_PRE_PING=True,     # Validate connections before use
-    POOL_USE_LIFO=True,     # LIFO: reuse warm connections, keep cold ones idle
+    POOL_PRE_PING=True,  # Validate connections before use
+    POOL_USE_LIFO=True,  # LIFO: reuse warm connections, keep cold ones idle
 )
 
 # Batch/worker process — smaller pool
diff --git a/docs/tutorials/adapters/redis.md b/docs/tutorials/adapters/redis.md
@@ -16,8 +16,7 @@ First, ensure you have the Redis dependencies installed:
 uv add "archipy[redis]"
 ```
 
-!!! tip
-The Redis adapter is an optional extra. Install only when Redis support is needed.
+> **Tip:** The Redis adapter is an optional extra. Install only when Redis support is needed.
 
 ## Configuration
 
diff --git a/docs/tutorials/adapters/scylladb.md b/docs/tutorials/adapters/scylladb.md
@@ -17,8 +17,7 @@ The ScyllaDB adapter is included with ArchiPy. Ensure you have the required depe
 uv add "archipy[scylladb]"
 ```
 
-!!! tip
-The ScyllaDB adapter is an optional extra. Install it only when ScyllaDB or Cassandra support is required.
+> **Tip:** The ScyllaDB adapter is an optional extra. Install it only when ScyllaDB or Cassandra support is required.
 
 ## Configuration
 
diff --git a/docs/tutorials/error_handling.md b/docs/tutorials/error_handling.md
@@ -7,13 +7,11 @@ description: Practical tutorials for error handling patterns in ArchiPy.
 
 This document provides examples of how to use the error handling system in different scenarios.
 
-!!! note "Always use specific exception types"
-ArchiPy errors extend `BaseError` and map to standard HTTP status codes automatically when used
-with the FastAPI integration. Never catch or raise bare `Exception` — use the most specific type available.
+> **Note:** ArchiPy errors extend `BaseError` and map to standard HTTP status codes automatically when used with the
+> FastAPI integration. Never catch or raise bare `Exception` — use the most specific type available.
 
-!!! danger "Never swallow exceptions silently"
-Always either re-raise (with `raise ... from e`) or log and raise. Swallowing exceptions hides
-bugs and makes debugging nearly impossible in production.
+> **Danger:** Always either re-raise (with `raise ... from e`) or log and raise. Swallowing exceptions hides bugs and
+> makes debugging nearly impossible in production.
 
 ## Basic Error Handling
 
diff --git a/docs/tutorials/observability.md b/docs/tutorials/observability.md
@@ -278,9 +278,8 @@ def create_grpc_server() -> grpc.Server:
     return server
 ```
 
-!!! note "FastAPI + APM"
-ArchiPy does not ship a FastAPI APM middleware. For FastAPI Elastic APM or Sentry integration,
-use the official SDKs directly (`elasticapm.contrib.starlette.ElasticAPM` or
+> **Note:** ArchiPy does not ship a FastAPI APM middleware. For FastAPI Elastic APM or Sentry integration, use the
+> official SDKs directly (`elasticapm.contrib.starlette.ElasticAPM` or
 `sentry_sdk.integrations.fastapi.FastApiIntegration`). ArchiPy's APM interceptors cover gRPC only.
 
 ---
diff --git a/docs/tutorials/testing_strategy.md b/docs/tutorials/testing_strategy.md
@@ -18,9 +18,8 @@ adapters and in-memory fakes — are written as Gherkin features with Behave ste
 | BDD (mock adapters) | `behave` + mocks            | Single adapter / helper behaviour | Fast  | No                      |
 | BDD (integration)   | `behave` + `testcontainers` | Adapter against real service      | Slow  | Yes (Docker)            |
 
-!!! tip "Selectively run scenarios"
-Features that require a running service are tagged with `@needs-*`. Skip infrastructure-heavy scenarios
-when Docker is not available:
+> **Tip:** Features that require a running service are tagged with `@needs-*`. Skip infrastructure-heavy scenarios when
+> Docker is not available:
 
 ```bash
 uv run behave --tags=~@needs-redis         # skip Redis scenarios
@@ -151,9 +150,8 @@ class InMemorySQLAlchemyMock(BaseSQLAlchemyAdapterPort):
         return self._store.get(str(entity_id))
 ```
 
-!!! note "Keep mocks minimal"
-Implement only the methods your tests actually call. An `NotImplementedError` on unused methods is
-better than a mock that silently returns wrong values.
+> **Note:** Implement only the methods your tests actually call. An `NotImplementedError` on unused methods is better
+> than a mock that silently returns wrong values.
 
 ---
 
@@ -321,15 +319,13 @@ def step_retrieve(context, key, expected):
     logger.info("Redis value for key '%s' matched expected '%s'", key, expected)
 ```
 
-!!! tip "Global config is patched automatically"
-Each `*TestContainer.start()` updates `BaseConfig.global_config()` with the live container host and
-port. Adapters constructed after container startup automatically connect to the right endpoint —
-no manual config wiring needed in step definitions.
+> **Tip:** Each `*TestContainer.start()` updates `BaseConfig.global_config()` with the live container host and port.
+> Adapters constructed after container startup automatically connect to the right endpoint — no manual config wiring
+> needed in step definitions.
 
-!!! warning "Integration scenarios are slow"
-Each container start adds several seconds. Containers are started per-feature and stopped after
-each feature — `ContainerManager` skips already-running containers so sharing across features
-within a run is handled automatically.
+> **Warning:** Each container start adds several seconds. Containers are started per-feature and stopped after
+> each feature — `ContainerManager` skips already-running containers so sharing across features
+> within a run is handled automatically.
 
 ### Skipping infrastructure-heavy scenarios
 
