Authoring advertorial sites templates

Advertorial site visually looks the same as your primary website. However, fewer elements detract end-user attention so that they can focus on content created by advertisers.

Advertorial sites are hosted on a "virtual folder" of your primary website. E.g. your website is example.com, then advertorial content will appear under the example.com/advertorials/ path prefix. These requests are routed to the Contimo backend, which will render articles based on templates defined in this repository.

A template is an HTML file processed using Nunjucks templating engine. It is an easy-to-use friendly templating engine.

There are two objects accessible in a template:

website
article

website has information about the website where advertorial content will appear. It has the following structure:

{
    "templateName": "dummy",
    "url": "https://example.com",
    "name": "Dummy website",
    "primaryColor": "#333",
    "secondaryColor": "#aaa",
    "headerCode": "<!-- additional code to appear in the head section -->",
    "footerCode": "<!-- additional code to appear in before /body  -->",
    "logoImageId": "imageId_of_logo",
    "properties": {
        "arbitrary_property": "value"
    }
}

article is an advertorial content that will appear on the website. It has the following structure:

{
    "publicationDate": "14.06.2023 09:23",
    "landingPage": "https://example.com/",
    "url": "https://example.com/advertorials/url-to-article",
    "headline": "Lorem Ipsum",
    "teaser": "Neque porro quisquam est qui dolorem ipsum quia dolor sit amet, consectetur, adipisci velit...",
    "coverImage": "42-970x400_lvjqhc",
    "content": "<p>Articles content</p>"
}

A template is a pure HTML file with Nunjucks syntax to access the article's and website's properties. For instance:

{{ article.headline }} renders headline, and it also escapes HTML-like characters.
{{ article.content | safe }} will render the article's content in HTML without escaping.
{{ website.name }} renders the name of the website

With the website.properties, you can send additional information to reuse the same template across multiple websites. You can use if, for and other Nunjucks tags to make advanced rendering.

To work

Setting up Advertorials playground

During onboarding, Contimo will create a GitHub repository where you will author your templates. You will get a link to it and then you need to clone this repo to your local machine.

To start using this repo, you need to initial dependencies using the npm install or yarn command. Then you use npm run dev or yarn run dev.

