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. There are lots more examples below.

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. I can’t show this here, but there are examples on many of my later posts.

In this 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 the Tailwind 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 my website’s layout, trying 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 picture on the left remains aligned alongside this paragraph at all screen sizes, except for portrait phone 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:

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

Because image KirbyTags are plain Markdown 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 distracting than ‘Matrix’ or ‘Builder’ blocks when writing, compiling, or editing the rest of the content

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

• Sizes are: tiny, mini, small, medium, large, or extra-large
• Positions are: left, right, or center
• and no-shadow or dark-shadow, to remove or darken their shadow outlines

This simple text-only markup means that both the image’s size and its position can be changed in an instant — creating a highly flexible, and easy-to-use, article format.

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 from one, two, three … up to nine. No additional markup is needed, just a line of three hyphens --- to separate each row:

---

---

---

---

---

---

---

---

---

---

---

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

• Captions are aligned, so they 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, with no space for captions, and no regard for content or colour clashes.

• I think my Markdown row layouts are a much better alternative, offering lots more control, without losing the gallery aesthetic. This later post includes a few more examples.

Update, 7 June 2021: I’ve just added a Medium-style ‘zoom’ feature — so you can now click on any image on this page, and it will enlarge to fill the available space. This can be selectively applied to any image: either by adding imgclass: zoom 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 wouldn’t normally be repeated in a blog post. However, these Markdown h1 headings are needed on other non-blog pages, such as ‘Home’ and ‘About’.

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, like this.

This is an h4 heading

Text above and below an h4 heading is spaced tighter still.

Below the next paragraph is a full-width ‘horizontal rule’ entered in Markdown as a line of three hyphens ---.

As mentioned earlier, these horizontal rules are also used as separators for image rows, and so they are always automatically hidden whenever they’re entered immediately below any image.

---

All headings immediately following a horizontal rule are closely spaced below it, contrasting with the space above

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

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

---

But, sometimes it’s useful to break up a longer column of text with a spacer. This is done by inserting another hidden ‘horizontal rule’ — this time with a line of three equals signs == =, and this also triggers a nice red ‘drop-cap’ for the first letter of the following paragraph, just like this one.

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

---

Deleted headings and text

Deleted headings and text are marked up ~~like this~~. Deleted text looks like this.

Any text which is tagged <mark> like this </mark> will get styled like this.

---

Inline code and code blocks

Inline code is marked-up `like this.php`, and will then be rendered like this.php.

Code blocks are marked-up with a line of three backticks: ```, 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 -->

---

 Blockquotes and quote tags

Blockquotes are marked-up with a simple > 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 both italic formatting, and funky red quotation marks,  like this 

---

4  Markdown list formats

Updated, 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 ‘paragraph lists’ mark-up…

---

An unordered list

• Ordered lists are simple in Markdown: - Like this…
• This standard unordered list is tight spaced, with the default sans-serif font
• It’s useful for shorter lists of key points
• It’s also handy for manually-entered ‘Notes’ and ‘Related posts’ after the last paragraph in a post

---

An ordered list

1. Ordered lists are simple too: 1. Like this…
2. This is the same as the unordered list, but with nice automatic red numbers instead of red bullets
3. This is an ideal format for manually entered ‘Footnotes’ (until I get round to adding a Footnotes plugin)
4. All the list items can be emboldened or italicised or linked exactly like before

---

An unordered list with paragraph spacing

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

• These wider spacings 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.

• The list items can be emboldened or italicised or linked exactly like before.

---

An ordered list with paragraph spacing

1. This is the same as the unordered list, but with the auto numbers in bright red boxes.

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

3. Lists look better with three items.

---

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 is a nice button, using simple <button> … </button> tags, to wrap the Markdown link text:

Tell me what you think…

---

Update, 25 January 2021: Panel 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 two new panel styles:

---

---

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 above.

Mea Culpa

I have to admit that by adding these <aside> tags, I’ve broken my original headline claim — that I’ve used just ‘one image KirbyTag’.

But this (minor) departure from pure Markdown offers exciting new avenues to explore. Maybe I could extend the new panel styling to enable simple text columns, still sized and positioned by re-using all the existing image classes?

But first, 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 line in every post — but only if it’s in a text paragraph.