Conditional outputs

Conditional outputs allow you to change how you output your content depending on certain variables. For example, you might want to mark some of your content as draft, and make sure it's only included in test builds, not in builds for the live site.

Quickstart

// `_data/environment.js`
module.exports = {
    'output': process.env.OUTPUT
};

// `index.md`

{% if environment.output == "draft" %}
Draft text
{% endif %}

Then build the output with:

# include the draft content
OUTPUT=draft npx @11ty/eleventy

# exclude the draft content
npx @11ty/eleventy

# include the draft content
$env:OUTPUT="draft"; npx @11ty/eleventy; $env:OUTPUT=$null

# exclude the draft content
npx @11ty/eleventy

Explanation

11ty allows us to pass environment variables to our templates using Node.js' process.env property. 11ty docs example.

This may sound complicated. What it means is:

You need a data file listing your environment variables.
You set those variables in the CLI (command line interface) when you build the site, or in your npm scripts.
Your templates can check for those variables and take action based on the values.

In the example above, we:

Create an environment variable named OUTPUT.
Check the value of the variable in the index.md file.
If the value of the variable is draft, we show the draft content.
Build the site, setting the value of OUTPUT to draft.

Why is OUTPUT capitalized?

It's a common style convention for environment variables.

What's going on with PowerShell?

The 11ty documentation shows how to set environment variables in a Bash shell (or CLI). In PowerShell it's more complicated. There is a detailed explanation in this StackOverflow answer.

The PowerShell command:

Sets the environment variable before running the 11ty build.
Runs the 11ty build.
Clears the environment variable.

If you use an npm script (for example, npm run draft) to build your site, I recommend using cross-env to avoid PowerShell-related quirks. Take a look at this site's package.json for an example.

Can I still use flags like `--serve` or `--output`?

Yes. For example, the following overwrites the default output directory, docs, and puts the output into docs/draft. This allows you to have several output folders. You could have one for live, one for draft, and so on.

# Bash
OUTPUT=draft npx @11ty/eleventy --output=_site/draft

# PowerShell
$env:OUTPUT="draft"; npx @11ty/eleventy --output=_site/draft; $env:OUTPUT=$null