How to use and create themes?

What is a theme?#

A theme is some default layouts / templates, blocks, and / or assets. You can use multiple themes in the same project. So thanks to theming, you can easily customize the rendering of your blog / website. There is two kind of themes:

• Personal themes, not shareable. In this case, just put your templates in the layouts/ directory.

• Common themes, shareable. In this case, you can install themes created by the community.

Existing Themes#

• Twitter bootstrap

Installation#

You can use as many themes as you want. This section is only for themes created by the community.

1. add the dependency with composer. Generally, the dependency can be found in the composer.json file in the theme repository.

2. register the theme in the config.yml file:

   #config.yml
   engine:
       themes:
           - %dir%/vendor/carew/theme-bootstrap

Theme folder can contain layouts and assets folders. The %dir% parameter will be replaced by the current directory (i.e. the directory which contains the config.yml file).

Note: The order matters. Carew will search for template in your layouts/ folder, then in themes folder registered in the configuration, then fallback to the default theme.

Customization#

If you want to replace a template, create a new template in your layouts/ directory with the same name as the original one.

You can also extends the original one with extends:

{# my_project/layouts/default.html.twig #}
{% extends 'vendor/carew/theme-bootstrap/layouts/default.html.twig' %}

{% block nav_right %}
    

        

            ...
        
    
{% endblock %}

Default layouts are in a special namespace default_theme:

{# my_project/layouts/default.html.twig #}
{% extends '@default_theme/default.html.twig' %}

{% block nav_right %}
    {{ parent() }}
    

        

            Visit my personal website
        
    
{% endblock %}

Blocks theming#

With carew, you have useful helpers set. Almost all helpers are customizable thanks to the special blocks.html.twig. Of course, you can overide this template:

{% use '@default_theme/blocks.html.twig' %} {# Reimport default blocks #}

{% block document_toc %}
{% spaceless -%}
    {% if 0 == deep %}
{% endif %}
    

        {% if 0 == deep %}
            
Quick access
        {% endif %}
        {% for child in children %}
            

                {{ child.title }}
                {% if child.children %}
                    {{ render_document_toc(child.children, deep + 1) }}
                {% endif %}
            
        {% endfor %}
    
    {% if 0 == deep %}
{% endif %}
{%- endspaceless %}
{% endblock %}

You have created a theme?#

You have created a theme and you want to share it? Write me an email and I will create a new repository on github/carew for you, or send me a pull request and add a new link.