docs: name and link the example file before every snippet include

README.md

@@ -101,6 +101,11 @@ async def report(cache: AppCache):
 
 ## Documentation
 
+The guides are built from `docs/` into the site linked below. Read them there:
+a code block that includes one of the runnable examples renders on the site,
+while GitHub shows only its `--8<--` include line (the sentence before each
+block links the example file).
+
 - [Migrating to 0.4.0](https://fastapi-cachex.readthedocs.io/en/latest/MIGRATING_0_4/) — what 0.4.0 changes and how to upgrade from 0.3.x
 - [HTTP caching](https://fastapi-cachex.readthedocs.io/en/latest/HTTP_CACHING/) — the `@cache` decorator, Cache-Control directives, cache keys, invalidation and monitoring routes
 - [Application cache](https://fastapi-cachex.readthedocs.io/en/latest/APP_CACHE/) — `CacheManager`

docs/APP_CACHE.md

@@ -48,7 +48,7 @@ Complete runnable example: [`examples/app_cache.py`](https://github.com/allen009
 
 `@cached` does what `get_or_set()` does for a plain function, keyed on its
 arguments, so a loader or a call to another service is written once and
-cached wherever it is called:
+cached wherever it is called. From [`examples/app_cache.py`](https://github.com/allen0099/FastAPI-CacheX/blob/master/examples/app_cache.py):
 
 <!-- fmt:off -->
 ```python

docs/BACKENDS.md

@@ -242,7 +242,7 @@ answers again.
 ## Closing a backend
 
 Every backend has `aclose()`, which releases what it holds open. Call it on
-shutdown, at the end of the FastAPI lifespan:
+shutdown, at the end of the FastAPI lifespan, as [`examples/redis_backend.py`](https://github.com/allen0099/FastAPI-CacheX/blob/master/examples/redis_backend.py) does:
 
 <!-- fmt:off -->
 ```python

docs/DEVELOPMENT.md

@@ -268,6 +268,11 @@ its English comments on the Traditional Chinese site too; explain it in the
 text around the fence. `README.md` keeps its quick start inline, since PyPI and
 GitHub render it without snippets.
 
+GitHub renders a page under `docs/` without expanding the include: the reader
+sees the bare `--8<--` line. So the sentence before every fence names the
+example file and links to it on GitHub, in both languages (#394); the
+`README.md` says the same once for the whole `docs/` tree.
+
 ### Traditional Chinese translation
 
 A Traditional Chinese (`zh-TW`) translation is published at

docs/HTTP_CACHING.md

@@ -9,6 +9,8 @@ Complete runnable example: [`examples/http_cache.py`](https://github.com/allen00
 
 ## The `@cache` decorator
 
+The routes of [`examples/http_cache.py`](https://github.com/allen0099/FastAPI-CacheX/blob/master/examples/http_cache.py):
+
 <!-- fmt:off -->
 ```python
 --8<-- "examples/http_cache.py:routes"
@@ -910,8 +912,8 @@ keys from a `key_builder` that does not use `build_cache_key()`.
 > the routes on an internal-only app. For a local or test app that should stay
 > open, pass `dependencies=[]` to opt out deliberately.
 
-The runnable example guards them with a token from an environment variable, and
-keeps them closed while the variable is unset:
+[`examples/http_cache.py`](https://github.com/allen0099/FastAPI-CacheX/blob/master/examples/http_cache.py) guards them with a token from an environment variable,
+and keeps them closed while the variable is unset:
 
 <!-- fmt:off -->
 ```python

docs/JWT_CLAIMS.md

@@ -178,7 +178,7 @@ await session_manager.delete_session("session-abc123")
 
 If your application needs additional JWT claims, write your own serializer and pass an instance to `SessionManager` through its `token_serializer` argument. Any object with `to_string(token) -> str` and `from_string(token_str) -> SessionToken` methods (the `TokenSerializer` protocol) will do; `from_string()` should raise `ValueError` for invalid tokens, which `SessionManager` converts into `SessionTokenError`.
 
-The base class below does what the built-in `JWTTokenSerializer` does and leaves two hooks for the extra claims. It keeps its own copy of the settings, read from the public `SessionConfig` fields, instead of reaching into `JWTTokenSerializer`'s private attributes, which may change in any release. Like the built-in serializer, it follows `token.expires_at` in `to_string()`, so `exp` keeps up with sliding expiration.
+The base class below does what the built-in `JWTTokenSerializer` does and leaves two hooks for the extra claims. It keeps its own copy of the settings, read from the public `SessionConfig` fields, instead of reaching into `JWTTokenSerializer`'s private attributes, which may change in any release. Like the built-in serializer, it follows `token.expires_at` in `to_string()`, so `exp` keeps up with sliding expiration. It is the `serializer` part of [`examples/session_jwt_claims.py`](https://github.com/allen0099/FastAPI-CacheX/blob/master/examples/session_jwt_claims.py).
 
 <!-- fmt:off -->
 ```python
@@ -211,6 +211,8 @@ class ExtendedJWTSerializer(CustomClaimsJWTSerializer):
 
 ### Example 2: Adding Multi-Tenant Custom Claims
 
+From [`examples/session_jwt_claims.py`](https://github.com/allen0099/FastAPI-CacheX/blob/master/examples/session_jwt_claims.py):
+
 <!-- fmt:off -->
 ```python
 --8<-- "examples/session_jwt_claims.py:multi-tenant"
@@ -221,6 +223,8 @@ class ExtendedJWTSerializer(CustomClaimsJWTSerializer):
 
 #### Option 1: Pass it to `SessionManager` (recommended)
 
+From [`examples/session_jwt_claims.py`](https://github.com/allen0099/FastAPI-CacheX/blob/master/examples/session_jwt_claims.py):
+
 <!-- fmt:off -->
 ```python
 --8<-- "examples/session_jwt_claims.py:setup"

docs/STATE.md

@@ -26,6 +26,8 @@ The quick start below is the complete, runnable [`examples/oauth_state.py`](http
 
 ## Quick start
 
+This is [`examples/oauth_state.py`](https://github.com/allen0099/FastAPI-CacheX/blob/master/examples/oauth_state.py):
+
 <!-- fmt:off -->
 ```python
 --8<-- "examples/oauth_state.py"

i18n/zh-TW/docs/APP_CACHE.md

@@ -44,7 +44,7 @@ await manager.clear_pattern("user:*")  # 比對 "myapp:user:*"
 
 ## 快取一個函式 {#caching-a-function}
 
-`@cached` 對一般函式做的事與 `get_or_set()` 相同，以函式的引數作為鍵，因此載入資料或呼叫其他服務的函式只要寫一次，在任何地方呼叫都會被快取：
+`@cached` 對一般函式做的事與 `get_or_set()` 相同，以函式的引數作為鍵，因此載入資料或呼叫其他服務的函式只要寫一次，在任何地方呼叫都會被快取。以下取自 [`examples/app_cache.py`](https://github.com/allen0099/FastAPI-CacheX/blob/master/examples/app_cache.py)（程式碼註解為英文）：
 
 <!-- fmt:off -->
 ```python

i18n/zh-TW/docs/BACKENDS.md

@@ -146,7 +146,7 @@ BackendProxy.set(backend)
 
 ## 關閉後端 {#closing-a-backend}
 
-每個後端都有 `aclose()`，用來釋放它持有的連線與背景工作。請在關閉應用程式時，於 FastAPI lifespan 的結尾呼叫它：
+每個後端都有 `aclose()`，用來釋放它持有的連線與背景工作。請在關閉應用程式時，於 FastAPI lifespan 的結尾呼叫它，如 [`examples/redis_backend.py`](https://github.com/allen0099/FastAPI-CacheX/blob/master/examples/redis_backend.py) 所示（程式碼註解為英文）：
 
 <!-- fmt:off -->
 ```python

i18n/zh-TW/docs/HTTP_CACHING.md

@@ -6,6 +6,8 @@
 
 ## `@cache` 裝飾器 {#the-cache-decorator}
 
+以下是 [`examples/http_cache.py`](https://github.com/allen0099/FastAPI-CacheX/blob/master/examples/http_cache.py) 的路由（程式碼註解為英文）：
+
 <!-- fmt:off -->
 ```python
 --8<-- "examples/http_cache.py:routes"
@@ -521,7 +523,7 @@ add_routes(
 > [!WARNING]
 > **這些路由本身沒有任何身分驗證。** `include_in_schema=False` 只是讓它們不出現在 OpenAPI 文件中；任何猜到路徑的人都能讀取。它們會暴露整個路由結構（包含查詢字串），設定 `include_content_preview=True` 時還會暴露每個快取回應的開頭。因此 `dependencies` 為必填：請傳入 `dependencies=[Depends(your_auth)]`，或將路由掛載在僅供內部使用的應用程式上。若本機或測試用的應用程式確實要保持開放，請傳入 `dependencies=[]` 明確選擇不設防護。
 
-可執行範例以環境變數中的權杖保護它們，未設定該變數時路由一律拒絕存取：
+[`examples/http_cache.py`](https://github.com/allen0099/FastAPI-CacheX/blob/master/examples/http_cache.py) 以環境變數中的權杖保護它們，未設定該變數時路由一律拒絕存取（程式碼註解為英文）：
 
 <!-- fmt:off -->
 ```python

i18n/zh-TW/docs/JWT_CLAIMS.md

@@ -178,7 +178,7 @@ await session_manager.delete_session("session-abc123")
 
 如果你的應用程式需要額外的 JWT claim，請撰寫自己的序列化器，並透過 `SessionManager` 的 `token_serializer` 參數傳入實例。任何具有 `to_string(token) -> str` 與 `from_string(token_str) -> SessionToken` 方法的物件（即 `TokenSerializer` 協定）都可以；`from_string()` 遇到無效權杖時應拋出 `ValueError`，`SessionManager` 會將它轉換為 `SessionTokenError`。
 
-下面的基底類別做的事與內建的 `JWTTokenSerializer` 相同，並為額外的 claim 留下兩個掛鉤。它從 `SessionConfig` 的公開欄位讀取設定並自行保存，而不是存取 `JWTTokenSerializer` 的私有屬性，因為那些屬性在任何版本都可能改變。它與內建序列化器一樣，在 `to_string()` 中採用 `token.expires_at`，讓 `exp` 持續跟著滑動過期。
+下面的基底類別做的事與內建的 `JWTTokenSerializer` 相同，並為額外的 claim 留下兩個掛鉤。它從 `SessionConfig` 的公開欄位讀取設定並自行保存，而不是存取 `JWTTokenSerializer` 的私有屬性，因為那些屬性在任何版本都可能改變。它與內建序列化器一樣，在 `to_string()` 中採用 `token.expires_at`，讓 `exp` 持續跟著滑動過期。它是 [`examples/session_jwt_claims.py`](https://github.com/allen0099/FastAPI-CacheX/blob/master/examples/session_jwt_claims.py) 的 `serializer` 部分（程式碼註解為英文）。
 
 <!-- fmt:off -->
 ```python
@@ -211,6 +211,8 @@ class ExtendedJWTSerializer(CustomClaimsJWTSerializer):
 
 ### 範例 2：加入多租戶的自訂 claim {#example-2-adding-multi-tenant-custom-claims}
 
+以下取自 [`examples/session_jwt_claims.py`](https://github.com/allen0099/FastAPI-CacheX/blob/master/examples/session_jwt_claims.py)（程式碼註解為英文）：
+
 <!-- fmt:off -->
 ```python
 --8<-- "examples/session_jwt_claims.py:multi-tenant"
@@ -221,6 +223,8 @@ class ExtendedJWTSerializer(CustomClaimsJWTSerializer):
 
 #### 做法 1：傳給 `SessionManager`（建議） {#option-1-pass-it-to-sessionmanager-recommended}
 
+以下取自 [`examples/session_jwt_claims.py`](https://github.com/allen0099/FastAPI-CacheX/blob/master/examples/session_jwt_claims.py)（程式碼註解為英文）：
+
 <!-- fmt:off -->
 ```python
 --8<-- "examples/session_jwt_claims.py:setup"

i18n/zh-TW/docs/STATE.md

@@ -15,6 +15,8 @@ State 與 HTTP 快取存放在同一個後端，但使用自己的鍵前綴（
 
 ## 快速開始 {#quick-start}
 
+以下是 [`examples/oauth_state.py`](https://github.com/allen0099/FastAPI-CacheX/blob/master/examples/oauth_state.py)（程式碼註解為英文）：
+
 <!-- fmt:off -->
 ```python
 --8<-- "examples/oauth_state.py"