Starting off with the first image that appears alongside here at the top of this post. Demonstrating that this image doesn’t always have to be huge. In fact, any image in the post can be set to a small or a medium size, and aligned alongside any paragraph, if that’s more appropriate to the image quality, or the post’s content.

If there is no image at the top, a nice ‘drop cap’ style is instead added automatically to the first letter of the first paragraph. Here’s an example on one of my later posts.

In this first demo post, intead of using ‘Lorem Ipsum’ dummy text, I’m going to try to describe the typography and layout from within the examples themselves. Like in this blockquote:

“With so many different elements crammed in together, this page will probably look a bit of a mess. But, I won’t properly find out how well these styles work, until I start using them for real posts.”
— Brian Liddell

I’ve used the (excellent) Tailwind CSS framework in all my templates. One of Tailwind’s key features is that it comes with no pre-set typography at all. So all the type styling has to be built up from a zero base, rather than hacking it down from the framework’s pre-set defaults.

I’ve started off with very basic typography, using only Tailwind’s system default sans-serif and serif fonts — but mixing them up a bit, sometimes within the same sentence. For example, applying bold to these emboldened words changes their font family, as well as their font weight. Hopefully, this will add a bit of life to my minimalist design.

I want this to look like a personal website, rather than a corporate blog. That said, I’m looking forward to experimenting with more interesting typography and colours, sometime later on.

1  How the image layout options work

I’ve spent a crazy amount of time designing/evolving my website’s layout — aiming to create a varied and interesting grid — at every breakpoint — and using the full screen width, not just the main text column.

For example, the photo on the left remains aligned alongside this paragraph at all screen sizes, except for mobile screens, where it appears above.

This image’s file name, its size, its position, and its caption are all defined using a bracketed ‘shortcode’ called a KirbyTag, which is inserted inline with all the other text in Kirby’s Markdown editor. The KirbyTag for this particular image looks like this:

(image; geese.jpg class: small left caption: I am a **small left** image)

Because image KirbyTags are plain text, they can easily be moved, with a simple cut-and-paste, to appear alongside or above any other paragraph.

And also because they are just plain text — they are much less intrusive than ‘Matrix’ or ‘Builder’ blocks when writing or editing the rest of the content.

The CSS class options for these image KirbyTags are really simple too:

• Sizes are: small, medium, large, or extra-large,
• positions are: left, right, or center,
• and no-shadow or extra-shadow, to remove or increase their shadow outlines

This simple text-only markup means that both the image’s size and its position can be changed in an instant — a super-fast and powerful formatting tool, that I’ve used to create every post (and page) on this site.

2  More examples of image layout

As well as the right and left examples above, images can also be positioned in grid rows — set using class names, numbered one to five. No additional markup is needed, just a line of three spaced hyphens - - - to separate each row:

These - - - invisible separators split the ‘floated’ images above into horizontal rows. However, all the images below here are sized and positioned to fill their rows, so they don’t need a separator between them:

I don’t expect to use these center images very often. I prefer images aligned at the left edge of the text column, with my favourite off-center class:

Images can be entered quickly, without specifying a class, and these default to fill the text-column width:

• This wide range of options makes it easy to choose a display size that’s exactly right for the context and quality of each image.

• Captions are aligned to stand out from the main text, yet they take up only the space they need.

• I’m a huge fan of captions, and I use them wherever I can! But, I don’t like automated ‘gallery’ layouts, where images are butted up to each other, without captions, and no regard for content or colour clashes.

• I think my Markdown row layouts are a better alternative, offering lots more control, without losing the gallery aesthetic. There are good examples in this cycle touring post, and with different aspect ratios in this later post.

Update, 7 June 2021: I’ve just added a Medium-style ‘zoom’ feature — so you can now click on (some) images on this page, and they’ll enlarge to fill the available space. This can be selectively applied to any image: by adding a zoom class to individual image KirbyTags, or (much quicker), by ticking a single checkbox in the control panel, to enable zooming for every image on the page.

