Templating with MidnightCMS

If you want to customize your site you need at least to edit the templates of MidnightCMS.

Don't worry ! You can customize the templates directly into the backend !
You just have to click on the "Templates" tab, and select what template you want to edit.

Templates are using the Twig Template Engine. You can read his documentation and learn how to use it. It's really easy to use and it offer a large set of functionnalities.

Templating Requirements

MidnightCMS's "Main template" requires a minimum setup if you want some functionalities to work, like the Frontend Editor.

If you look at the default "Main template" of MidnightCMS there's some twig blocks already sets and you'll have to keep the most of them :

        <meta charset="UTF-8">
        <meta name="viewport"
              content="width=device-width, user-scalable=no, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0">
        <meta http-equiv="X-UA-Compatible" content="ie=edge">
        <title>{% block title %}{% endblock %}</title>
        {% block css %}
        {% endblock %}
        <h1>{{ block('title') }}</h1>
        {% block body %}
            {% block content %}
            {% endblock %}
        {% endblock %}
        {% block js %}
        {% endblock %}

The most important blocks here is the css, js and content.

  • The css and js blocks are obviously for inserting your styles and script into. They are needed for rendering correctly the Frontend Editor.
  • The content block is used for rendering your page's content. It's really important to insert it into the template, or your page will not be rendered correctly

The options variable

Sometimes, some page's types gives to your template an "options" variable. It can contains useful informations about the current page. A very good example is for the Blog type : When you are reading a post, the page type gives you a "description" in your options that you can use in you main template for rendering description meta-tag. These meta-tags are mainly used by search engines and social networks for displaying a preview of you page.

If you want an example of displaying data via the "options" variable, here's how you display the description for the Blog type :

{{ options.description|default('my description') }}

As you can see, we use the 'default' twig filter for setting a default description if the current page type don't provide one.

MidnightCMS's Twig functions

MidnightCMS offer some twig functions, that gives CMS-related functionnalities like creating links or make a nav menu.

Note: The twig macros in Midnight v1.0 has been deprecated and will be removed later, please replace your calls by removing the imported file and the prefix. "cms.subPages" will simply become "subPages"

Overview of the functions

  • subPages(page, nb_of_lvl, ul_class, li_class, a_class)

Display a nav menu with customizable classes for each tags generated. You have to give a page that'll be used for displaying, and you also need to give the number of levels you want to display.
Here's the schema of the generated HTML :

<ul class="ul_class">
    <li class="li_class"><a class="a_class" href="link">title</a></li>


  • link(page, append)

Generate a link that leads to the page. You can also give a value to append to the link.
This function is essential to use if you want the frontend editor to work correctly.

When you have finished to edit your template, you can save it with the toolbar's button "Save".