Jekyll Robot · Control Jekyll at commandline

The Jekyll Ruby Gem provides an executable named jekyll to be used at the command line. Jekyll is a robot, an engine to generate a site from a scaffold. Using the commands and options of Jekyll, a site could be created (command build) or displayed in a web browser (command serve).

Synopsis

Several commands and related options are available to control how the engine jekyll generates a site.

jekyll <command> [options]

Find all commands available for the executable jekyll with the following sections below.

Commands

To change Jekyll’s default behavior generating sites, have a look at the configuration options. All general options can be found with the section General commands. All specific commands and options to control build and serve processes for a site, see the sections for the Build command and the Serve command.

General commands

The executable jekyll provides some general commands to create a new site scaffold from the scratch for example (based on the default theme Minima) or some support commands like doctor to check the configuration of a site or clean to reset an existing, already generated site.

Have a look through the commands and options available this section.

Table 1. General commands
Command	Options	Description
`new`	`--blank`	Creates a new Jekyll site with default gem-based theme. Using option `--blank` to create a new blank Jekyll site scaffold.
`doctor` \| `hyde`	`na`	Outputs any deprecation or configuration issues.
`new-theme`	`na`	Creates a new Jekyll theme scaffold.
`clean`	`na`	Removes the generated site (folder `_site`) and all Jekyll metadata files.
`help`	`<subcommand>`	Shows help, optionally for a given subcommand like build. Example: `jekyll help build`.

Build command

Performs a one off build your site. For default, site pages gets written to the folder _site.

Synopsis

jekyll build|b [options]

Typically you’ll use jekyll serve while developing and jekyll build if you need to generate the site for production.

Table 2. Build Commands
Option	Description
`-c`, `--config` CONFIG_FILE [,CONFIG_FILE2, ..]	Use custom configuration file.
`-d, --destination` DESTINATION	The current folder will be generated into DESTINATION.
`-s` \| `--source` SOURCE	Custom source directory.
`--future`	Publishes posts with a future date.
`--limit_posts` MAX_POSTS	Limits the number of posts to parse and publish.
`-w` \| `--[no-]watch`	Watch for changes and rebuild
`-b` \| `--baseurl` URL	Serve the website from the given base URL.
`--force_polling`	Force watch to use polling.
`--lsi`	Use LSI for improved related posts.
`-D` \| `--drafts`	Render posts in the _drafts folder.
`--unpublished`	Render posts that were marked as unpublished.
`-q` \| `--quiet`	Silence output.
`-V` \| `--verbose`	Print verbose output
`-i` \| `--incremental`	Enable incremental rebuild.
`--strict_front_matter`	Fail if errors are present in front matter.
`-h` \| `--help`	Show detailed options an flags.
`-s` \| `--source` DIR	Source directory. Defaults to current directory `./`.
`-d` \| `--destination` DIR	Destination directory. Defaults to `./_site`.
`--safe`	Safe mode. Defaults to `false`
`-p` \| `--plugins` PLUGINS_DIR1[,PLUGINS_DIR2[,…]]	Plugins directory. Defaults to `./_plugins`
`--layouts` DIR	Layouts directory. Defaults to `./_layouts`.
`--profile`	Generate a Liquid rendering profile.
`-t` \| `--trace`	Show the full backtrace when an error occurs.
`-v` \| `--version`	Print the name and version.

Serve command

Create your site any time a source file changes and serves it locally using builtin web server WEBRick. For default, site pages gets written to the folder _site in your project root.

Synopsis

jekyll serve|s [options]

Typically you’ll use jekyll serve while developing locally and jekyll build when you need to generate the site for production.

Table 3. Serve Commands
Options	Description
`-c`, `--config` CONFIG_FILE [,CONFIG_FILE2, ..]	Use custom configuration file.
`-d, --destination` DESTINATION	The current folder will be generated into DESTINATION
`-s` \| `--source` SOURCE	Custom source directory.
`--future`	Publishes posts with a future date
`--limit_posts` MAX_POSTS	Limits the number of posts to parse and publish.
`-w` \| `--[no-]watch`	Watch for changes and rebuild.
`-b` \| `--baseurl` URL	Serve the website from the given base URL.
`--force_polling`	Force watch to use polling.
`--lsi`	Use `LSI` for improved related posts.
`-D` \| `--drafts`	Render posts in the _drafts folder
`--unpublished`	Render posts that were marked as unpublished.
`-q` \| `--quiet`	Silence the output.
`-V` \| `--verbose`	Print verbose output
`-i` \| `--incremental`	Enable incremental rebuild.
`--strict_front_matter`	Fail if errors are present in front matter.
`--ssl-cert` CERT	X.509 (SSL) certificate neede for HTTPS connections.
`--ssl-key` KEY	X.509 (SSL) Private Key needed for HTTPS connections.
`-H` \| `--host` HOST	Host to bind to.
`-o` \| `--open-url`	Launch your site in a browser.
`-B` \| `--detach`	Run the server in the background. Not available for the Windows operating system.
`-P` \| `--port` PORT	Port to listen on.
`--show-dir-listing`	Show a directory listing instead of loading your index file.
`--skip-initial-build`	Skips the initial site build which occurs before the server is started
`-l` \| `--livereload`	Use LiveReload to automatically refresh browsers.
`--livereload-ignore` GLOB1[,GLOB2[,…]]	Files for LiveReload to ignore. Remember to quote the values so your shell won’t expand them.
`--livereload-min-delay` SECONDS	Minimum reload delay.
`--livereload-max-delay` SECONDS	Maximum reload delay.
`--livereload-port` PORT	Port for LiveReload to listen on.
`-h` \| `--help`	Show detailed options an flags.
`-s` \| `--source` DIR	Source directory. Defaults to current directory `./`.
`-d` \| `--destination` DIR	Destination directory. Defaults to `./_site`.
`--safe`	Safe mode. Defaults to `false`.
`-p` \| `--plugins` PLUGINS_DIR1[,PLUGINS_DIR2[,…]]	Plugins directory. Defaults to `./_plugins`.
`--layouts` DIR	Layouts directory. Defaults to `./_layouts`.
`--profile`	Generate a Liquid rendering profile.
`-t` \| `--trace`	Show the full backtrace when an error occurs.
`-v` \| `--version`	Print the name and version.

Examples

Find some common jekyll CLI commands for build and serve.

Build a site from custom configuration

Typically you’ll use jekyll serve while developing locally and jekyll build when you need to generate the site for production.

jekyll b -c ./site_configs/_config.yml

Build a site in mode incremental

Typically you’ll use jekyll serve while developing locally and jekyll build when you need to generate the site for production.

jekyll b --incremental

Run a site in mode incremental

Typically you’ll use jekyll serve while developing locally and jekyll build when you need to generate the site for production.

jekyll s --incremental