Skip to content

Content styleguide

This page contains our guidelines for writing content and the custom Markdown extensions we use. If you want to make any proposals for updates or submit new Cookbook articles, please read this first.

Wording & Style

Kirby’s docs are written in American English, so its orthographic rules apply to all content on the site, including text shown in images. Screenshots, code and other examples should always stick with English as well to keep the documentation as accessible as possible to all of our users.

We try to use language that is as simple as possible to make it easier to understand for non-native speakers.

Always use full sentences (except in lists).

Use of names

We use a lot of names and terms on the site. Usage of those names should be consistent. We follow this set of rules:

  • Everything that is a "trademark" of some sorts is written like intended by the author.
    Composer, GitHub, HTTP Basic auth, JavaScript, Markdown, MySQL, SmartyPants, SQLite, Vue, YouTube, Whoops
  • Our own names are written like this:
    Kirby, Panel, KirbyTag, KirbyTags, KirbyText, Starterkit, Plainkit, Pluginkit
  • Acronyms are always written like they are commonly used (typically all-caps).
    API, CSS, HTTP, JS, REST, SQL, URL, YAML
  • Everything that is not a trademark/name or acronym is lowercased (if not at the beginning of a sentence). This also applies to terms that have a "special" meaning in Kirby, but are not listed above.
    template, snippet, blueprint, field method, …

Formatting & Structure

We use KirbyText to write the content on our website. On top of that, we also use some custom Markdown extensions that help us with formatting the content in our docs and elsewhere on the site.

Use native Markown features over HTML or KirbyTags wherever possible and avoid inline CSS at all cost. This ensures the portability of our content for future updates and is often more readable than any complex markup like HTML or KirbyTags. This guide assumes that you are already familiar with basic Markdown formatting. If not, please refer to our text formatting guide first, to learn how text formatting works in Kirby.

Inline styling

Use italics and bold formatting to draw attention to single words or parts of sentences. You can also put "quotes" around words where appropriate. Every value that represents a file name, path or variable, should be displayed as inline code, e.g. /site/config/config.php and $page to clearly separate it from the rest of the text. As inline code is set in a monospace font, this also makes it easier for the reader to identify single letters within that particular phrase, which is especially important for variable names and code examples.

In general, you should use text formatting sparingly to prevent the text from becoming too cluttered. Every deviation from the regular typography will add noise to the page, but not necessarily make it easier to understand the content. A well-structured page with subheaders usually does not need very much additional formatting (except for inline code, depending on the subject).

TL;DR: Use formatting only, where it adds any benefit to the reader.

Headlines

Use headlines generously to structure your content, this especially holds true for long pages with long text content. Do not use H1 headlines, as these are reserved for the page title. You can use anything from H2 and below. If the page template contains a table of contents at the top, each H2 will be listed there to provide a quick overview of the page contents. Everything from H3 and below is not included in the TOC. Use Markdown syntax to mark up headers.

Headlines should never end with a colon:

## Don't do this:

## Do this instead

Code Examples

Code examples, that are part of a sentence, should be marked up as inline code, whereas longer or multiline code examples should always be written as code blocks. These do not only get syntax-highlighting, but also offer a button to copy their contents to the clipboard, which is quite handy.

