Blog (RSS)

News about Kirby and stuff

Follow kirby on Twitter
@getkirby for more


Kirby Text Formatting 101

I've been asked a few times, how you can format text with Kirby.

Kirby has a built-in parser for the fantastic Markdown syntax by John Gruber. Markdown is a way to add formats in plain text with easy learnable and understandable tags. It's way easier to learn than HTML and all clients I worked with so far are using it without problems.

To add more features to Markdown, I've developed something, called Kirbytext. It's an extended version of Markdown, which makes it easy to embed images from your content folders, link to other pages of your website, provide download links for files, etc.

This is an overview of all the great things you can do with Kirbytext to get your content formatted in the way you want.

If you want to learn more about how to add kirbytext-formatted content to your templates, please read the docs.

Basic formats

Line breaks & paragraphs

Kirbytext does automatically convert single line breaks and paragraphs. So just add them to your text as you would in any other editor.

My first line
My second line

Another paragraph


Adding a hierarchy of headlines to your content is very easy…

# Headline 1
Lorem ipsum dolor sit amet, consectetuer adipiscing elit.

## Headline 2
Lorem ipsum dolor sit amet, consectetuer adipiscing elit.

### Headline 3
Lorem ipsum dolor sit amet, consectetuer adipiscing elit.

#### Headline 4
Lorem ipsum dolor sit amet, consectetuer adipiscing elit.

Bold Text

**The quick brown fox jumps over the lazy dog**

Italic Text

_The quick brown fox jumps over the lazy dog_

Unordered Lists

The Simpsons: 

- Homer
- Marge
- Bart
- Lisa
- Maggie

Ordered Lists

The Simpsons: 

1. Homer
2. Marge
3. Bart
4. Lisa
5. Maggie

Horizontal Rules

To add a horizontal rule (hr) to your content, just add four asterisks.

Lorem ipsum dolor sit amet, consectetuer adipiscing elit. 


Lorem ipsum dolor sit amet, consectetuer adipiscing elit.


> Design is not just what it looks like and feels like. 
> Design is how it works.

– Steve Jobs

Code Blocks

If you want to demonstrate some code, like I do on this page, simply indent the entire code block with a tab:


    // awesome code example



Link without link text:




Link with link text:

(link: text: Wikipedia)

Open link in a new window

(link: text: Wikipedia popup: yes)

Link with a title

(link: text: Wikipedia title: Go to Wikipedia)

Link with a custom CSS class

(link: text: Wikipedia class: mylink)

Relative links

To link to any page of your site, you can simply use relative links without typing the entire URL. This will make sure, links won't break when you move your site to a different domain or when you are testing your site locally.

(link: docs/getting-started)
(link: blog/text-formatting-101)

Email Addresses

Kirby will automatically encrypt your email addresses, so they won't be that easy to be parsed and misused by spam bots.

Email without link text




Email with link text

(email: text: Send me an email)

Email with a title

(email: text: Send me an email title: Contact me)

Email with a custom CSS class

(email: text: Send me an email class: email)


Images in your content folder

You can easily embed any images from your page's content folder.

(image: myawesomepicture.jpg)

Set the width and height of an image

(image: myawesomepicture.jpg width: 120 height: 200)

Define an alternative text for an image

(image: myawesomepicture.jpg alt: On this picture you can see a cat)

Sometimes you need to add floating or special styling to particular images. Best way to do this is to go for a custom css class.

(image: myawesomepicture.jpg class: floated)

A linked image

(image: myawesomepicture.jpg link:

You can even link to the same picture – maybe for a lightbox feature – or to a different picture in the same content folder.

(image: myawesomepicture.jpg link: anothergreatpic.jpg)

Images from other websites

To embed images from other websites, simply use the direct URL to the image. Please make sure you got the copyright and the permission to deep-link to an external image!


Of course all the additional attributes, described above, are available for external images as well.


Provide a download link to a file in your page's content folder.

(file: companysecrets.pdf)

Download link with link text

(file: companysecrets.pdf text: Download our company secrets)

Youtube & Vimeo Videos

Kirbytext has a built-in way to add Youtube and Vimeo videos to any page without the hassle of fiddling with those scary embed codes. All you need is the URL of the video.




Set the width and height of the embedded video

(vimeo: width: 400 height: 300)

Twitter Profile Links

Linking to Twitter profiles has become almost as important as linking to your own website. Thus Kirby provides a simple way to link to any Twitter profile.

(twitter: getkirby)

With link text:

(twitter: getkirby text: Follow Kirby on Twitter)

Embedding Github Gists

Github is probably the most awesome platform for all developers and sharing pieces of code with a Github Gist is fantastic. Those Gists can be embedded in any page as easy as it is to embed a Youtube video.


Define, which file you want to embed

(gist: file: targetblank.js)

Something's missing?

You'd love to have a special tag for embedding cat pictures from or you need some other tags for your next client project?

Kirbytext is extendable, so you can actually build in all the great features you need.

If you still think there's a missing feature, which should be included in Kirbytext by default, please let me know: or start talking about it in the forum.

More Markdown features

I've not listed all Markdown features here, so if you want to learn more about Markdown and its syntax, head over to John Gruber's site.

Markdown Extra

If you still need more features, you can switch to Markdown Extra, which is also included with Kirby.

Switching it on is easy. Go to site/config/config.php and set

c::set('markdown.extra', true);


There are some fantastic Markdown Editors for Mac and PC, which you can use to edit content for Kirby:

For Mac:

For Windows:

Of course you can still use any other editor, as this is all just plain text.

Questions? Feedback?

Let me know!

‹ Back

blog comments powered by Disqus