Creating a Custom Homepage

2025-06-29T00:00:00+00:00

The Apollo theme provides a default homepage that lists your recent blog posts. However, you might want to create a custom homepage that better reflects your personality and work. This guide will walk you through the process of creating a custom homepage with the Apollo theme.</p>

1. Create a Custom Homepage Template</a></h2>

The first step is to create a custom homepage template. In the root of your Zola project, create a new file at templates/home.html</code>. This file will contain the HTML for your custom homepage.</p>

You can use the following code as a starting point:</p>

{% extends "base.html" %}</span></span>
</span>
{% block main_content %}</span></span>
    <</span>main</span>></span></span>
        <</span>article</span>></span></span>
            <</span>section</span> class</span>=</span>"body"</span>></span></span>
                <</span>h1</span>></span>Welcome to my custom homepage!</span></</span>h1</span>></span></span>
                <</span>p</span>></span>This is where you can introduce yourself and your work.</span></</span>p</span>></span></span>
            </</span>section</span>></span></span>
        </</span>article</span>></span></span>
    </</span>main</span>></span></span>
{% endblock main_content %}</span></span></code></pre>
This template extends the theme's base.html</code> template and overrides the main_content</code> block with your own content.</p>
2. Set the Homepage Template</a></h2>
Next, you need to tell Zola to use your custom homepage template. In the content</code> directory of your Zola project, you should have a _index.md</code> file. If you don't have one, create one.</p>
In this file, add the following front matter:</p>
+++</span></span>
template</span> =</span> "home.html"</span></span>
+++</span></span></code></pre>
This tells Zola to use the templates/home.html</code> file to render your homepage.</p>
3. Add Content to Your Homepage</a></h2>
Now you can add content to your homepage. The content of the content/_index.md</code> file will be available in your templates/home.html</code> template as the section</code> variable.</p>
For example, you can add a title and some introductory text to your content/_index.md</code> file:</p>
+++</span></span>
title</span> =</span> "Hey there! 👋🏼"</span></span>
template</span> =</span> "home.html"</span></span>
+++</span></span>
</span>
I'm a software engineer who loves to write about technology and programming.</span></span></code></pre>
You can then display this content in your templates/home.html</code> template:</p>
{% extends "base.html" %}</span></span>
</span>
{% macro home_page(section) %}</span></span>
    <</span>main</span>></span></span>
        <</span>article</span>></span></span>
            <</span>section</span> class</span>=</span>"body"</span>></span></span>
                {{ post_macros::page_header(title=section.title) }}</span></span>
                {{ section.content | safe }}</span></span>
            </</span>section</span>></span></span>
        </</span>article</span>></span></span>
    </</span>main</span>></span></span>
{% endmacro home_page %}</span></span>
</span>
{% block main_content %}</span></span>
    {{ self::home_page(section=section) }}</span></span>
{% endblock main_content %}</span></span></code></pre>4. Displaying Posts</a></h2>
You can also display a list of your recent posts on your homepage. The following code shows how to display the 5 most recent posts:</p>
{% extends "base.html" %}</span></span>
</span>
{% macro home_page(section) %}</span></span>
    <</span>main</span>></span></span>
        <</span>article</span>></span></span>
            <</span>section</span> class</span>=</span>"body"</span>></span></span>
                {{ post_macros::page_header(title=section.title) }}</span></span>
                {{ section.content | safe }}</span></span>
            </</span>section</span>></span></span>
        </</span>article</span>></span></span>
    </</span>main</span>></span></span>
{% endmacro home_page %}</span></span>
</span>
{% block main_content %}</span></span>
    {{ self::home_page(section=section) }}</span></span>
</span>
    <</span>h1</span>></span>Recent articles</span></</span>h1</span>></span></span>
    <</span>main</span> class</span>=</span>"post-list"</span>></span></span>
        {% set section = get_section(path="posts/_index.md") %}</span></span>
        {{ post_macros::list_posts(pages=section.pages | slice(end=5)) }}</span></span>
    </</span>main</span>></span></span>
{% endblock main_content %}</span></span></code></pre>
This code gets the posts</code> section and then uses the post_macros::list_posts</code> macro to display the 5 most recent posts.</p>
You can also highlight specific posts by getting them by their path:</p>
{% set highlights = [</span></span>
    get_page(path="posts/my-first-post.md"),</span></span>
    get_page(path="posts/my-second-post.md"),</span></span>
] %}</span></span>
<</span>main</span> class</span>=</span>"post-list"</span>></span></span>
    {{ post_macros::list_posts(pages=highlights) }}</span></span>
</</span>main</span>></span></span></code></pre>
This is just a starting point. You can customize your homepage as much as you want.</p>

Rendered Example</a></h2>

Muhsin

Character Shortcodes Example

Creating a Custom Homepage

Collaborative Article

Mermaid Example