3  Markdown text styles and spacing

The h1 heading above isn’t usually repeated in a blog post. However, h1 styles are needed for other non-blog pages, such as ‘home’ and ‘about’, and their use is permitted for major sections in longer blog posts like this.

Heading styles h1 to h4 are simple to set in Markdown, in lines of text beginning with #  to ####  :

This is an h2 heading

There is no bold in any heading style! Emboldened words in h1, h2, h3, and h4 headings are rendered in a red round-cornered box instead.

This is an h3 heading

Text below h1, h2, and h3 headings is spaced closely beneath them, like this.

This is an h4 heading

H4 headings are exactly the same as h3 headings, except the spacing above and below them is tighter.

I like to use longer h2 headings, sentence-case across multiple lines, to emphasise key points…

Space between successive headings is automatically set closer, like above this h3 heading

These closely spaced h3 headings also look good as a display text style, on pages such as my site’s home page

Below the next paragraph is a horizontal rule, entered in Markdown as a line of three hyphens ---.

These horizontal rules always clear the full page width — so if there is an adjacent image ‘floated’ to its right or left, the rule will always position itself above or below it. The actual spacing depends on the type of content before and after, and this is always set automatically:

Headings are closely spaced below horizontal rules, contrasting with the extra space above them

This distinctive spacing is an effective way of structuring blocks of content, especially when aligned with an image alongside.

Sometimes it’s useful to add some extra space with a spacer. This is done by inserting another hidden separator — this time with a single line of three asterisks ***. And, if the following block is a text paragraph (like this one), this also automatically triggers a nice red drop-cap for the first letter.

All the main text and list typography is set (like this) to the same 18 px font size (19 px on widescreens, 16 px on mobile), and 1.5 line height, with a consistent spacing between every paragraph or list block.

Emphasised text looks like these emboldened words, or like these italicised words, and clickable links look like this: I am a KirbyTag link.

Highlighted, underlined, deleted, and Small-Cap styles

Headings or text which are tagged <mark>like this</mark> are highlighted like this.

Underlined headings and text are marked-up <u>like this</u> to look like this.

Deleted headings and text are marked-up <del>like this</del> and look like this.

‘Small-cap’ headings and text are tagged <small>Like This</small> to make them look Like This.

Blockquotes, Quote tags, and Pull-quotes

Blockquotes are marked-up with a simple > right-arrow-bracket before a block of text or a heading in Markdown. They’re a great way of highlighting key points, not just for quotations:

Blockquotes can contain h1, h2, h3, or h4 headings

— or default text like this, which can be emboldened or italicised or linked like this.

Quote tags are used <q>Like this</q> to add, not only italic formatting, but also these funky red quotation marks: Like this.

Pull-quotes are created from quote tags — using the new ‘card’ layout styles I’ve added in an update at the end of this post.

Inline code and code blocks

Inline code is marked-up with back-ticks `like_this.php` and will then be rendered like_this.php

