Skip to navigation Skip to main content
These docs are for an upcoming version of Build Awesome — take extra care before linking here as URLs may change! Look to the latest stable docs instead (or the full release history).
Versions
Canary
4.0.0-alpha.10
Stable
3.1.6
Pro
Coming Soon

Command Line Usage

Prerequisites
  1. Build Awesome runs in a Terminal application. Well, wait—what is a Terminal?
  2. Have you already installed Build Awesome?

Here’s the first command you can enter in your Terminal application to run Build Awesome:

npm pnpm yarn 
# Searches the current directory, outputs to ./_site
npx @awesome.me/buildawesome

# `npx @awesome.me/buildawesome` is the same as:
npx @awesome.me/buildawesome --input=. --output=_site

# Searches the current directory, outputs to ./_site
npx @awesome.me/buildawesome

# `npx @awesome.me/buildawesome` is the same as:
npx @awesome.me/buildawesome --input=. --output=_site

# Searches the current directory, outputs to ./_site
npx @awesome.me/buildawesome

# `npx @awesome.me/buildawesome` is the same as:
npx @awesome.me/buildawesome --input=. --output=_site

Read more about --input and --output. Note that setting the input and output directories via config file is preferred.

A hypothetical template.md in the current directory would be rendered to _site/template/index.html. Read more at Permalinks.

npm pnpm yarn 
# Use only a subset of template types
npx @awesome.me/buildawesome --formats=md,html,ejs

# Don’t process any formats
npx @awesome.me/buildawesome --formats=

# Find out the most up-to-date list of commands (there are more)
npx @awesome.me/buildawesome --help

# Use only a subset of template types
npx @awesome.me/buildawesome --formats=md,html,ejs

# Don’t process any formats
npx @awesome.me/buildawesome --formats=

# Find out the most up-to-date list of commands (there are more)
npx @awesome.me/buildawesome --help

# Use only a subset of template types
npx @awesome.me/buildawesome --formats=md,html,ejs

# Don’t process any formats
npx @awesome.me/buildawesome --formats=

# Find out the most up-to-date list of commands (there are more)
npx @awesome.me/buildawesome --help
  • The default for --formats= changed in v3.0.0 from an alias of * to an empty set.

Build when you save

npm pnpm yarn 
# Add a web server to apply changes and
# refresh automatically. We’ll also --watch for you.
npx @awesome.me/buildawesome --serve

# Change the web server’s port—use localhost:8081
npx @awesome.me/buildawesome --serve --port=8081

# Watch and re-run when files change, without the web server.
npx @awesome.me/buildawesome --watch

# Add a web server to apply changes and
# refresh automatically. We’ll also --watch for you.
npx @awesome.me/buildawesome --serve

# Change the web server’s port—use localhost:8081
npx @awesome.me/buildawesome --serve --port=8081

# Watch and re-run when files change, without the web server.
npx @awesome.me/buildawesome --watch

# Add a web server to apply changes and
# refresh automatically. We’ll also --watch for you.
npx @awesome.me/buildawesome --serve

# Change the web server’s port—use localhost:8081
npx @awesome.me/buildawesome --serve --port=8081

# Watch and re-run when files change, without the web server.
npx @awesome.me/buildawesome --watch

--quiet if the Output is Too Noisy

npm pnpm yarn 
# Shhhhh—Don’t log so much to the console
npx @awesome.me/buildawesome --quiet

# Shhhhh—Don’t log so much to the console
npx @awesome.me/buildawesome --quiet

# Shhhhh—Don’t log so much to the console
npx @awesome.me/buildawesome --quiet

--dryrun to do a Little Testing

Runs without writing to the file system. Useful when debugging.

npm pnpm yarn 
# Run but don’t write any files
npx @awesome.me/buildawesome --dryrun

# Run but don’t write any files
npx @awesome.me/buildawesome --dryrun

# Run but don’t write any files
npx @awesome.me/buildawesome --dryrun

--config to Change the Config file name

npm pnpm yarn 
# Override the default configuration filename (buildawesome.config.js)
npx @awesome.me/buildawesome --config=myconfig.js

# Override the default configuration filename (buildawesome.config.js)
npx @awesome.me/buildawesome --config=myconfig.js

# Override the default configuration filename (buildawesome.config.js)
npx @awesome.me/buildawesome --config=myconfig.js

Read more about Configuration files.

