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. I won’t properly find out how well these styles work, until I start using them for real posts”
— Paige Topp

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, small and medium images can also be positioned in columns one, two, or three, alongside each other in rows. 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 formatted to take up only the space they need. I’m a huge fan of captions, and I use them wherever I can. But I’m not a big fan of ‘gallery’ layouts, where images are automatically arranged with no regard for content or colour palette, and no space for captions. I think my simpler row layouts are a better alternative, offering much more control, without losing the gallery aesthetic. This later post includes a couple 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 single post page: 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 or <strong> in any heading style — emboldened words in h1, h2, h3, and h4 headings puts them into 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 tightly spaced below it, in contrast with the spacing above the rule

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

The main text styling looks like this — with an 18 px serif font (16 px on portrait phone screens), just-enough paragraph spacing, and no wasted vertical space.

Emphasised text look 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 finally, blockquotes are a highly flexible way of highlighting key points, not just for quotations:

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

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

This is a content-free sentence, which I’ve inserted simply to avoid ending this section with a blockquote. Perhaps I need a second sentence here too, to sneak this paragraph onto another line.

---

4  Markdown list formats

Updated, November 2020: After several months of using Markdown in Kirby, I’ve only just discovered that there are two possible 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 documentation

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

• This standard unordered list is tight spaced, and uses 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. This is the same as the unordered list, but with a nice automatic red numbers instead of red bullets
2. This is an ideal format for manually entered ‘Footnotes’ (until I get round to adding a Footnotes plugin)
3. All the list items can be emboldened or italicised or linked exactly like before

---

An unordered list with ‘blank line’ 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 ‘blank line’ 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, and use, 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 is part of a much larger table I’ve just compiled for this post comparing six comments apps — 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

Yes — I have to admit that by adding these <aside> tags, I’ve blown my original 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 extent 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.