zola/docs/content/documentation/getting-started/cli-usage.md

117 lines
3.5 KiB
Markdown
Raw Normal View History

2017-09-12 07:13:26 +00:00
+++
title = "CLI usage"
weight = 2
2017-09-12 07:13:26 +00:00
+++
2018-10-18 21:09:32 +00:00
Zola only has 3 commands: init, build and serve.
2018-10-18 21:09:32 +00:00
You can view the help of the whole program by running `zola --help` and
the command help by running `zola <cmd> --help`.
## init
2018-10-18 21:09:32 +00:00
Creates the directory structure used by Zola at the given directory.
```bash
2018-10-18 21:09:32 +00:00
$ zola init my_site
$ zola init
```
If the `my_site` folder already exists, Zola will only populate it if it does not contain non-hidden files (dotfiles are ignored). If no `my_site` argument is passed, Zola will try to populate the current directory.
You can initialize a git repository and a Zola site directly from within a new folder:
```bash
$ git init
$ zola init
```
## build
2019-01-05 10:04:12 +00:00
This will build the whole site in the `public` directory after deleting it.
```bash
2018-10-18 21:09:32 +00:00
$ zola build
```
You can override the config `base_url` by passing a new URL to the `base-url` flag.
```bash
2018-10-18 21:09:32 +00:00
$ zola build --base-url $DEPLOY_URL
```
2018-08-05 08:29:53 +00:00
This is useful for example when you want to deploy previews of a site to a dynamic URL, such as Netlify
deploy previews.
2018-10-10 21:21:58 +00:00
You can override the default output directory 'public' by passing a other value to the `output-dir` flag.
2018-03-16 18:11:08 +00:00
```bash
2018-10-18 21:09:32 +00:00
$ zola build --output-dir $DOCUMENT_ROOT
```
2018-03-16 18:11:08 +00:00
You can also point to another config file than `config.toml` like so - the position of the `config` option is important:
```bash
2018-10-18 21:09:32 +00:00
$ zola --config config.staging.toml build
2018-03-16 18:11:08 +00:00
```
## serve
This will build and serve the site using a local server. You can also specify
the interface/port combination to use if you want something different than the default (`127.0.0.1:1111`).
2018-08-05 08:29:53 +00:00
You can also specify different addresses for the interface and base_url using `-u`/`--base-url`, for example
2018-10-18 21:09:32 +00:00
if you are running zola in a Docker container.
Use the `--open` flag to automatically open the locally hosted instance in your
web browser.
2018-11-01 22:36:47 +00:00
In the event you don't want zola to run a local webserver, you can use the `--watch-only` flag.
Before starting, it will delete the public directory to ensure it starts from a clean slate.
```bash
2018-10-18 21:09:32 +00:00
$ 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 --port 2000 --output-dir www/public
2018-11-01 22:36:47 +00:00
$ zola serve --watch-only
$ zola serve --open
```
The serve command will watch all your content and will provide live reload, without
hard refresh if possible.
2017-10-03 15:21:18 +00:00
2018-10-18 21:09:32 +00:00
Zola does a best-effort to live reload but some changes cannot be handled automatically. If you
fail to see your change or get a weird error, try to restart `zola serve`.
2018-03-16 18:11:08 +00:00
You can also point to another config file than `config.toml` like so - the position of the `config` option is important:
```bash
2018-10-18 21:09:32 +00:00
$ zola --config config.staging.toml serve
2018-03-16 18:11:08 +00:00
```
### check
The check subcommand will try to build all pages just like the build command would, but without writing any of the
results to disk. Additionally, it will also check all external links present in Markdown files by trying to fetch
them (links present in the template files will not be checked).
## Colored output
Any of the three commands will emit colored output if your terminal supports it.
*Note*: coloring is automatically disabled when the output is redirected to a pipe or a file (ie. when the standard output is not a TTY).
You can disable this behavior by exporting one of the two following environment variables:
- `NO_COLOR` (the value does not matter)
- `CLICOLOR=0`
Should you want to force the use of colors, you can set the following environment variable:
- `CLICOLOR_FORCE=1`