Templates

A template is a plain HTML file with data-arc-* attributes and {{ }} placeholders. Arc CMS fills it with an entry's data to build its page. No framework knowledge is needed.

For the step-by-step path of designing a site's templates, see Design templates. This page is the reference: the tables below are the full list of what a template can use.

What it is

Each content type points at a template folder. A type without public pages uses only the folder's partials.html, for its cards on the home page.

A file a folder lacks is taken from the default folder, so a folder can hold just the one file it changes.

Arc CMS ships three folders in public/_site/templates/: default (used by any type without a folder of its own, so every type renders), articles, manuals and info (the standard pages, see Standard pages, with a Contact layout). An app's folders go in src/custom/site/templates/. A folder name uses lowercase letters, digits, hyphens and underscores, and starts with a letter or digit (case-studies, blog_2); a folder named otherwise is not served, and npm run dev warns about it. The build puts both sets together and serves them at /_site/templates/{folder}/{file}.html; a file in the app's folder at the same path as one of Arc CMS's replaces it. The folders offered in the admin are every folder the site has, listed by the build in /_site/site.json (see Use the custom space).

The same template is filled in two places, and both use the same attributes:

A template is a fragment: no <html>, <head>, <body> or doctype. Only real tags count, in the file's first 2,000 characters: a comment, <style> or <script> that mentions <head> is fine. Publishing wraps it in a full document with the title, meta tags, structured data, language links and site stylesheets; see What publishing puts around your template.

Turn it on or off

Templates are part of the Content feature (content). With content off there are no content pages, so templates are not used.

Set it up

1. Copy a folder to start from, for example public/_site/templates/default/ to src/custom/site/templates/events/.

2. Edit src/custom/site/templates/events/list.html and src/custom/site/templates/events/detail.html. Delete a file you do not change; the default's is used.

3. In Content > Content types, edit the type and pick the folder under Content Template. Run the app locally and open /events to see the templates filled.

4. Deploy Hosting (see Deploy), then rebuild the published pages so they use the new template:

   npm run seed:dev

   For production: npm run seed:prod. The full npm run deploy:dev and npm run deploy:prod run the seed at their end. Republish website in Content > Content types also rebuilds every page.

Use it

Attributes

A template is filled in this order: UI strings (data-arc-t) first, then site info (data-arc-site, below), then loops, then the page's own bindings. So a translated string may itself hold a placeholder such as {{ contentType }}, and a loop's row is translated once, before it is repeated. UI string keys and translations are covered in Languages.

Site info

The site's own details, typed once in Settings, About, print on any page with data-arc-site: in the header, the footer, the home page, every template (list, detail and partials) and static pages, both on published pages and in the app. A change in About republishes every page that uses them.

An element bound to a value the site does not have is removed. The social links are the Social and profile links of About, one URL per line; the platform is read from each address. Known sites are Facebook, Instagram, X, LinkedIn, YouTube, GitHub, TikTok, Pinterest, Threads, WhatsApp, Telegram and Medium.

<p data-arc-site-if="phone"><i class="fa-solid fa-phone"></i> <a data-arc-site="phone"></a></p>
<ul data-arc-site-loop="social">
    <li><a href="{{ url }}" aria-label="{{ label }}"><i class="{{ icon }}"></i></a></li>
</ul>

Syntax details

Special elements

Put <arc-header> and <arc-footer> in list.html and detail.html, never in partials.html. Keep the search box and language switcher in the header or footer, so they work in the app too.

Detail page bindings

Everything detail.html can use outside a loop. Every other field saved on the entry is there too, under its own name.

Loops on a detail page:

List page bindings

Outside the loop, list.html has:

Inside data-arc-loop="items", one row per published entry, newest first or in the type's own order (see Put entries in your own order), at most 100. A list's rows and a partial's cards have the same bindings:

An entry with a translation shows it on that language's pages; one without shows its default-language text.

Custom field bindings

A custom field binds by its stored key (events-price) and by its short key, the name without the type slug (price), on detail pages and inside the items loop of lists and partials. So one template can serve several types. The short key never replaces a built-in: a field named "Title" does not shadow title. Some types add derived keys beside the stored value:

Repeating fields render only on detail pages, not inside the items loop of a list or partial. The default detail template already loops fields with the keys gallery, details, faq and locations, so fields with those keys render with no template work. It also loops info_cards, but a new field's key is made from its name with hyphens in place of spaces and underscores, so a new field cannot get that key: use a loop of your own, as below.

