快速开始

准备环境、运行站点，将第一篇文章导入为可预览的草稿。

准备环境

在你有访问权限的 InkStack 仓库副本中运行命令。当前固定环境为 Node 22.23.3、pnpm 11.1.1、Typst 0.15.0。真实 PDF 验收还需要 Poppler 的 pdffonts，以及 Noto Serif CJK SC、Noto Sans CJK SC、DejaVu Sans Mono 字体。

pnpm install --frozen-lockfile
export PATH="$PWD/node_modules/.bin:$PATH"
inkstack doctor

版本不符合时先修正环境。不要通过更新锁文件或忽略编译器检查来绕过版本要求。源码仓库为私有时，访问本站不自动授予仓库权限。

export 只在当前终端启用项目里的专用命令，不安装全局包或修改 shell 配置。没有启用时，在仓库根目录使用 pnpm inkstack <命令>，例如 pnpm inkstack build；两种写法调用同一个 CLI。CLI 可从项目子目录运行；项目之外使用 inkstack --root /path/to/InkStack <命令>。没有公开 npm 安装包，不要使用未经核验的 npx inkstack。

常用命令

命令	用途
`inkstack new`	逐步新建 Markdown、MDX 或 Typst 草稿
`inkstack import article.md`	导入文件、解析并迁移图片，确认后写入草稿
`inkstack dev`	本地开发，增量 Typst 与 Markdown / MDX 热更新
`inkstack build`	正式构建、搜索索引、资源同步与产物摘要验收
`inkstack preview`	自动构建并预览正式产物，Ctrl+C 结束
`inkstack check`	内容、Lint、类型与单元测试，无需已有构建
`inkstack publish <slug>`	本地发布草稿；`--submit` 明确提交 PR
`inkstack doctor`	只读检查环境；`--publish` 追加 GitHub 登录检查

每条命令可通过 inkstack <命令> --help 查看参数。旧 pnpm post:new、pnpm post:import、pnpm post:publish 仍兼容，不再作为新用户的主要入口。

启动本地站点

inkstack dev

使用终端打印的 Local 地址打开页面。项目入口会先构建上游包、编译 Typst，并维护隔离的草稿预览；Markdown 与 MDX 修改由 Astro HMR 处理。不要以直接运行 astro dev 代替此入口。

导入已有文件

inkstack import /path/to/article.md
# 或导入 Typst，显式开启 PDF
inkstack import /path/to/article.typ --pdf

向导会询问 URL slug、标题与摘要，展示图片和依赖迁移计划，再询问是否写入。默认创建草稿，原文件保持不变；取消或预检失败不会创建文章。

第一次可以先检查，不写入：

inkstack import /path/to/article.md \
  --slug first-post --description "第一篇文章的摘要" --dry-run

资源位于文件目录之外时，需要明确指定允许根，详见图片与依赖迁移。外部文件导入不接受 MDX，MDX 应在仓库内创建和审查。

在仓库内新建

inkstack new --format md --slug first-post --title "第一篇文章"
inkstack new --format mdx --slug component-post --title "组件文章"
inkstack new --format typst --slug typeset-post --title "排版文章" --pdf

编辑生成目录里的正文、元数据和 assets/。Markdown/MDX 元数据位于 YAML front matter，Typst 位于 post.yaml。不要同时在同一 Markdown 文章目录放 index.md 与 index.mdx。

验证与发布

inkstack check
inkstack preview

搜索需要完整构建后的 Pagefind 索引；开发模式不会使用可能陈旧的搜索结果。

只要生成产物时运行 inkstack build；只检查文章可用 inkstack check --content-only；复用已有产物预览可用 inkstack preview --no-build，它仍校验产物摘要，但不声称反映最新源码。完整本地验收使用 inkstack check --full，会追加构建、Astro 诊断和浏览器测试，需要预先安装 Playwright 浏览器。它不替代 CI 的真实发布矩阵、安全和部署门禁。