Skip to content

Commit b8e1e6a

Browse files
yeasyyeasy
committed
Fix command documentation accuracy
1 parent 64c6de1 commit b8e1e6a

File tree

8 files changed

+22
-26
lines changed

8 files changed

+22
-26
lines changed

‎docs/commands/build.md‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44

55
## Purpose
66

7-
Build publishable outputs from a local directory or a GitHub repository. `build` supports `pdf`, `html`, `site`, and `epub`, and it can generate multiple formats in a single run.
7+
Build publishable outputs from a local directory or a GitHub repository. `build` supports `pdf`, `html`, `site`, `epub`, and `typst`, and it can generate multiple formats in a single run.
88

99
## Syntax
1010

@@ -55,6 +55,7 @@ mdpress build --config ./docs/book.yaml ./docs --format pdf,html
5555
- When `--format` is provided, the CLI value overrides `output.formats` in config.
5656
- When `--format` is omitted, `output.formats` is used first.
5757
- If neither is set, the default output is `pdf`.
58+
- `--format all` expands to `pdf,html,site,epub` and does **not** include `typst`. To include Typst output, specify it explicitly (e.g., `--format all,typst` or `--format pdf,html,site,epub,typst`).
5859

5960
### `--output`
6061

@@ -114,10 +115,12 @@ mdpress build --config ./configs/book.yaml --verbose
114115
| `html` | A self-contained single-page HTML file |
115116
| `site` | A multi-page static site directory |
116117
| `epub` | A single ePub file |
118+
| `typst` | A PDF file generated via the Typst CLI (experimental, Chromium-free) |
117119

118120
## Notes
119121

120122
- PDF generation requires Chrome or Chromium. If neither is available, PDF builds will fail.
123+
- Typst output requires the Typst CLI. If it is not installed, `--format typst` builds will fail.
121124
- During the build, mdpress checks heading numbering, Markdown links, and Mermaid diagnostics. Many of these are warnings and do not necessarily stop the build.
122125
- When `LANGS.md` exists at the project root, `build` generates one output set per language and also creates a language landing page.
123126
- For remote GitHub inputs, the current implementation prefers the remote repository's `book.yaml`. A local `--config` path does not override the remote project's config location.

‎docs/commands/build_zh.md‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44

55
## 作用
66

7-
从本地目录或 GitHub 仓库构建发布产物。支持 `pdf`、`html`、`site`、`epub` 四种输出格式，也支持一次构建多种格式。
7+
从本地目录或 GitHub 仓库构建发布产物。支持 `pdf`、`html`、`site`、`epub`、`typst` 五种输出格式，也支持一次构建多种格式。
88

99
## 语法
1010

@@ -55,6 +55,7 @@ mdpress build --config ./docs/book.yaml ./docs --format pdf,html
5555
- 传入 `--format` 时，命令行值会覆盖配置文件中的 `output.formats`
5656
- 不传 `--format` 时，优先使用 `output.formats`
5757
- 如果两者都没有设置，默认构建 `pdf`
58+
- `--format all` 展开为 `pdf,html,site,epub`，**不**包含 `typst`。如需 Typst 输出，请显式指定（例如 `--format all,typst` 或 `--format pdf,html,site,epub,typst`）。
5859

5960
### `--output` 的行为
6061

@@ -114,10 +115,12 @@ mdpress build --config ./configs/book.yaml --verbose
114115
| `html` | 自包含单页 HTML 文件 |
115116
| `site` | 多页静态站点目录 |
116117
| `epub` | 单个 ePub 文件 |
118+
| `typst` | 通过 Typst CLI 生成的 PDF 文件（实验性，无需 Chromium） |
117119

118120
## 注意事项
119121

120122
- 生成 PDF 依赖 Chrome 或 Chromium；如果系统没有浏览器，PDF 构建会失败。
123+
- Typst 输出依赖 Typst CLI；如果未安装，`--format typst` 构建会失败。
121124
- 构建过程中会检查章节标题编号、Markdown 链接和 Mermaid 诊断，但很多问题是警告，不一定直接终止构建。
122125
- 当项目根目录存在 `LANGS.md` 时，`build` 会按语言分别构建，并额外生成语言入口页。
123126
- 对远程 GitHub 仓库输入，当前实现优先使用远程仓库中的 `book.yaml`。本地传入的 `--config` 不会覆盖远程项目内的配置文件路径。

‎docs/commands/completion.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -41,15 +41,15 @@ source <(mdpress completion zsh)
4141

4242
## Subcommand Flags
4343

