Starting off with the first image that appears at the top of this post. Showing 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 of the page, 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.

Throughout 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 be resized or moved, by changing their class, or 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 outline shadows

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 nesting or 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, below here all the images 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, including 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  Text styles and vertical 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 also permitted for major sections in longer blog posts like this one.

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

This is an h2 heading

Emboldened words in h1, h2, h3, and h4 headings are marked-up as usual like this: **h2** — but they’re always rendered with extra emphasis in a red round-cornered box.

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 — using CSS selector rules for many different permutations of adjacent sibling HTML elements.

Headings, text, and images are automatically close-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 ‘floated’ alongside.

Sometimes it’s useful to over-ride this automatic behaviour by adding a spacer. Here this is done by inserting a second hidden separator — with a single line of three asterisks *** immediately below the visible horizontal rule ---. And, if the following block is a text paragraph (like this one), this also triggers a nice red drop-cap for the first letter.

Below are a few more of these visible --- and hidden *** horizontal rules:

1  There’s a hidden *** spacer above each of these three paragraphs, and this also triggers their drop-cap styling.

2  All text and list typography is set to 18 px font size (19 px on widescreens, 16 px on mobile), and 1.5 line height.

3  Emphasised text looks like these emboldened words, or these italicised words, or this KirbyTag link.

Marked, underlined, deleted, inserted, and Small-Cap styles

Instead of using Markdown, I’ve (ab)used a few more HTML elements, to make it easier to remember these useful inline styles:

• Text which is tagged <mark>like this</mark> is highlighted in yellow like this.

• Underlined text is marked-up <u>like this</u> to make it look exactly like this.

• Deleted text is marked-up <del>like this</del>, and looks like this.

• Text is ‘inserted’ <ins>like this</ins> to make it stand out strongly like this.

• ‘Small-cap’ text is tagged <small>Like This</small> to make it appear Like This.

Blockquotes, quote tags, and pull-quotes

Blockquotes are marked-up with a simple >  right-arrow-bracket and space 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 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 mark-ups 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 stylings — 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 ‘tight-spaced’, in 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, automatically-numbered counters instead of bullets
3. All the list items can be emboldened or italicised or linked exactly as before

An unordered list, with an h3 heading, and ‘blank-lines’ between list items

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

• This ‘loose-spaced’ list format is ideal for longer sentences, or substantial paragraphs.

• Just as important: it’s a quick and easy way to add some structure to my writing.

An ordered list, with an h3 heading, and ‘blank-lines’ markup — now extended with indented text and images

1. Just like the unordered list, but with bigger, red, auto-numbered counters.

2. This ‘loose-spaced’ list is best suited to longer sentences, or substantial paragraphs. That’s why I’ve written an extra sentence to fill out this item.

3. Update, January 2025: Any item in this list can be extended with some indented blocks beneath it:

   Adding four spaces before the first word of this paragraph (in Markdown) indents it to align with the text in the previous list item.

   /* Adding four spaces before its three enclosing backticks… */
   /* Creates an indented code block like this */

   • Four spaces before each line’s -  markup creates an indented unordered list, like this
   • And another line, also preceded by four spaces, looks like this

   Indented blockquotes look like this — but I’m not sure if I’ll ever use them!

   

4. Indenting all the blocks immediately above here (including the image floated alongside) prevents this list item from reverting to the first item in a new ordered list.

   So all the list content stays aligned, and the list counters stay in sequence!

5. Below here is another indented image — this time it’s aligned left (except on mobile) within the main text column.

   

6. Just checking if it works!

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 sometimes 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:

More updates!

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

So, I’ve shoe-horned all 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: Vertical 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 vertical card layout styles:

Update, 9 March 2022: Horizontal cards layout

After another long hiatus, 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:

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’ve worked hard to simplify the markup for these new cards and styles, and to optimise their responsive behaviour.

Nevertheless, 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.

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 paragraph of every post — like this.