<section class="info-cards" data-arc-loop="info-cards">
    <article class="info-card">
        <img data-arc-if="image" data-arc-bind="image" alt="">
        <i data-arc-if="icon" class="{{ icon }}" aria-hidden="true"></i>
        <h3 data-arc-bind="headline">Headline</h3>
        <p data-arc-bind="info">Text</p>
    </article>
</section>

A file field keyed brochure, as one download button, or a list of every file:

<a data-arc-if="brochure_url" href="{{ brochure_url }}" class="btn">Download {{ brochure_title }} ({{ brochure_type }}, {{ brochure_size }})</a>

<ul data-arc-loop="brochure">
    <li class="file-{{ kind }}"><a href="{{ url }}">{{ title }}</a> {{ type }}, {{ size }}</li>
</ul>

Files linked in rich text are cards already: one link, <a class="arc-file" data-arc-file="pdf"> holding .arc-file-title and .arc-file-meta. main.css draws them with the type's colour on the left edge; restyle .arc-file in site.css to change them.

Layouts

Every entry of a type uses the folder's detail.html. For a page that needs its own look, such as a Contact page laid out differently from About, add a layout: another detail file in the same folder, named detail-{name}.html.

1. Put the file in the type's folder, such as src/custom/site/templates/info/detail-contact.html. The name after detail- uses lowercase letters, digits, - and _. It is a template like detail.html, with the same bindings.

2. In the editor, open the entry. The Basic tab now shows Layout: Standard (the folder's detail.html) and one option per layout, named from the file (detail-wide-hero.html is Wide hero). The picker shows only for a type whose folder has a layout, so most editors never see it.

3. Pick the layout and publish. The choice is shared by every language of the entry.

A layout replaces only the entry's detail page: the folder's list.html and partials.html are unchanged. An app adds or replaces a layout file by file, like the other files, so src/custom/site/templates/info/detail-contact.html replaces Arc CMS's Contact layout and leaves its detail.html in place. The content type's view page lists the folder's layouts beside the template row.

A layout cannot have fields of its own: fields belong to the type. Use the site's details through site info, and the type's ordinary fields, such as an Info Cards field that only the pages using that layout fill in; on the other pages it stays empty and shows nothing.

When the live site does not have the chosen layout yet, publishing uses the folder's detail.html instead and notes it in the function log, so the page stays online in its standard look. Deploy the website, then publish the page again. The app's preview falls back the same way.

Image sizes

Every upload is stored at four sizes (see Media). Any image binding has one sibling per size, so a template can use a size the editor did not pick:

<img src="{{ coverImage_m }}"
     srcset="{{ coverImage_s }} 300w, {{ coverImage_m }} 600w, {{ coverImage_l }} 900w, {{ coverImage_xl }} 1200w"
     sizes="(max-width: 600px) 100vw, 600px" alt="{{ title }}">

The widths above are for the default maximum of 1200px; they follow the maximum set in Settings, Misc. Unsplash photos are resized by Unsplash to the same limits; an image pasted from elsewhere gets none.

Partials

partials.html renders a block of cards (such as "Latest articles") on the home page, where it is written as an element:

<arc-content-partials content-type="articles" count="4" section-title="Latest articles"></arc-content-partials>

Outside the loop, a partial has:

Inside data-arc-loop="items", each card has the list item bindings, in the type's order. The default partials.html makes the whole card a link only when it has a url. A card shows its translation on a translated home page, in the app too. A type without a partials.html of its own uses the default folder's cards. A partial's <style> and <script> stay where they are in the home page; in the app they run once, after the cards are first drawn. The element works on the home page only; publishing removes it from content pages.

Header, footer and styles

Icons from an icon field need Font Awesome in cssUrls; without it, bind x_svg instead of the class list. How a published page differs from the app's preview is listed in Preview versus live.

Extend it

• A new look for one type: a new folder, as in Set it up.
• New attributes or bindings are a core change: the two renderers, functions/src/shared/template-hydration.ts and src/app/core/services/template-hydration.service.ts, must stay the same. See Keep core generic.

What it stores

Templates have no Cloud Functions of their own; the content feature's functions render them (see Content).

Who can do what

Template files are changed by whoever can edit the repository and deploy Hosting. Choosing a type's folder is an admin action in the content type screen. Nothing about templates is kept in Firestore: earlier versions also read a templates collection and a Settings/partials document, set by hand in the Firebase console, and Arc CMS no longer reads either. Settings/site is admin only. See Security rules.

Troubleshooting