Use the fenced code block style (```) and always specify the language of the code (e.g. ```php), so the syntax highlighter can properly colorize it. If your example represents the contents of a specific file or needs to have a title, you should add a title to the codeblock by adding it after the language definition surrounded by double quotes (e.g. ```php "/site/config/config.php"):


```php "/site/snippets/hero.php"
<figure class="hero">
  ...
</figure>
…
```

Common programming languages

The examples shown below list all programming languages supported by the syntax highlighter:

Plain text
Code blocks are very useful for developers and other people who look at code or other things that are written in plain text. As you can see, it uses a fixed-width font.
JavaScript
const gallery = documnet.querySelector('.js-gallery');
PHP
$gallery = new Gallery('My Gallery', ['imagesPerRow' => 5]);
HTML
<div class="gallery / js-gallery">Please enable JavaScript to view the gallery.</div>
SCSS
$color: #ff0000;
.gallery-error {
  color: $color;
}
CSS
.gallery-error {
  color: #ff0000;
}
YAML
gallery:
  imagesPerRow: 5
  images:
    - image1.jpg
    - image2.jpg
Bash
npm run gallery-server
Markdown
# Headline

The **gallery server** is an *awesome* server.

- It’s very very fast, pages usually only take between 5.0 and 15.0 seconds to load!
- We still support PHP 4!

## Installation

1. Make sure that your PC runs Windows Vista or Windows ME. Windows 7 and 10 are not stable yet.
2. Download a copy of Winamp and your favourite theme, so you can listen to your own music while browsing the photo gallery.

Kirby-specific file types

Our content files follow simple schema for storing variables in a human-readable format. Examples of content files (located in the /content directory of your Kirby installation by default) can be highlighted by specifying kirbycontent as the code language. As our content is stored in a content file itself, you need to add 2 spaces of indentation for all content in the block, to prevent the content parsing any separators in your example (---- in an otherwise empty line). The indentation is automatically removed when the content is displayed.

Kirby Content
Title: My Gallery Page

----

Text: This page contains my awesome gallery.

Always use uppercase field names.

For highlighting content itself, specify kirbytext as the code block’s language. KirbyText examples also get highlighting for Markdown formatting. If you need to include KirbyTags into a code sample, you have to escape the opening bracket of each tag ( by substituting it with &lpar; to prevent the parser from interpreting that particular tag.

KirbyText
This is an example of (glossary: kirbytext) with **benefits**.

Custom KirbyTags

(glossary: …)

The glossary KirbyTag inserts a tooltip, that gives quick access to the corresponding glossary article. This is especially useful for new users who read the introductionary articles of the docs, but also for advanced users who want to dig deeper into Kirby’s internals. Use, wherever you feel that the explanation of a particular term might be beneficial to the reader. Repeated terms on a single parge should not be given a glossary tag on every occurence.

The example below uses glossary entry’s title as text:

(glossary: kirbytext)

You can also add a custom text (useful for adding the tooltip to conjugated words):

The (glossary: Panel text: Panel’s) interface has been completely re-designed for Kirby 3.

Example

You can find more information about the Panel in our docs.

(screenshot: …)

Inserts a screenshot. It shares all attributes with the (image: …) KirbyTag, but has a drop-shadow to make screenshots with a light background stand out more from the background. Ideally, screenshots should be taken at 2× resolution (also known as HiDPI or retina resolution) to ensure that screenshots appear crisp on all devices.

(screenshot: ui.png)

If you don’t want a screenshot to span the whole width of the text colum, consider to add the width attribute for setting a maximum width for the image.

(screenshot: ui.png width: 600)

Example

File structures

If you want to visualize the contents of a directory, use our filesystem Markdown extension for generating a nice infographic of the file structure. The filesystem component is used by inserting a fenced code block and setting filesystem as the code language. Directories are marked by a slash / the the end of the line, files just use their full file name including the extension. Use 2 spaces of indentation to nest files and folders. The filesystem component will add the corresponding icons to every folder and file for most common file extensions. For indicating omissioned files and folders, use ... or , the corresponding item is displayed without an icon.

```filesystem
assets/
  css/
    styles.css
  fonts/
    robotron.woff2
  …
  images/
    logo.svg
    background.jpg
  js/
    main.js
kirby/
site/
  templates/
    default.php
```

Example

  • assets
    • css
      • styles.css
    • fonts
      • robotron.woff2
    • images
      • logo.svg
      • background.jpg
    • js
      • main.js
  • kirby
  • site
    • templates
      • default.php

Info & Warning boxes

If an article or section requires the user to pay specific attention to certain requirements, pitfalls or to provide further information on a subject, you can add info and warning boxes to separate these pieces of information both visually and semantically from the regular text. Use the <info> and <warning> HTML-style tags to mark up these blocks. Markdown is supported inside, so you can use all features of Markdown and even Kirbytags to style the content of these boxes. The parser transforms these tags into the corresponding HTML structure.

<info>
You need to setup a **local development environment** for installing Kirby. There are a ton of options availale, each of them comes with its individual benefits and pitfalls.
</info>

<warning>
Before updating your Kirby installation, always create a fresh backup first.
</warning>

Example

Available Icons

The table below gives an overview of all icons available on the site. This section is mostly aimed at template developers and/or contributors who want to make suggestions to style updates.

Preview Name Size
algolia 150 × 38
archive 16 × 16
arrow-big-left 32 × 32
arrow-big-right 32 × 32
arrow-left 24 × 12
arrow-right 24 × 12
audio 16 × 16
bug 16 × 16
cart 16 × 16
check 16 × 16
chevron-left 5 × 11
chevron-right 5 × 11
code 16 × 16
composer 16 × 16
copy 16 × 16
css 16 × 16
document 16 × 16
download 16 × 16
file 16 × 16
folder-collapsed 16 × 16
folder-expanded 16 × 16
font 16 × 16
git 16 × 16
github 20 × 20
guide 16 × 16
gulpfile 16 × 16
html 16 × 16
image 16 × 16
info 16 × 16
instagram 16 × 16
javascript 16 × 16
keycdn 150 × 44
link 18 × 18
markdown 16 × 16
php 16 × 16
readme 16 × 16
sass 16 × 16
search 16 × 16
star-outline 16 × 16
star 16 × 16
text 16 × 16
twitter 20 × 20
video 16 × 16
wand 16 × 16
warning 16 × 16
yaml 16 × 16