docs: order the site navigation by how a developer adopts the library

README.md

@@ -100,13 +100,13 @@ async def report(cache: AppCache):
 
 ## Documentation
 
+- [Migrating to 0.4.0](https://fastapi-cachex.readthedocs.io/en/latest/MIGRATING_0_4/) — what 0.4.0 changes and how to act on the 0.3.9 warnings now
 - [HTTP caching](https://fastapi-cachex.readthedocs.io/en/latest/HTTP_CACHING/) — the `@cache` decorator, Cache-Control directives, cache keys, invalidation and monitoring routes
-- [Cache flow](https://fastapi-cachex.readthedocs.io/en/latest/CACHE_FLOW/) — what happens inside a cached request
 - [Application cache](https://fastapi-cachex.readthedocs.io/en/latest/APP_CACHE/) — `CacheManager`
 - [Backends](https://fastapi-cachex.readthedocs.io/en/latest/BACKENDS/) — choosing and configuring a backend, atomic primitives
-- [Session management](https://fastapi-cachex.readthedocs.io/en/latest/SESSION/) and [JWT claims](https://fastapi-cachex.readthedocs.io/en/latest/JWT_CLAIMS/)
-- [OAuth state](https://fastapi-cachex.readthedocs.io/en/latest/STATE/) — one-shot OAuth/CSRF state tokens
 - [Distributed lock](https://fastapi-cachex.readthedocs.io/en/latest/LOCK/) — `CacheLock` for multi-process mutual exclusion
+- [Session management](https://fastapi-cachex.readthedocs.io/en/latest/SESSION/), [OAuth state](https://fastapi-cachex.readthedocs.io/en/latest/STATE/) (one-shot OAuth/CSRF state tokens) and [JWT claims](https://fastapi-cachex.readthedocs.io/en/latest/JWT_CLAIMS/)
+- [Cache flow](https://fastapi-cachex.readthedocs.io/en/latest/CACHE_FLOW/) — what happens inside a cached request
 - [Runnable examples](https://github.com/allen0099/FastAPI-CacheX/tree/master/examples) — one complete app per feature, each covered by the test suite
 - [API reference](https://fastapi-cachex.readthedocs.io/en/latest/api/http-caching/)
 - [Development guide](https://fastapi-cachex.readthedocs.io/en/latest/DEVELOPMENT/) and [contributing](https://fastapi-cachex.readthedocs.io/en/latest/CONTRIBUTING/) · [Security policy](https://github.com/allen0099/FastAPI-CacheX/blob/master/SECURITY.md) — report vulnerabilities privately, not in public issues

i18n/zh-TW/docs/index.md

@@ -89,13 +89,13 @@ async def report(cache: AppCache):
 
 ## 文件 {#documentation}
 
+- [遷移至 0.4.0](MIGRATING_0_4.md)：0.4.0 的變更，以及現在如何處理 0.3.9 的警告
 - [HTTP 快取](HTTP_CACHING.md)：`@cache` 裝飾器、Cache-Control 指令、快取鍵、快取失效與監控路由
-- [快取流程](CACHE_FLOW.md)：快取請求內部的處理流程
 - [應用層快取](APP_CACHE.md)：`CacheManager`
 - [後端](BACKENDS.md)：選擇與設定後端、原子操作的基本功能
-- [Session 管理](SESSION.md)與 [JWT claims](JWT_CLAIMS.md)
-- [OAuth state](STATE.md)：一次性的 OAuth / CSRF state 權杖
 - [分散式鎖](LOCK.md)：以 `CacheLock` 在多個行程之間互斥
+- [Session 管理](SESSION.md)、[OAuth state](STATE.md)（一次性的 OAuth / CSRF state 權杖）與 [JWT claims](JWT_CLAIMS.md)
+- [快取流程](CACHE_FLOW.md)：快取請求內部的處理流程
 - [可執行範例](https://github.com/allen0099/FastAPI-CacheX/tree/master/examples)（英文）：每個功能一個完整的應用程式，皆由測試套件涵蓋
 - [API 參考](https://fastapi-cachex.readthedocs.io/en/latest/api/http-caching/)（英文）
 - [開發指南](https://fastapi-cachex.readthedocs.io/en/latest/DEVELOPMENT/)（英文）與[貢獻指南](CONTRIBUTING.md) · [安全性政策](https://github.com/allen0099/FastAPI-CacheX/blob/master/SECURITY.md)（英文）：請私下回報漏洞，不要開公開 issue

zensical.toml

@@ -18,21 +18,25 @@ site_dir = "site"
 
 nav = [
   { "Home" = "index.md" },
-  { "Guides" = [
+  { "Migrating to 0.4.0" = "MIGRATING_0_4.md" },
+  { "Caching" = [
     { "HTTP caching" = "HTTP_CACHING.md" },
-    { "Cache flow" = "CACHE_FLOW.md" },
     { "Application cache" = "APP_CACHE.md" },
     { "Backends" = "BACKENDS.md" },
+    { "Distributed lock" = "LOCK.md" },
+  ] },
+  { "Sessions and sign-in" = [
     { "Session management" = "SESSION.md" },
+    { "OAuth state" = "STATE.md" },
     { "JWT claims" = "JWT_CLAIMS.md" },
-    { "State management" = "STATE.md" },
-    { "Distributed lock" = "LOCK.md" },
   ] },
-  { "Migrating to 0.4.0" = "MIGRATING_0_4.md" },
+  { "Under the hood" = [
+    { "Cache flow" = "CACHE_FLOW.md" },
+  ] },
   { "API reference" = [
     { "HTTP caching" = "api/http-caching.md" },
-    { "Backends" = "api/backends.md" },
     { "CacheManager" = "api/cache-manager.md" },
+    { "Backends" = "api/backends.md" },
     { "CacheLock" = "api/lock.md" },
     { "Session" = "api/session.md" },
     { "State" = "api/state.md" },

zensical.zh-TW.toml

@@ -22,17 +22,21 @@ site_dir = "site-zh-TW"
 # to the local file once its translation lands.
 nav = [
   { "首頁" = "index.md" },
-  { "指南" = [
+  { "遷移至 0.4.0" = "MIGRATING_0_4.md" },
+  { "快取" = [
     { "HTTP 快取" = "HTTP_CACHING.md" },
-    { "快取流程" = "CACHE_FLOW.md" },
     { "應用層快取" = "APP_CACHE.md" },
     { "後端" = "BACKENDS.md" },
+    { "分散式鎖" = "LOCK.md" },
+  ] },
+  { "Session 與登入" = [
     { "Session 管理" = "SESSION.md" },
-    { "JWT claims" = "JWT_CLAIMS.md" },
     { "OAuth state" = "STATE.md" },
-    { "分散式鎖" = "LOCK.md" },
+    { "JWT claims" = "JWT_CLAIMS.md" },
+  ] },
+  { "深入了解" = [
+    { "快取流程" = "CACHE_FLOW.md" },
   ] },
-  { "遷移至 0.4.0" = "MIGRATING_0_4.md" },
   { "API 參考（英文）" = "https://fastapi-cachex.readthedocs.io/en/latest/api/http-caching/" },
   { "開發" = [
     { "開發指南（英文）" = "https://fastapi-cachex.readthedocs.io/en/latest/DEVELOPMENT/" },