Build awesome configuration¶

How the build runs when you publish, and what you can add to it: Eleventy plugins and shortcodes.

How the build works¶

Silex publishes your website to a Git repository, then the hosting platform's CI builds it. Silex writes the site files into the public/ folder of the repository, and generates the build script. build awesome (powered by Eleventy, pinned version 3.1.6) turns public/ into _site/, and _site/ is what gets deployed.

The build step runs two commands:

npx @11ty/eleventy@3.1.6 --input=public --output=_site
cp -R public/css public/assets _site/ 2>/dev/null || true

There is no Eleventy config file in this command. Eleventy is run with command line options, and it looks for a config file at the root of the repository (see Add a plugin below).

Silex also writes public/public.11tydata.js at every publication, for every website. This file tells Eleventy how to treat your pages:

On a website without a data source, it sets a permalink and templateEngineOverride: false. Your pages are copied as they are: about.html stays about.html, and template syntax is left untouched.
On a website with a data source, it is export default {}. Each page then carries its own front matter, and Eleventy renders the pages as Liquid templates.

The build only starts when you publish

The CI pipeline runs when Silex creates a tag named _silex_<timestamp>, which happens at each publication. It also runs on a trigger, api, web or schedule pipeline. It does not run on a normal push. If you edit build.json directly on the forge and push, nothing is built: publish from Silex, or start the pipeline by hand from the platform interface.

Add a plugin¶

An Eleventy plugin adds features to the build: syntax highlighting, image optimization, feeds, and more. Adding one takes three files in your website repository.

1. package.json, at the root of the repository, with the plugin as a dependency:

{
  "type": "module",
  "dependencies": {
    "@11ty/eleventy-plugin-syntaxhighlight": "^5.0.2"
  }
}

2. eleventy.config.js, at the root of the repository too, next to package.json:

import syntaxHighlight from "@11ty/eleventy-plugin-syntaxhighlight"

export default function (eleventyConfig) {
  eleventyConfig.addPlugin(syntaxHighlight)
}

3. build.json, to install the dependencies before the build:

[
  { "type": "sh", "value": "npm i" },
  { "type": "build" }
]

Publish again, and the plugin is active. See Customize the build for the full build.json reference.

Three things to know:

The config file must be at the root of the repository, not in public/. A config file inside public/ is ignored, and your build fails when a page uses something the plugin should provide.
Silex never creates an npm i step for you. Without it, your package.json is not installed and the plugin is never loaded.
The name to use is eleventy.config.js. The old name .eleventy.js still works, and it wins if both files exist. Create only one of them.

Do not import @11ty/eleventy in your config file

Eleventy runs through npx, so it is not installed in your repository. A line like import { HtmlBasePlugin } from "@11ty/eleventy" stops the build with Cannot find package '@11ty/eleventy'. Import your own plugins only, the ones listed in your package.json.

Shortcodes¶

Shortcodes go with data sources. They are template tags, read at build time, on the pages that Eleventy renders as templates. A website with a data source gets such pages, so shortcodes work there. A website without a data source is published as plain files, template syntax is left untouched, and a shortcode has nothing to run in.

A shortcode calls a function, defined in your eleventy.config.js, and the build replaces the tag with what the function returns. Plugins often provide shortcodes: the syntaxhighlight plugin above gives you a highlight shortcode.

Place the block¶

In the editor, open the blocks panel and find the Shortcode block, marked {%, in the last group. Drag it into your page.

Select it, open the settings panel, and fill the two fields:

Shortcode name: the name of the shortcode, for example highlight.
Shortcode attributes: the parameters, for example js or param1, "example param 2".

The block writes the tag for you. Empty, it writes a simple tag:

{% highlight js %}

With other blocks inside it, it writes a paired tag, and your content stays between the two tags:

{% highlight js %}
  ... your blocks ...
{% endhighlight %}

Define the shortcode¶

The build needs to know the shortcode. It comes either from a plugin you installed, or from your own eleventy.config.js:

export default function (eleventyConfig) {
  eleventyConfig.addShortcode("year", () => new Date().getFullYear())

  eleventyConfig.addPairedShortcode("callout", (content, type = "info") => {
    return `<div class="callout callout-${type}">${content}</div>`
  })
}

At publication¶

Silex publishes the page with the tag inside it, and the build replaces the tag with the result. If the shortcode is not defined anywhere, the build fails with tag "<name>" not found and nothing is deployed.

What you cannot customize¶

Silex owns several files and rewrites them at every publication. Changes you make to them are lost:

The published folder structure. Silex writes your pages, CSS and assets into public/.
public/public.11tydata.js.
build.sh, generated from your build.json.
The CI file (.gitlab-ci.yml and its equivalent on other platforms), which only runs sh build.sh.

What is yours: build.json, and any file you add at the root of the repository, such as package.json and eleventy.config.js.

Troubleshooting¶

My shortcode appears as text on the published page¶

The page was copied, not rendered. This happens on a website without a data source. Shortcodes need a data source.

The build fails with `tag "..." not found`¶

The shortcode name is not known by the build. Check the spelling in the Shortcode name field, and check that the shortcode is defined in your eleventy.config.js, or provided by a plugin you installed.

My plugin has no effect¶

Check the three points in Add a plugin: eleventy.config.js at the root of the repository, the plugin in package.json, and an npm i step before the build step in build.json. Then open the job log on your hosting platform, or run sh build.sh in a clone of your repository to get the same build locally.