After you do that, you will see the URL to your development server (typically http://localhost:8080/). When you change your local files, changes will apply immediately, and the webpage reload. If you have errors in your template, you can find them in the console output.

Authoring templates

Templates are *.njk files in the src/_includes/templates/ folder. The repo in its initial state has the most simple dummy template, dummy.njk. It has all the building blocks and is annotated.

<html>
    <head>
        <meta charset="utf-8">
        {# page_title is a article.headline - website.name and it is set to `page_title` variable #}
        <title>{{ page_title }}</title>
        {# Mandatory inclusion of Contimo tracking script #}
        {% include "src/_includes/contimo_code.njk" %}

        {# Example of how primaryColor and secondaryColor can be used. Other case could be setting up CSS variables #}
        <style>
            h1 {
                color: {{ website.primaryColor }};
            }

            h2 {
                color: {{ website.secondaryColor }};
            }
        </style>

        {# Render additional header code without HTML escaping #}
        {{ website.headerCode | safe }}
    </head>
    <body>
        <header>
        {# If logo is uploaded - render it #}
        {% if website.logoImageId %}
            {# The cloudinaryImage tag:
               - generates and IMG tag to the image by its ID
               - applies transforms (2nd argument), gives an `alt` (3rd argument) 
               - adds HTML attributes to the tag (4th argument) 
            #}
            <a href="{{ website.url }}">{% cloudinaryImage website.logoImageId, "", website.name, {} %}</a>
        {% else %}
            <a href="{{ website.url }}">{{ website.name }}</a>
        {% endif %}
        </header>
        <article>
            {# If article has cover image - render it #}
            {% if article.coverImage %}
                {% cloudinaryImage article.coverImage, "", article.headline, { lazy: true, style: "max-width: 100%" } %}
            {% endif %}

            {# article's headline #}
            <h1>{{ article.headline }}</h1>

            {# article's teaser #}
            <h2>{{ article.teaser }}</h2>

            {# article's content #}
            {{ article.content | safe }}
        </article>

        {# Render additional footer code without HTML escaping #}
        {{ website.footerCode | safe }}
    </body>
</html>

To create a new template, create a new .njk file in the src/_includes/templates/ folder.

The template must be designed to fit all your websites with a common/similar template. You can use website.properties to pass website-specific parameters:

menu items
footer links
GA tracking code etc.

Full templates have:

CMP tag
GTM or other tag manager tag that your websites use
Internal analytics platform

Working with assets

You can employ multiple tactics on how you load your CSS/JS/Image files to the template:

Load them from your domain
Load them from Contimo
Inline them to the template

Loading assets from your domain

It is easy to start loading your resources using an absolute URL. Like,

<link rel="stylesheet" href="{{ website.url }}/css/main.css" />
<script src="{{ website.url}}/js/main.js"></script>

To improve caching, many websites generate unique URLs for their assets. Something like

<link rel="stylesheet" href="https://example.com/css/main.css?v=20230501130425" />
<script src="https://example.com/js/main.js?v=20230501130425"></script>

<link rel="stylesheet" href="https://example.com/css/main.20230501130425.css" />
<script src="https://example.com/js/main.20230501130425.js"></script>

In this case, you should add assetVersion property to your website configuration, and then you can use it, like

<link rel="stylesheet" href="{{ website.url }}/css/main.{{ website.properties.assetVersion }}.css" />
<script src="{{ website.url }}/js/main.{{ website.properties.assetVersion }}.js"></script>

Every time you deploy a new version, you need to update website settings and enter a new assetVersion

If you do so, you must ensure that your old URLs return content after deploying a new version. If you don't - your advertorial content will be rendered without styles, users will not engage with the content, and their attention will be wasted.

Loading assets from Contimo domain

You can reference your asset files in the src/_assets folder. Assuming you put css/main.css and js/main.js there. They should be already minified.

<link rel="stylesheet" href="{{ assetsPrefix }}/css/main.css" />
<script src="{{ assetsPrefix }}/js/main.js"></script>

When you restyle your website, you must update your template and assets.

Inlining assets

To reduce the number of requests, you can bundle JS/CSS file content in the template code.

First, add your CSS/JS files to the src/_assets folder. Assuming you put css/main.css and js/main.js there.

To inline CSS/JS, you need to use the following Nunjucks syntax:

{% cssi "css/main.css" %}
{% jsi "css/main.css" %}

In the dev env mode, files will be processed "as is". In production mode, files will be minified. To enable production mode, update .env file and set NODE_ENV=production.

Working with images

Contimo uses Cloudinary service for hosting and transforming images uploaded to the Contimo platform. Your template "knows" about it in two instances:

website logo
article cover image

You may also use your images for your templates. In this case, we recommend treating them as assets.

To render website logo / article cover image, there is a Nunjucks code:

{% cloudinaryImage logoImageId, "", alt, {"class": "logo-image"} %}</a>

Arguments are:

image ID - website.logoImageId or article.coverImage
Cloudinary transforms. Empty means "as is". You can crop the image to a desired width or height using w_600 or h_300 values. Read the documentation to see all your options.
Alternative text for image
Additional HTML attributes to add to the generated <img /> tag

Previewing templates websites

A template without a website where it is applied is useless.

To see how your template will look on a specific website created in the Contimo platform, you need to create a file in the src/_data/websites/ folder and give it the name <website>.json, like example.json. In the file, you can specify all parameters that are managed in Contimo.

{
    "templateName": "dummy",
    "url": "https://example.com",
    "name": "Dummy website",
    "primaryColor": "#333",
    "secondaryColor": "#aaa",
    "headerCode": "<!-- additional code to appear in the head section -->",
    "footerCode": "<!-- additional code to appear in before /body  -->",
    "logoImageId": "imageId_of_logo",
    "properties": {
        "arbitrary_property": "value"
    }
}

Where templateName corresponds to the name of your template. E.g. template file is src/_includes/templates/my-awesome.njk, then "templateName": "my-awesome".

To see how the template renders, use yarn run dev, open the dev server URL and open a link with the name of your website.

Submitting templates workflow

This repository is a source of truth on how advertorial content is styled. Contimo automatically applies new templates when your push changes to the main branch. You can create dev or feature branches to work on templates without affecting production env.

Authoring advertorial sites templates

Setting up Advertorials playground

Authoring templates

Working with assets​

Loading assets from your domain​

Loading assets from Contimo domain​

Inlining assets​

Working with images​