obsidian-pub

安装与使用

npm install
npm run build
npm link

推荐先写入配置文件，然后直接运行：

obsidian-pub

也可以每次通过命令行参数显式指定：

obsidian-pub --directory /path/to/vault --index /path/to/index.md --sync /path/to/content

配置文件（推荐）

CLI 启动时会从本地配置文件读取默认参数，因此不需要每次都输入 directory、index、sync。最简单的情况下，把这些参数预设到配置文件后，直接执行 obsidian-pub 即可。

• 路径：~/.config/obs-scanner/config.yaml
• 字段：directory、index、sync、asset_root

示例：

directory: /path/to/vault
index: /path/to/index.md
sync: /path/to/content
asset_root: /path/to/vault/assets

asset_root 是图片资源查找根目录，可选。未配置时默认使用 directory。同步时会从已发布的 Markdown 文件中提取 ![[relative path to file.jpg|100*100]] 这类图片 Wiki Link，并递归查找匹配图片，复制到 <sync>/internal-static。

命令行参数优先于配置文件，所以可以只临时覆盖某个参数：

obsidian-pub --sync /tmp/content

若配置文件不存在，CLI 会提示：

配置文件 /Users/yourname/.config/obs-scanner/config.yaml 不存在

路径支持使用 ~/ 作为用户目录的简写，CLI 会自动展开为绝对路径。

发布到 npm

项目提供了一个轻量发布脚本：

npm run release:npm

脚本会按顺序执行这些检查和动作：

• 校验当前 npm registry 必须是官方源 https://registry.npmjs.org/
• 校验当前分支必须是 main
• 校验 git 工作区必须干净
• 校验当前 npm login 状态有效
• 执行 npm test
• 执行 npm pack --dry-run
• 最后执行 npm publish

如果需要临时改发布分支或目标源，可以通过环境变量覆盖：

EXPECTED_BRANCH=release EXPECTED_REGISTRY=https://registry.npmjs.org/ npm run release:npm

发布脚本默认使用项目内 .npm-cache，避免本机 ~/.npm 权限问题影响发布流程。也可以临时覆盖：

NPM_CACHE_DIR=/tmp/obsidian-pub-npm-cache npm run release:npm

如果账号开启了发布 2FA，可以在仓库根目录创建不会被 git 跟踪的 .npmrc.publish：

registry=https://registry.npmjs.org/
//registry.npmjs.org/:_authToken=${NPM_TOKEN}

实际使用时把 ${NPM_TOKEN} 替换为带发布权限且允许绕过 2FA 的 npm token。发布脚本检测到 .npmrc.publish 后会自动使用它。也可以不落盘，临时通过环境变量发布：

NPM_TOKEN=xxxxx npm run release:npm

npm 包本身只发布运行所需内容和少量说明文件，当前白名单包括：

• dist/
• README.md
• config.sample.yaml

其中 build 只生成可发布的运行时代码；测试使用单独的 build:test，避免把测试产物混入最终 npm 包。