Important Concepts

Some things you should be aware of if you decide to use this starter kit.

All content is pre-rendered

Currently, the entire Umbraco node tree is retrieved at Eleventy build time. In fact, a maximum of 1111 nodes are retrieved (configurable via the UMBRACO_DELIVERY_API_TAKE environment variable). The 1111 limit is arbitrary, we just need to pass some big number to the Delivery API, otherwise it will only return 10 content items.

I haven't really thought much yet about large websites which may need interesting things like incremental builds, additional caching, or other performance optimisations. I'm okay with it for now as the API calls only occur at site build time and don't affect runtime performance.

Eleventy output site structure reflects Umbraco node tree structure

The URLs you see for content nodes in the Umbraco backoffice are mapped to Eleventy permalinks. For example, consider the following node:

This will be rendered to the output file Site/_site/docs/important-concepts/index.html.

This is intended to be intuitive for editors who would typically expect to see the same URL on the front end as in the backoffice. It also gives editors full control over their URLs (but redirects and aliases are not currently supported).

Nunjucks templates are rendered for Umbraco nodes based on their content type

Not all Umbraco nodes represent pages on the front end, one example being the siteSettings node in the starter kit. Nodes that are meant to be rendered need to have a content type alias with a suffix of Page.

The content type is mapped to a Nunjucks template template of the same name under Site/_includes/pages/. For example, a node of type webPage will be rendered with the template Site/_includes/pages/webPage.njk.

All pages inherit the base layout at Site/_includes/layouts/base.njk.

Have a look at Site/content/UmbracoPage.11ty.js where much of the magic happens. This is an Eleventy JavaScript template that uses the Render plugin to dynamically render Nunjucks page templates based on content type.

How to access Umbraco data in templates

The following variables are made available in page templates for easy access to Umbraco data:

• currentPage: the content item currently being rendered.

• umbraco.content: an array of all content items returned from the Delivery API.

• umbraco.pages: an array of all content items representing pages to be rendered (content types with a Page suffix, as mentioned above).

• umbraco.settings: the properties of the siteSettings node in the CMS.

All content items and properties have the same structure as they do in the Delivery API JSON response (they are effectively the exact same objects).

The umbraco object is populated in Site/_data/umbraco.js, an Eleventy global data file.

How media is handled in rich text content

In the templates provided with the starter kit, rich text properties are piped through a custom Eleventy filter named richText. This will scan the rich text HTML and prepend the Umbraco base URL (configurable via the UMBRACO_BASE_URL environment variable) to all relative URLs starting with /media/.

The Eleventy Image HTML transform will process <img> or <picture> tags as a post-processing step in the build. Umbraco media images are downloaded from the CMS and cached locally for faster subsequent builds.

Configuration

The starter kit supports a number of options and comes with some default configurations that are worth being aware of. See the configuration docs for more information.