Creating a Kirby-powered blog

In this section you will learn how to build a blog with Kirby. We will start with a very basic and minimalistic blog here. You will find more advanced stuff in related sections.

Setting up the content

For this example we will use a very simple file structure. You can definitely get way more fancy than that, but let’s keep it simple:

content
- 1_about-us
- 2_projects
- 3_blog
  - 1_your-first-article
    article.txt
  - 2_your-second-article
  - 3_your-third-article
  - blog.txt

First we add a new listed blog folder to our site (3_blog) so it will appear in our menu. Inside that blog folder we add subfolders for each new article and a blog.txt.

`blog.txt`

Add two fields to your blog.txt.

/content/3_blog/blog.txt

Title: Blog
----
Text: This is a very insightful blog about things I know.
----

More on how we use that later when we build our templates.

Inside each article folder, add an article.txt. By naming it like this, we can later add an article.php template to our template folder and create a specific template for all articles. Add two fields to each article.txt.

Title: This is my first Article
----
Text: Hello World!
----

Building the templates

Add a blog.php and an article.php to /site/templates.

site
- templates
  - article.php
  - blog.php
  - …

`blog.php`

This is the template for the main blog view, which will show a list of all articles.

/site/templates/blog.php

<?php snippet('header') ?>
<?php snippet('menu') ?>

<section class="content blog">

  <h1><?= $page->title()->html() ?></h1>
  <?= $page->text()->kirbytext() ?>

  <?php foreach($page->children()->listed()->flip() as $article): ?>

  <article>
    <h1><?= $article->title()->html() ?></h1>
    <p><?= $article->text()->excerpt(300) ?></p>
    <a href="<?= $article->url() ?>">Read more…</a>
  </article>

  <?php endforeach ?>

</section>

<?php snippet('footer') ?>

Breaking it down a bit…

First we include our header and main menu snippets and start the content section. By giving the content section a second blog selector, we can easily style it later in our CSS.

<?php snippet('header') ?>
<?php snippet('menu') ?>

<section class="content blog">

Next we build the title of our blog and the short description, which we added in blog.txt.

<h1><?= $page->title()->html() ?></h1>
<?= $page->text()->kirbytext() ?>

The next few lines of code consist of a loop, where we build a short version for each article of our blog:

<?php foreach($page->children()->listed()->flip() as $article): ?>

<article>
  <h1><?= $article->title()->html() ?></h1>
  <p><?= $article->text()->excerpt(300) ?></p>
  <a href="<?= $article->url() ?>">Read more…</a>
</article>

<?php endforeach ?>

Breaking it down some more…

With $page->children()->listed() we get a set of all listed subpages in our blog folder. This will return the subfolders we got so far in the following order:

1_your-first-article
2_your-second-article
3_your-third-article

But for our blog we want the latest post to be on top, which is 3_your-third-article.

So what we do is to add ->flip(): $page->children()->listed()->flip, which will return the set of pages in reverse order.

3_your-third-article
2_your-second-article
1_your-first-article

Now we can build our foreach loop with that:

<?php foreach($page->children()->listed()->flip() as $article): ?>
…
<?php endforeach ?>

Within the foreach loop, we build the HTML for each article in our list.

<?php foreach($page->children()->listed()->flip() as $article): ?>

<article>
  <h1><?= $article->title()->html() ?></h1>
  <p><?= $article->text()->excerpt(300) ?></p>
  <a href="<?= $article->url() ?>">Read more…</a>
</article>

<?php endforeach ?>

Let’s have a close look at the following line:

<p><?= $article->text()->excerpt(300) ?></p>

In our article list, we don’t want to show the entire content of each article. That would totally mess up our overview. Kirby has a nice little ->excerpt() function, which makes it easy to only show the first few words or sentences of a large article, which is just perfect for our article overview list.

With $article->text()->excerpt(300) we get an excerpt with a maximum of 300 characters for each article.

With the next line…

<a href="<?= $article->url() ?>">Read more…</a>

…we finally link to the full article. This is where we need the article.php template, which we will build next.

`article.php`

The article template will be responsible for displaying the detailed view of articles. The template code for this is very short and easy to understand.

/site/templates/article.php

<?php snippet('header') ?>
<?php snippet('menu') ?>

<section class="content article">
  <article>
    <h1><?= $page->title()->html() ?></h1>
    <?= $page->text()->kirbytext() ?>

    <a href="<?= url('blog') ?>">Back…</a>

  </article>
</section>

<?php snippet('footer') ?>

All you need to do is to include the header and menu again at the top as well as the footer snippet at the bottom. In between, add a content section and give it an article selector so we can add some nice CSS again later.

The rest is super straight forward. Add the title of your article and the full text of your article and you’re done.

You might also want to add a back link, which will take your visitors back to the article list.

<a href="<?= url('blog') ?>">Back…</a>

Add an intro to your articles

To add an article intro which you can display and maybe style differently from the rest of the post you have to set up an additional field in your article.txt content files first.

Title: Some title
----
Intro: This is a nice article intro.
----
Text: Some great text

Template adjustments

Now we are going to implement the intro in the blog’s overview loop (instead of an excerpt) like this: