Back to Details

indexion-readme

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

indexion readme — README Construction

indexion README — README构建

Build project READMEs from templates, doc comments, hand-written prose, and per-package READMEs. This skill covers the construction side: scaffolding, generating, planning, assembling, and verifying. For evaluating existing documentation, see 
indexion-documentation
.
从模板、文档注释、手写文本以及每个包的README构建项目README。本技能涵盖构建环节：脚手架搭建、生成、规划、组装和验证。如需评估现有文档，请查看
indexion-documentation
。

Where things live

文件位置说明

The conventions vary by project; check what actually exists before editing:
AssetLocation patterns seen
Config
doc.json
(repo root) or 
.indexion/readme/doc.json
Per-package template
docs/templates/readme.md
(no SoT constant; declared via 
--template
)
Static prose
docs/intro.md
, 
docs/installation.md
, 
docs/license.md
, …
Per-package READMEs
cmd/<name>/README.md
, 
src/<name>/README.md
Assembled root READMEusually 
README.md
. Some projects use a 
.mbt.md
suffix so the file is also a MoonBit doctest module — when so, 
README.md
is a symlink to 
README.mbt.md
.
.indexion.toml
[doc] config_path
/ 
per_package
auto-load doc.json
The first thing to check is 
git diff
/ 
ls -la
for: a symlink on 
README.md
, a 
doc.json
(at root or under 
.indexion/readme/
), and 
.indexion.toml
. The presence of these tells you whether the README is hand-maintained, build-assembled, or a hybrid.
不同项目的约定有所不同，编辑前请先确认实际存在的文件：
资源常见位置模式
配置
doc.json
（仓库根目录）或 
.indexion/readme/doc.json
每个包的模板
docs/templates/readme.md
（无单一来源常量；通过
--template
声明）
静态文本
docs/intro.md
, 
docs/installation.md
, 
docs/license.md
, …
每个包的README
cmd/<name>/README.md
, 
src/<name>/README.md
组装后的根目录README通常为
README.md
。部分项目使用
.mbt.md
后缀，使文件同时作为MoonBit文档测试模块——此时
README.md
是指向
README.mbt.md
的符号链接。
.indexion.toml
[doc] config_path
/ 
per_package
自动加载doc.json
首先需要检查的是通过
git diff
/ 
ls -la
查看：
README.md
是否为符号链接、是否存在
doc.json
（根目录或
.indexion/readme/
下）以及
.indexion.toml
。这些文件的存在情况可以告诉你README是手动维护、构建组装还是混合模式。

Workflow overview

工作流程概述

