Posted on ::

查看原文

命令行使用方法

Zola 仅包含 4 个命令:initbuildservecheck

您可以通过运行 zola --help 查看整个程序的帮助信息,或通过运行 zola <cmd> --help 查看特定命令的帮助信息。

init

在询问几个基本配置问题后,在指定目录下创建 Zola 使用的目录结构。在这些提示中做出的任何选择都可以通过修改 config.toml 轻松更改。

$ zola init my_site
$ zola init

如果 my_site 目录已存在,Zola 仅会在该目录仅包含隐藏文件(点文件将被忽略)时进行初始化。如果未传入 my_site 参数,Zola 将尝试对当前目录进行初始化。

如果您想尝试对非空目录进行初始化且愿意承担风险,可以使用 zola init --force。请注意,这不会覆盖现有的文件夹或文件;在这种情况下,你会收到“文件已存在(操作系统错误 17)”或类似的错误。

你可以直接在新文件夹内初始化一个 git 仓库和一个 Zola 站点:

$ git init
$ zola init

build

这将在 public 目录中构建整个站点(如果该目录已存在,则会被删除)。

$ zola build

您可以通过向 base-url 标志传递新 URL 来覆盖 base_url 配置项。

$ zola build --base-url $DEPLOY_URL

例如,当您希望将网站的预览部署到动态 URL(如 Netlify 部署预览)时,此方法非常有用。

您可以通过向 output-dir 标志传递另一个值来覆盖默认输出目录 public。如果该目录已存在,系统会提示用户是否要替换该文件夹;您可以通过传递 --force 标志来忽略此提示。

$ zola build --output-dir $DOCUMENT_ROOT

您可以像这样指定 config.toml 以外的配置文件(请注意 config 选项的位置很重要):

$ zola --config config.staging.toml build

您还可以使用 root 标志从其他目录处理项目。如果使用 root 标志进行“树外”构建,建议将其与 output-dir 标志结合使用。(请注意,与 config 类似,位置很重要):

$ zola --root /path/to/project build

默认情况下,草稿文件不会被加载。若需包含草稿文件,请传入 --drafts 标志。

serve

此命令将构建网站并通过本地服务器进行托管。若需使用与默认设置(127.0.0.1:1111)不同的接口/端口组合,可自行指定。

此外,如果您是在 Docker 容器中运行 Zola,还可以分别使用 --interface-u/--base-url 参数为接口和 base_url 指定不同的地址。

默认情况下,本地网络中的设备无法访问所提供的页面。当您希望在移动设备或平板电脑上测试页面交互和布局时,这一点可能尤为重要。不过,如果您将接口设置为 0.0.0.0,本地网络中的设备即可通过请求提供页面的机器的本地 IP 地址和所用端口来访问这些页面。

为了确保一切正常运行,您可能还需要将 base-url 参数修改为本地 IP,或者将其设置为 / 以使用基于服务器的相对路径。

使用 --open 参数可在网页浏览器中自动打开本地托管的实例。

启动前,Zola 会删除输出目录(默认位于项目根目录下的 public 目录),以便从零开始。

如果您指定了目录,但同时也使用了 output-dir 标志,那么如果该目录已存在,Zola 将不会使用该目录,除非使用了 --force 标志。

$ zola serve
$ zola serve --port 2000
$ zola serve --interface 0.0.0.0
$ zola serve --interface 0.0.0.0 --port 2000
$ zola serve --interface 0.0.0.0 --base-url 127.0.0.1
$ zola serve --interface 0.0.0.0 --base-url /
$ zola serve --interface 0.0.0.0 --port 2000 --output-dir www/public
$ zola serve --open

serve 命令会监听所有内容,并在可能的情况下提供实时刷新,无需手动刷新页面。如果您在 Windows 上使用 WSL2,请确保将网站存储在 WSL 文件系统中。

某些更改无法自动处理,因此实时刷新可能无法始终生效。若您未看到更改或遇到错误,请尝试重启 zola serve

默认情况下,实时刷新会设置一秒的延迟,以便更平稳地处理输入文件中快速连续的多次更改。您可以通过 --debounce <duration_ms> 参数控制该延迟时长。
您可以使用 -d1 选项将其(虚拟地)完全禁用:出于技术原因(以及保持简单性),不支持 0 作为“延迟”值。

您还可以像这样指定 config.toml 以外的配置文件(请注意配置选项的位置很重要):

$ zola --config config.staging.toml serve

默认情况下,草稿不会被加载。如果您希望包含草稿,请传递 --drafts 参数。

check

check 子命令将尝试像 build 命令一样构建所有页面,但不会将任何结果写入磁盘。此外,它还会通过尝试获取链接来检查 Markdown 文件中的所有外部链接(模板文件中的链接不进行检查)。

您可以通过 --skip-external-links 标志跳过所有外部链接的检查。

默认情况下,草稿不会被加载。若需包含草稿,请传入 --drafts 标志。

彩色输出

若您的终端支持,将使用彩色输出。

注意:当输出被重定向到管道或文件时(即标准输出不是 TTY 时),着色功能会自动禁用。

您可以通过导出以下两个环境变量之一来禁用此行为:

  • NO_COLOR(值不限)
  • CLICOLOR=0

若要强制使用颜色,可设置以下环境变量:

  • CLICOLOR_FORCE=1

附加信息

Zola 可通过 RUST_LOG 变量提供其行为的详细日志:

  • 若要查看 Zola 的性能计时信息,请设置 RUST_LOG=zola=info,site=debug
  • 若要查看调试信息,请设置 RUST_LOG=debug。注意:此时日志输出将非常冗余,请谨慎使用。
  • 若要完全禁用所有日志输出,请设置 RUST_LOG=off

有关 RUST_LOG 的完整参考,请参阅 env_logger 文档