44-
Completion subcommands such as `bash` and `zsh` currently support:
44+
Completion subcommands `bash` and `fish` currently support:
4545

4646
| Flag | Default | Description |
4747
| --- | --- | --- |
4848
| `--no-descriptions` | off | Disable completion item descriptions. |
4949

5050
## Notes
5151

52-
- Completion scripts are written to stdout, so they are usually redirected into a file or loaded immediately with `source <(...)>`.
52+
- Completion scripts are written to stdout, so they are usually redirected into a file or loaded immediately with `source <(...)`.
5353
- The `bash` help output explicitly requires the system package `bash-completion`.
5454
- If zsh completion is not enabled yet, run `autoload -U compinit; compinit` first.
5555
- `--config` appears in global flags, but `completion` does not use it.

‎docs/commands/completion_zh.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -41,15 +41,15 @@ source <(mdpress completion zsh)
4141

4242
## 子命令参数
4343

44-
`bash` 和 `zsh` 等补全子命令当前支持：
44+
`bash` 和 `fish` 补全子命令当前支持：
4545

4646
| 参数 | 默认值 | 说明 |
4747
| --- | --- | --- |
4848
| `--no-descriptions` | 关闭 | 关闭补全项描述。 |
4949

5050
## 注意事项
5151

52-
- 补全脚本输出到标准输出，通常需要重定向到文件，或通过 `source <(...)>` 立即载入。
52+
- 补全脚本输出到标准输出，通常需要重定向到文件，或通过 `source <(...)` 立即载入。
5353
- `bash` 的帮助信息明确要求系统安装 `bash-completion`。
5454
- `zsh` 如果还没有启用补全，需要先在环境里执行 `autoload -U compinit; compinit`。
5555
- `--config` 虽然是全局参数，但当前 `completion` 不会使用它。

‎docs/commands/upgrade.md‎

Lines changed: 0 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -81,15 +81,6 @@ The `upgrade` command respects standard HTTP environment variables:
8181
| `HTTPS_PROXY` | HTTPS proxy URL for release downloads |
8282
| `NO_PROXY` | Comma-separated domains to bypass proxy |
8383

84-
## Exit Codes
85-
86-
| Code | Meaning |
87-
| --- | --- |
88-
| 0 | Success (either updated or already latest version) |
89-
| 1 | Network error or failed to fetch release information |
90-
| 2 | Version comparison or parsing error |
91-
| 3 | Download or installation failed |
92-
9384
## Notes
9485

9586
- **Backup Creation**: Before replacing the binary, a backup is created with the `.backup` extension. On successful installation, this backup is automatically removed.

‎docs/commands/upgrade_zh.md‎

Lines changed: 0 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -81,15 +81,6 @@ mdpress --version
8181
| `HTTPS_PROXY` | 用于发布下载的 HTTPS 代理 URL |
8282
| `NO_PROXY` | 以逗号分隔的不使用代理的域名 |
8383

84-
## 退出代码
85-
86-
| 代码 | 含义 |
87-
| --- | --- |
88-
| 0 | 成功（已更新或已是最新版本） |
89-
| 1 | 网络错误或无法获取发布信息 |
90-
| 2 | 版本比较或解析错误 |
91-
| 3 | 下载或安装失败 |
92-
9384
## 注意事项
9485

9586
- **备份创建**：替换二进制文件前，会创建一个以 `.backup` 为扩展名的备份。成功安装后，此备份会自动删除。

‎docs/commands/validate.md‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,11 @@ mdpress validate [directory] [flags]
2020

2121
## Flags
2222

23-
`validate` currently has no dedicated flags and mainly uses global flags:
23+
| Flag | Short | Default | Description |
24+
| --- | --- | --- | --- |
25+
| `--report` | | (none) | Write validation report to `.json` or `.md` file |
26+
27+
`validate` also uses global flags:
2428

2529
| Flag | Default | Description |
2630
| --- | --- | --- |

‎docs/commands/validate_zh.md‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,11 @@ mdpress validate [directory] [flags]
2020

2121
## 命令参数
2222

23-
`validate` 当前没有专属参数，主要使用全局参数：
23+
| 参数 | 简写 | 默认值 | 说明 |
24+
| --- | --- | --- | --- |
25+
| `--report` | | （无） | 将校验报告写入 `.json` 或 `.md` 文件 |
26+
27+
`validate` 同时使用以下全局参数：
2428

2529
| 参数 | 默认值 | 说明 |
2630
| --- | --- | --- |

0 commit comments

Comments
 (0)