doc init                      → .indexion/readme/template.md + doc.json (greenfield)
edit doc.json + docs/*.md     → declare sources of truth
doc readme --per-package      → cmd/<pkg>/README.md (API skeletons; non-overwriting)
hand-write each per-package README's Overview / Usage / Options / Examples
doc readme --config           → assembled root README
plan drift <prev> <new>       → verify the assembled output (or hand-edit) is purely additive
doc init                      → .indexion/readme/template.md + doc.json（新项目初始化）
edit doc.json + docs/*.md     → 声明信息来源
doc readme --per-package      → cmd/<pkg>/README.md（API框架；不会覆盖现有文件）
hand-write each per-package README's Overview / Usage / Options / Examples
doc readme --config           → 组装根目录README
plan drift <prev> <new>       → 验证组装输出（或手动编辑）仅为增量内容

Step 1: Initialize (greenfield only)

步骤1：初始化（仅适用于新项目）

bash
indexion doc init <project-dir>
Creates 
.indexion/readme/template.md
+ 
.indexion/readme/doc.json
. Skip this step on a project that already has 
doc.json
or 
.indexion.toml
pointing at one.
bash
indexion doc init <project-dir>
创建
.indexion/readme/template.md
+ 
.indexion/readme/doc.json
。如果项目已存在
doc.json
或
.indexion.toml
指向该文件，请跳过此步骤。

Step 2: Configure doc.json

步骤2：配置doc.json

json
{
  "$schema": "./schemas/doc-config.schema.json",
  "version": "1.0",
  "spec": "moonbit",
  "output": { "format": "markdown", "filename": "README.md" },
  "packages": [
    {
      "path": "cmd/<name>",
      "title": "<command name>",
      "include_in_root": true,
      "sections": ["overview", "usage"]
    }
    // …one entry per package that should appear in the assembled root README
  ],
  "root": {
    "output": "README.md",
    "sections": [
      { "type": "static",   "file": "docs/intro.md" },
      { "type": "toc",      "title": "Commands" },
      { "type": "packages", "filter": "cmd/**" },
      { "type": "static",   "file": "docs/installation.md" },
      { "type": "static",   "file": "docs/license.md" }
    ]
  }
}
Root section types:
  • static
    — include a markdown file verbatim
  • toc
    — insert a table-of-contents heading
  • packages
    — pull in entries from the 
    packages
    array, filtered by glob
Package fields:
  • include_in_root
    — whether to include in the assembled root README
  • sections
    — README headings to extract; honored by per-package extraction flows. Note that 
    { "type": "packages" }
    in the root currently emits a table of package links, not the rich Overview/Usage expansion implied by per-package 
    sections
    . See "Known limitation" below.
json
{
  "$schema": "./schemas/doc-config.schema.json",
  "version": "1.0",
  "spec": "moonbit",
  "output": { "format": "markdown", "filename": "README.md" },
  "packages": [
    {
      "path": "cmd/<name>",
      "title": "<command name>",
      "include_in_root": true,
      "sections": ["overview", "usage"]
    }
    // …每个应出现在组装后的根目录README中的包对应一个条目
  ],
  "root": {
    "output": "README.md",
    "sections": [
      { "type": "static",   "file": "docs/intro.md" },
      { "type": "toc",      "title": "Commands" },
      { "type": "packages", "filter": "cmd/**" },
      { "type": "static",   "file": "docs/installation.md" },
      { "type": "static",   "file": "docs/license.md" }
    ]
  }
}
根目录章节类型：
  • static
    — 直接包含指定markdown文件的内容
  • toc
    — 插入目录标题
  • packages
    — 从
    packages
    数组中提取条目，通过通配符过滤
包字段说明：
  • include_in_root
    — 是否包含在组装后的根目录README中
  • sections
    — 要提取的README标题；会被每个包的提取流程遵循。注意根目录中的
    { "type": "packages" }
    当前仅生成一个包链接表格，并非每个包
    sections
    所暗示的详细Overview/Usage扩展内容。请查看下方“已知限制”。

Step 3: Generate per-package READMEs

步骤3：生成每个包的README

bash
indexion doc readme --per-package src/ cmd/
Generates 
README.md
in each package directory that doesn't already have one. Non-overwriting — existing per-package READMEs are left alone.
The skeleton is API-only (extracted from 
///
doc comments via KGF). Treat it as a starting point and hand-write the prose sections (Overview, Usage, Options, Examples) afterwards.
bash
undefined
bash
indexion doc readme --per-package src/ cmd/
在每个尚未拥有README的包目录中生成
README.md
。不会覆盖现有文件——已存在的每个包的README将保持不变。
生成的框架仅包含API内容（通过KGF从
///
文档注释提取）。请将其作为起点，后续手动编写文本章节（概述、用法、选项、示例）。
bash
undefined

Single package to stdout

将单个包的README输出到标准输出

indexion doc readme src/kgf/lexer/
indexion doc readme src/kgf/lexer/

Single package to a file

将单个包的README输出到文件

indexion doc readme -o=README.md src/kgf/lexer/

**Note on side effects**: `doc readme --template=<t> <paths...>` (the template-based mode below) walks the given paths and **auto-creates** per-package READMEs for any package that lacks one — even without `--per-package`. If you run it on a broad path (`cmd/`, `src/`), expect new files in unrelated packages. Run with a narrow path or grep `git status` afterwards to clean up unintended creations.
indexion doc readme -o=README.md src/kgf/lexer/

**副作用说明**：`doc readme --template=<t> <paths...>`（下方的模板模式）会遍历指定路径，并**自动创建**所有缺少README的包的README——即使未使用`--per-package`参数。如果在宽泛路径（如`cmd/`, `src/`）上运行该命令，可能会在无关包中创建新文件。请使用窄路径运行，或在运行后通过`git status`检查并清理意外创建的文件。

Step 4: Write static content

步骤4：编写静态内容

Create 
docs/intro.md
, 
docs/installation.md
, etc. — whatever your 
root.sections
references. These are the hand-written prose; the assembler pulls them in verbatim.
创建
docs/intro.md
, 
docs/installation.md
等文件——即
root.sections
中引用的所有文件。这些是手写文本，组装器会直接将其内容纳入。

Step 5: Generate writing plans (optional)

步骤5：生成写作计划（可选）

bash
indexion plan readme --template=docs/templates/readme.md --plans-dir=.indexion/plans src/
Emits per-section writing tasks for manual or LLM-assisted authoring.
bash
indexion plan readme --template=docs/templates/readme.md --plans-dir=.indexion/plans src/
输出每个章节的写作任务，用于手动或LLM辅助创作。

Step 6: Assemble the README

步骤6：组装README

bash
undefined
bash
undefined

Config-driven (preferred; doc.json controls layout and packages list)

配置驱动（推荐；doc.json控制布局和包列表）

indexion doc readme --config=doc.json
indexion doc readme --config=doc.json

Template-driven (alternative; {{include:…}} and {{packages}} placeholders)

模板驱动（替代方案；使用{{include:…}}和{{packages}}占位符）

indexion doc readme --template=docs/templates/readme.md -o=README.md cmd/

The config path can live at repo root or under `.indexion/readme/`. With `.indexion.toml`'s `[doc] config_path = "…"`, the `--config=` flag becomes optional.
indexion doc readme --template=docs/templates/readme.md -o=README.md cmd/

配置文件可位于仓库根目录或`.indexion/readme/`下。如果`.indexion.toml`中设置了`[doc] config_path = "…"`，则`--config=`参数为可选。

Step 7: Verify with 
plan drift

步骤7：使用
plan drift
验证

After regeneration or any hand-edit of the root README, verify the change is purely additive (no silent deletions, no reflowing of unrelated sections):
bash
undefined
在重新生成或手动编辑根目录README后，验证更改仅为增量内容（无静默删除、无无关章节的重排）：
bash
undefined

Snapshot the previous version

保存之前版本的快照

git show HEAD:README.md > /tmp/README.before.md
git show HEAD:README.md > /tmp/README.before.md

Compare against the new version

与新版本对比

indexion plan drift --top=20 /tmp/README.before.md README.md

What to look for in the output:
- `Drift terms in /tmp/README.before.md (missing on the other side): (none)` — nothing was removed
- `Drift terms in README.md (missing on the other side): …` — exactly the new vocabulary you intended to add (command names, new flags, new concepts)
- `Cosine similarity` near 1.0 for a small additive change; substantially lower if you reshaped a section

For CI integration:

```bash
indexion plan drift --vocab-threshold=0.05 /tmp/README.before.md README.md
indexion plan drift --top=20 /tmp/README.before.md README.md

输出内容需关注：
- `Drift terms in /tmp/README.before.md (missing on the other side): (none)` — 未删除任何内容
- `Drift terms in README.md (missing on the other side): …` — 仅添加了你预期的新词汇（命令名称、新标志、新概念）
- 对于小的增量更改，`Cosine similarity`接近1.0；如果重排了章节，则相似度会显著降低

用于CI集成：

```bash
indexion plan drift --vocab-threshold=0.05 /tmp/README.before.md README.md

exits 1 if cosine_distance > 0.05 — useful as a guard against accidental large rewrites

如果余弦距离>0.05则返回1——可作为防止意外大范围重写的防护措施


This same workflow applies to translated README pairs (`README.md` ↔ `README-ja.md`): cross-lingual drift detection works natively because vocab sub-tokenization delegates to the natural-language KGFs in `kgfs/natural/`.

此工作流程同样适用于翻译后的README对（`README.md` ↔ `README-ja.md`）：跨语言漂移检测原生支持，因为词汇子分词由`kgfs/natural/`中的自然语言KGF处理。

Template syntax

模板语法

The template file supports 
{{placeholder}}
substitution:
PlaceholderExpansion
{{include:path}}
Contents of the file (relative to project root)
{{packages}}
All discovered packages (filtered by CLI 
--include
/ 
--exclude
)
{{module_doc}}
Module-level documentation only
模板文件支持
{{placeholder}}
替换：
占位符扩展内容
{{include:path}}
指定文件的内容（相对于项目根目录）
{{packages}}
所有发现的包（通过CLI的
--include
/ 
--exclude
过滤）
{{module_doc}}
仅模块级文档

.indexion.toml integration

.indexion.toml集成

toml
[doc]
config_path = "doc.json"   # auto-loads doc.json without --config
per_package = true         # makes `doc readme <path>` default to --per-package
Explicit 
--config=…
always takes priority.
toml
[doc]
config_path = "doc.json"   # 自动加载doc.json，无需使用--config参数
per_package = true         # 使`doc readme <path>`默认启用--per-package
显式的
--config=…
参数始终优先。

Known limitation: 
packages
root section produces a table, not rich expansion

已知限制：
packages
根目录章节仅生成表格，不支持详细扩展

The 
doc-config.schema.json
permits 
sections: ["overview", "usage", …]
on each 
packageEntry
, but the current 
doc readme --config
implementation does not expand those sections inline when emitting 
{ "type": "packages" }
in the root. The output is a markdown table of package links with empty descriptions.
Two practical consequences:
  1. If the project's checked-in root README has rich per-command Overview / Usage paragraphs, they were not produced by 
    doc readme --config
    as it stands now. They are hand-maintained. Diff 
    doc readme --config -o=/tmp/regen.md
    against the checked-in README to see how much of it is hand-curated; very large diffs mean the README is mostly hand-maintained.
  2. For new commands, you currently need to also hand-edit the rich section into the assembled README, in addition to adding the package entry to 
    doc.json
    and writing the per-package README. Use the 
    plan drift
    verification above to confirm the hand-edit only adds, never removes.
If you fix this limitation (so 
{ "type": "packages" }
honors per-entry 
sections
), update this skill to remove this section.
doc-config.schema.json
允许在每个
packageEntry
上设置
sections: ["overview", "usage", …]
，但当前
doc readme --config
的实现在根目录中输出
{ "type": "packages" }
时，不会将这些章节内容内联扩展。输出结果是一个包含包链接的markdown表格，描述为空。
实际影响如下：
  1. 如果项目已提交的根目录README包含详细的每个命令的概述/用法段落，那么这些内容并非由当前的
    doc readme --config
    生成，而是手动维护的。对比
    doc readme --config -o=/tmp/regen.md
    和已提交的README，查看手动维护的内容占比；如果差异很大，说明README主要是手动维护的。
  2. 对于新命令，除了在
    doc.json
    中添加包条目并编写每个包的README外，你目前还需要手动编辑组装后的README，添加详细章节。使用上述
    plan drift
    验证来确认手动编辑仅添加内容，未删除任何内容。
如果修复了此限制（使
{ "type": "packages" }
支持每个条目的
sections
），请更新本技能以移除本节内容。

Common pitfalls

常见陷阱

"doc readme --per-package generated nothing"
  • All packages already have READMEs. The command only creates new files, never overwrites. Delete existing READMEs first to regenerate.
"doc readme --template … on 
cmd/
created READMEs in packages I didn't touch"
  • Template mode auto-generates missing per-package READMEs as a side effect. Either pass a narrow path, or revert unintended creations from 
    git status
    .
"Auto-generated per-package READMEs are just API listings"
  • By design. Hand-write Overview, Usage, Options, Examples. For CLI commands, the authoritative behavior comes from 
    indexion <command> --help
    .
"My hand-edit to README.md will be wiped out by 
doc readme --config
"
  • It will if the assembler ever produces the rich shape (see "Known limitation"). Until then, the assembler produces a strict subset (the table) and your hand-edits to the rich sections survive. Always run the 
    plan drift
    cross-check to be sure.
"README.md edit destroyed unrelated sections"
  • Run 
    plan drift HEAD:README.md README.md
    and look at the "missing on the other side" output for the previous version. If it lists anything other than 
    (none)
    , you removed content.
"doc readme --per-package未生成任何内容"
  • 所有包都已存在README。该命令仅创建新文件，从不覆盖。如需重新生成，请先删除现有README。
"在
cmd/
上运行
doc readme --template …
在我未修改的包中创建了README"
  • 模板模式会自动生成缺失的每个包的README作为副作用。请使用窄路径运行，或从
    git status
    中恢复意外创建的文件。
"自动生成的每个包的README仅包含API列表"
  • 这是设计如此。请手动编写概述、用法、选项、示例。对于CLI命令，权威行为来自
    indexion <command> --help
    。
"我对README.md的手动编辑会被
doc readme --config
覆盖"
  • 如果组装器能够生成详细内容（见“已知限制”），则会被覆盖。在此之前，组装器仅生成严格的子集（表格），你对详细章节的手动编辑会保留。请始终运行
    plan drift
    交叉检查以确保安全。
"编辑README.md破坏了无关章节"
  • 运行
    plan drift HEAD:README.md README.md
    ，查看旧版本的“missing on the other side”输出。如果除了
    (none)
    之外还有其他内容，说明你删除了部分内容。