@qnroa/qtype 0.0.4 → 0.0.6

package/CHANGELOG.md

@@ -13,6 +13,53 @@ 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
+
+- **Mermaid pre-render no longer fails under `npx` / hosted CI.**
+  `mermaidPrerender.init()` now uses `createRequire(import.meta.url).resolve('mermaid/…')`
+  to locate the mermaid ESM, so Node's own module resolver walks the
+  actual `node_modules` chain regardless of where qtype was installed
+  — user repo, npx cache, Cloudflare Pages build root, monorepo hoist.
+  The previous two hard-coded lookup paths remain as fallbacks but
+  are no longer the primary strategy. This fixes the
+  `mermaid ESM not found in node_modules` error on Cloudflare Pages
+  when a deck actually contains ` ```mermaid ` code blocks.
+- **`publish build` now copies `material/assets/**`** into
+  `dist/material/assets/` verbatim. Previously the CLI only walked
+  `.md` files, so any image the cards referenced via
+  `![](/material/assets/…)` returned 404 on the deployed site.
+
 ## [0.0.4] - 2026-08-22
 
 ### Added

package/CHANGELOG.zh.md

@@ -12,6 +12,45 @@ 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
+
+### 修复
+
+- **Mermaid 预渲染在 `npx` / 托管 CI 环境不再失败**。
+  `mermaidPrerender.init()` 改用
+  `createRequire(import.meta.url).resolve('mermaid/…')`,让 Node
+  自己顺着 `node_modules` 链找 mermaid,不管 qtype 是装到用户仓库、
+  npx 缓存、Cloudflare Pages build root 还是 monorepo hoist 都能
+  找到。之前的两条硬编码查找路径保留作为兜底,但不再是主要策略。
+  修复了 deck 里真的有 ` ```mermaid ` 代码块时,Cloudflare Pages 上
+  `mermaid ESM not found in node_modules` 报错。
+- **`publish build` 现在会把 `material/assets/**`** 原样拷进
+  `dist/material/assets/`。之前 CLI 只遍历 `.md` 文件,导致卡片
+  引用的 `![](/material/assets/…)` 图片在部署后 404。
+
 ## [0.0.4] - 2026-08-22
 
 ### 新增

package/dist/cli/commands/publish/build/mermaidPrerender.js

@@ -38,15 +38,37 @@ export class MermaidRenderer {
     pageDark = null;
     pageLight = null;
     async init() {
-        const candidates = [
-            path.resolve(__dirname, '..', '..', '..', '..', '..', 'node_modules', 'mermaid', 'dist', 'mermaid.esm.min.mjs'),
-            path.resolve(process.cwd(), 'node_modules', 'mermaid', 'dist', 'mermaid.esm.min.mjs'),
-        ];
+        // Ask Node's own module resolver where mermaid actually lives. It
+        // walks the `node_modules` chain from this file up, so it works
+        // regardless of where the caller installed qtype:
+        //
+        //   * user repo with `npm install @qnroa/qtype`      → resolves in
+        //                                                     `<user>/node_modules/mermaid`
+        //   * `npx @qnroa/qtype` on any host (Cloudflare,     → resolves in
+        //     Vercel, GitHub Pages) that hoists deps into      the npx cache
+        //     an npx cache
+        //   * monorepo with hoisted deps                     → resolves in
+        //                                                     the hoisted root
+        //
+        // The two hard-coded fallbacks below only fire if Node's resolver
+        // fails entirely (older Node, exotic packaging), which shouldn't
+        // happen in any supported deployment.
         let mermaidEsm = null;
-        for (const c of candidates) {
-            if (fs.existsSync(c)) {
-                mermaidEsm = c;
-                break;
+        try {
+            const { createRequire } = await import('node:module');
+            const req = createRequire(import.meta.url);
+            mermaidEsm = req.resolve('mermaid/dist/mermaid.esm.min.mjs');
+        }
+        catch {
+            const candidates = [
+                path.resolve(__dirname, '..', '..', '..', '..', '..', 'node_modules', 'mermaid', 'dist', 'mermaid.esm.min.mjs'),
+                path.resolve(process.cwd(), 'node_modules', 'mermaid', 'dist', 'mermaid.esm.min.mjs'),
+            ];
+            for (const c of candidates) {
+                if (fs.existsSync(c)) {
+                    mermaidEsm = c;
+                    break;
+                }
             }
         }
         if (!mermaidEsm) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qnroa/qtype",
-  "version": "0.0.4",
+  "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 结构表达