@qnroa/qtype 0.0.5 → 0.0.6

package/CHANGELOG.md

@@ -13,6 +13,35 @@ can land in any minor bump (`0.x.0`).
 
 ## [Unreleased]
 
+## [0.0.6] - 2026-08-24
+
+### Changed
+
+- **`QTYPE.md` template documents nested `material/` folders as
+  first-class.** The template already-existing `walkMaterial` recurses
+  into `material/<category>/<slug>.md`, and `publish build` even uses
+  the first path segment as a fallback `type` when frontmatter omits
+  it — but the previous wording ("flat `material/` + `assets/` only",
+  rule #9) read as a ban on subdirectories, misleading Agent-driven
+  authors into flattening large repos. The template now:
+  - shows both flat and nested placements in the Directory Layout
+    tree, with a one-line note that both are supported and discovery
+    is recursive;
+  - adds a **Grouping by folder (optional)** section covering the
+    recursive-discovery behavior and the first-segment-as-fallback-`type`
+    shortcut (`material/code/hello.md` → `type: code` when frontmatter
+    is silent);
+  - reworks the Naming section to say each path segment (`<slug>`,
+    `<category>`) uses the same kebab-case rules;
+  - rewrites rule #9 to enumerate the allowed root-level directories
+    (`material/`, `material/assets/`, `raw/`) and cross-reference the
+    new subfolder section, replacing the misleading "flat only"
+    phrasing.
+  Applies to both `templates/en/QTYPE.md` and `templates/zh/QTYPE.md`.
+  No runtime code changed; existing repos are unaffected until they
+  regenerate their `QTYPE.md` via `qtype repo new` or copy the new
+  template in.
+
 ## [0.0.5] - 2026-08-22
 
 ### Fixed

package/CHANGELOG.zh.md

@@ -12,6 +12,29 @@ English: [CHANGELOG.md](https://www.npmjs.com/package/@qnroa/qtype?activeTab=cod
 
 ## [Unreleased]
 
+## [0.0.6] - 2026-08-24
+
+### 变更
+
+- **`QTYPE.md` 模板把嵌套 `material/` 子目录写成一等公民**。
+  `walkMaterial` 一直就是递归的,`publish build` 甚至会用首段路径
+  作为 frontmatter 没写 `type` 时的 fallback —— 但之前模板里
+  "flat `material/` + `assets/` only"(规则 #9)的措辞读起来像禁止
+  子目录,把 Agent 驱动的作者误导成"再大的仓库也只能平铺"。这次:
+  - Directory Layout 目录树里同时画出平铺和嵌套两种放法,并加一行
+    "两种都支持,发现是递归的";
+  - 新增 **按分类分子目录(可选)** 小节,说明递归发现行为,以及
+    首段路径当 fallback `type` 的捷径(`material/code/hello.md`
+    在 frontmatter 没 `type` 时被视为 `type: code`);
+  - 命名节改为"每一段路径(`<slug>`、`<category>`)都用同一套
+    kebab-case 规则";
+  - 规则 #9 重写为枚举根目录允许的三个位置(`material/` /
+    `material/assets/` / `raw/`)并 xref 新的子目录小节,替换掉
+    误导性的"平铺"措辞。
+  同步改动 `templates/en/QTYPE.md` 和 `templates/zh/QTYPE.md`。
+  运行时代码没动;老仓库要拿到新文档需要重跑 `qtype repo new`
+  或手动把新模板拷进去。
+
 ## [0.0.5] - 2026-08-22
 
 ### 修复

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qnroa/qtype",
-  "version": "0.0.5",
+  "version": "0.0.6",
   "description": "Turn Markdown notes into typing practice — CLI + review + static-site publisher",
   "keywords": [
     "typing",

package/templates/en/QTYPE.md

@@ -41,7 +41,8 @@ The whole document is organized into four modules: **Concepts / Format / Operati
 ├── qtype.config.json
 ├── material/
 │   ├── .gitkeep
-│   ├── <slug>.md
+│   ├── <slug>.md                    # flat placement — fine
+│   ├── <category>/<slug>.md         # nested placement — also fine
 │   └── assets/<material-slug>/
 └── raw/
     ├── .gitkeep
@@ -49,6 +50,8 @@ The whole document is organized into four modules: **Concepts / Format / Operati
     └── assets/<raw-slug>/
 ```
 
+**Flat and nested placements are both supported.** All `.md` under `material/` are discovered recursively. Choose whichever fits the repo — small repos are usually flat, larger ones group by category folder.
+
 ---
 
 ## Format
@@ -231,11 +234,21 @@ sqrt(pi)
 
 ### Naming
 
-Material files: `material/<slug>.md`
-- kebab-case, ASCII lowercase + hyphens, ≤ 60 chars
+Material files: `material/<slug>.md` — or `material/<category>/<slug>.md` if grouping by folder.
+
+- Each path segment (`<slug>`, `<category>`) uses the same rules: kebab-case, ASCII lowercase + hyphens, ≤ 60 chars
 - Chinese topics: use English translation or pinyin
 - Collision: append `-2` / `-3`
 
+### Grouping by folder (optional)
+
+`material/` may contain category subfolders. Two things to know when you use them:
+
+- **Discovery is recursive.** All `.md` files under `material/` are picked up regardless of depth. Nested folders don't hide their contents.
+- **The first path segment is a fallback `type`.** When a material's frontmatter omits `type`, the first folder name is used instead — e.g. a file at `material/code/hello.md` with no `type:` line is treated as `type: code`. This is a shortcut for repos organized by type folder; explicit `type:` in frontmatter always wins.
+
+Group by folder when the repo has many materials of clearly different subjects (e.g. `skills/`, `experience/`, `projects/`, `code/`). Stay flat when there are only a handful of files — extra folders add friction without payoff.
+
 ### Links
 
 - **Markdown link syntax only**, no Wikilinks
@@ -272,7 +285,7 @@ Ingest, Update, Quiz-gen, Cascade, Check, Level-up — semantics as before. Key
 6. **No Wikilinks**
 7. **No absolute paths**
 8. **Never `git commit` / `push`** — the user commits
-9. **No unspec'd directories** — flat `material/` + `assets/` only
+9. **No unspec'd directories** — only `material/` (may contain category subfolders, see "Grouping by folder"), `material/assets/`, and `raw/` are allowed at the repo root
 10. **Never fabricate IPA / gloss / translation** — leave blank, report in log
 11. **One `type` per material** — no mixing
 12. **No card-level frontmatter** — per-card info lives in markdown structure

package/templates/zh/QTYPE.md

@@ -43,8 +43,9 @@ qtype 是一个以 Markdown 为源、以 OS 键盘（含中文 IME）为输入
 ├── qtype.config.json  # 用户可调设置
 ├── material/          # 你写的素材
 │   ├── .gitkeep
-│   ├── <slug>.md      # 一个素材一个文件
-│   └── assets/        # 素材引用的图片
+│   ├── <slug>.md              # 平铺放法 —— 可以
+│   ├── <category>/<slug>.md   # 按分类嵌套 —— 也可以
+│   └── assets/                # 素材引用的图片
 │       └── <material-slug>/
 └── raw/               # （可选）用户扔进来的原始材料
     ├── .gitkeep
@@ -52,6 +53,8 @@ qtype 是一个以 Markdown 为源、以 OS 键盘（含中文 IME）为输入
     └── assets/
 ```
 
+**平铺和嵌套都支持**：`material/` 下所有 `.md` 会被递归发现，深几层都能扫到。文件少时平铺就够了，文件多时按分类开子目录更清爽。
+
 ---
 
 ## 格式
@@ -259,12 +262,21 @@ sqrt(pi)
 
 ### 命名
 
-**素材文件名**：`material/<slug>.md`
+**素材文件名**：`material/<slug>.md` —— 或者按分类嵌套时 `material/<category>/<slug>.md`。
 
-- `<slug>`：主题的 kebab-case，小写，英文字母和短横线，最长 60 字符
+- 每一段路径（`<slug>`、`<category>`）都用同一套规则：kebab-case，小写，英文字母和短横线，最长 60 字符
 - 中文主题用英译或拼音
 - 同名冲突：末尾追加 `-2` / `-3`
 
+### 按分类分子目录（可选）
+
+`material/` 下可以开分类子目录。启用时需要知道两件事：
+
+- **发现是递归的**。`material/` 下所有 `.md` 文件不论深度都会被扫到，嵌套目录不会被跳过
+- **首段路径充当 `type` 的 fallback**。如果一个 material 的 frontmatter 没有写 `type`，第一段目录名会被当作 type —— 比如 `material/code/hello.md` 不写 `type:` 会被视为 `type: code`。这是给"按 type 分目录"的仓库的捷径；只要 frontmatter 里显式写了 `type`，永远以 frontmatter 为准。
+
+素材数量多、主题差异明显时（比如 `skills/` / `experience/` / `projects/` / `code/`）用子目录归类；素材只有几个时保持平铺就好，多开一层目录只会增摩擦不增收益。
+
 ### 链接
 
 - **只用 Markdown link**，不用 Wikilink
@@ -330,7 +342,7 @@ updated: YYYY-MM-DD
 6. **不用 Wikilink**
 7. **不绝对路径**
 8. **不主动 git commit / push**
-9. **不建规则外的目录**
+9. **不建规则外的目录**：仓库根下只允许 `material/`（内部可按分类开子目录，见"按分类分子目录"）、`material/assets/`、`raw/`
 10. **不凭空造 IPA / 释义 / 翻译**：不确定的宁可空着
 11. **一个 material 只有一个 type**：不能混
 12. **没有 card-level frontmatter**：所有 per-card 信息都用 markdown 结构表达