Code blocks are marked-up with a line of three back-ticks: ``` on the lines immediately before and after the enclosed code, and look like this:

<?php snippet('head') ?>
<?php snippet('header') ?>
<!-- longer lines of code will overflow, but can be horizontally scrolled like this -->

4  Markdown lists

Update, 20 November 2020: After several months of using Markdown in Kirby, I’ve only just discovered that there are two alternative list spacings available in its syntax:

If list items are separated by blank lines, Markdown will wrap the items in <p> tags in the HTML output
— John Gruber's original docs

How could I fail to notice this terrific option, for so long?

This means I can abandon my previous hacky CSS to achieve different list spacings — and I’ve now re-coded all my Markdown lists with this much cleaner ‘blank-line’ mark-up…

An unordered list, with an h4 heading

• Unordered list items are entered in Markdown - Like this
• This standard unordered list is tightly spaced, with the default sans-serif font
• It’s useful for shorter lists of key points

An ordered list, with an h4 heading

1. Ordered list items are entered in Markdown: 1. Like this
2. This is the same as the unordered list, but with neat red counters instead of bullets
3. All the list items can be emboldened or italicised or linked exactly like before

An unordered list, with an h3 heading, and ‘blank-line’ spacing

• This unordered list has the same spacing and serif font as the default paragraph text.

• These ‘spaced-out’ lists are ideal for longer sentences, or substantial paragraphs.

• Just as important, they’re a quick and easy way to add some structure to my writing.

An ordered list with an h3 heading, and ‘blank-line’ spacing

1. Just like the unordered list, but with more prominent red and white counters.

2. This increased spacing for lists is best suited to longer sentences, or substantial paragraphs. That’s why I’ve written an extra sentence to fill out this line.

3. List items’ content can be extended by other indented blocks:

   Adding four spaces before the first word of this paragraph indents it to line up with the previous list item…

   /* four spaces before ```` backticks */
   /* also indents code blocks */

4. Indenting the blocks above prevents this next item’s count from reverting to ‘1’.

5  Final thoughts…

Designing these layouts at the same time as coding them has been a great way to learn and test my ideas, but incredibly inefficient and time consuming. If there is ever a next time, it would probably be much faster to learn Sketch or Figma first.

Using too many styles together (as on this example page) can look confusing and messy. So it’s important to use everything in moderation, and it will take time and practice to get this right.

Last but not least, here’s a nice button, using <button> … </button> tags, wrapped around the standard KirbyTag link:

Even more updates!

September 2024: It’s been four years(!) since I started work on this blog. And, although I’ve lost some enthusiasm for writing since then, I’ve continuously (and obsessively) tinkered with its design and coding.

I’ve shoe-horned these further additions into this already long and complicated post, mainly because it helps (me) to find (and test) everything, in a logical order, in one place.

Update, 25 January 2021: Card layouts

As well as the <button> and <mark> tags already sneaked into the Markdown above, I’ve now introduced one more HTML element to the mix.

By adding <aside> tags, and re-using existing image classes, I’ve created these new card layout styles:

Update, 9 March 2022: Horizontal cards layout

I’ve just added these ‘horizontal’ card layouts, with a smaller image always aligned to the right:

Cards are sized and positioned using existing image classes — but the size and position of their internal image is always automatic.

Pull-quotes are created with quote tags inside cards, alongside or within the main text column.

Wrapping <cite> … </cite> tags around text in a card adds italic styling and right alignment:

I’ve worked hard to simplify the markup for these cards, and to optimise their responsive behaviour. Hopefully I’ll write a more detailed example post, linked to here, when I’ve finished.

Update, 13 May 2021: Markdown tables too!

Below are a few sample lines from a much larger table I’ve just compiled for this post — using the extended Markdown syntax for tables.

This table markup is wrapped in <aside class="table"> … </aside> tags.

All its text styling is then automatic, and it can also be resized and positioned by adding any of the image classes described earlier.

Update, 10 April 2022: Simplified syntax…

I’ve at last learned (just) enough Regex, using PHP’s preg_replace() function, to make my tag syntax more consistent with Kirby’s shortcodes.

So, I can now (optionally) use:

• <card class: large dark> … </card>
  instead of
• <aside class="large dark”> … </aside>

Update, 30 June 2022: Another great feature I didn’t know about…

<details>
<summary>
### The heading goes here, with no extra markup… 
</summary>
Content goes here, using existing Markdown styling…
</details>

Final update, 15 May 2021: I’m stopping now!

I realise that by adding these few HTML tags, I’ve broken my original claim in the headline of this post — that I’ve used just ‘one image shortcode’.

In my defence, these hacky departures from pure Markdown have enabled a surprising repertoire of responsive layouts and fancy typography.

But, now I need to drag myself away from this obsessive tinkering, to write a few ‘real’ blog posts.

So, I’ll end here with an example of the little red star that’s added automatically to the last <p> paragraph block of every post — like this.