Added in v3.0.0If your specified --config file does not exist, Build Awesome will throw an error.

--to can output JSON Added in v1.0.0

npm pnpm yarn 
# Output a JSON structure (does not write to the file system)
npx @awesome.me/buildawesome --to=json

# Default behavior (Output to file system)
npx @awesome.me/buildawesome --to=fs

# Output a JSON structure (does not write to the file system)
npx @awesome.me/buildawesome --to=json

# Default behavior (Output to file system)
npx @awesome.me/buildawesome --to=fs

# Output a JSON structure (does not write to the file system)
npx @awesome.me/buildawesome --to=json

# Default behavior (Output to file system)
npx @awesome.me/buildawesome --to=fs

--incremental for Partial Incremental Builds

npm pnpm yarn 
# *Repeat* builds only operate on files that have changed
npx @awesome.me/buildawesome --watch --incremental
npx @awesome.me/buildawesome --serve --incremental

# Skip the initial full build with `--ignore-initial`
npx @awesome.me/buildawesome --serve --incremental --ignore-initial

# Pass in a template path, watch/serve not required
# Added in v3.0.0
npx @awesome.me/buildawesome --incremental=myfile.md

# *Repeat* builds only operate on files that have changed
npx @awesome.me/buildawesome --watch --incremental
npx @awesome.me/buildawesome --serve --incremental

# Skip the initial full build with `--ignore-initial`
npx @awesome.me/buildawesome --serve --incremental --ignore-initial

# Pass in a template path, watch/serve not required
# Added in v3.0.0
npx @awesome.me/buildawesome --incremental=myfile.md

# *Repeat* builds only operate on files that have changed
npx @awesome.me/buildawesome --watch --incremental
npx @awesome.me/buildawesome --serve --incremental

# Skip the initial full build with `--ignore-initial`
npx @awesome.me/buildawesome --serve --incremental --ignore-initial

# Pass in a template path, watch/serve not required
# Added in v3.0.0
npx @awesome.me/buildawesome --incremental=myfile.md

Read more about incremental builds. Related GitHub #3324

--ignore-initial to skip the Initial Build Added in v2.0.0

Be wary of any file changes that happened while Build Awesome wasn’t running!

npm pnpm yarn 
# Don’t build when Build Awesome starts, only listen for future file changes
npx @awesome.me/buildawesome --watch --ignore-initial
npx @awesome.me/buildawesome --serve --ignore-initial

# Works great with Incremental
npx @awesome.me/buildawesome --serve --incremental --ignore-initial

# Don’t build when Build Awesome starts, only listen for future file changes
npx @awesome.me/buildawesome --watch --ignore-initial
npx @awesome.me/buildawesome --serve --ignore-initial

# Works great with Incremental
npx @awesome.me/buildawesome --serve --incremental --ignore-initial

# Don’t build when Build Awesome starts, only listen for future file changes
npx @awesome.me/buildawesome --watch --ignore-initial
npx @awesome.me/buildawesome --serve --ignore-initial

# Works great with Incremental
npx @awesome.me/buildawesome --serve --incremental --ignore-initial

Deeper insight into Internals

You can use the DEBUG environment variable to enable the special debug log output, allowing deeper insight into Build Awesome’s internals. For simplicity this example is using the cross-env package.

npm pnpm yarn 
npx cross-env DEBUG=BuildAwesome:* npx @awesome.me/buildawesome --dryrun

pnpm exec cross-env DEBUG=BuildAwesome:* pnpm exec @awesome.me/buildawesome --dryrun

yarn exec cross-env DEBUG=BuildAwesome:* yarn exec @awesome.me/buildawesome --dryrun

Learn more about Debug Mode log output.

Using the Same Input and Output

Yes, you can use the same input and output directories, like so:

npm pnpm yarn 
# Parse and write Markdown to HTML, respecting directory structure.
npx @awesome.me/buildawesome --input=. --output=. --formats=md

# Parse and write Markdown to HTML, respecting directory structure.
npx @awesome.me/buildawesome --input=. --output=. --formats=md

# Parse and write Markdown to HTML, respecting directory structure.
npx @awesome.me/buildawesome --input=. --output=. --formats=md
WARNING
Careful with --formats=html here! If you run Build Awesome more than once, we will attempt to process your new output files as input files (which will throw errors). Read more at the HTML template docs.

Other pages in Eleventy Projects