Content styleguide

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.js, 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 Markdown 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 for the reader.

Data types in inline code

Our custom Markdown extension automatically handles highlighting of atomic data types and classes available in PHP. In addition to that, Kirby’s built-in classes will get highlighting applied and linked to their respective entry in the Reference. The latter only works if the class name contains the fully-qualified name including namespace (i.e. contains at least one backslash \ character). All class names must be specified case-sensitive. If that also fails, the highlighter assumes given inline code is not a data type or class name. You can also specify multiple types by separating them with a pipe | character. Any inline code that does not solely consist of alphanumeric characters, underscores _ and backslashes \ is considered to be not a data type.

Use a string `string` or `int` as parameter.

The `Kirby\Cms\Page` class is the heart of Kirby.

Return value: `Kirby\Cms\Page|null`

Available data types: string, int, float, bool, object, array, null, mixed

Class examples: Kirby\Cms\Page, Kirby\Toolkit\Str

Multiple data types: Kirby\Cms\Page|null, string|bool

Method calls in inline code

We went one step further to also highlight and link method calls: for class methods, field methods, helpers, e.g. $page->url().

This works either by parsing normal inline code:

Check out `$page->url()`.
Or even `Kirby\Filesystem\F::exists()`

As you can see, class aliases can be used in their short form. All other classes require fully-qualified names including namespace.

Since that might look a little odd, we have added some Kirbytags:

Check out (class: Kirby\Filesystem\F method: exists text: ->exists()).
And then (method: Kirby\Filesystem\F::size text: $myFile->size()).

And it does work: ->exists() and $myFile->size().

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

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.

const gallery = document.querySelector('.js-gallery');

$gallery = new Gallery('My Gallery', ['imagesPerRow' => 5]);

<div class="gallery / js-gallery">Please enable JavaScript to view the gallery.</div>

.gallery-error {
  color: #ff0000;
}

gallery:
  imagesPerRow: 5
  images:
    - image1.jpg
    - image2.jpg

npm run gallery-server

# 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 a 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 escape separators in your example (\----).

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 ( to prevent the parser from interpreting that particular tag.

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

Custom KirbyTags

(screencast: …)

Adds a box with a screencast video:

(screencast: https://www.youtube.com/watch?v=EDVYjxWMecc title: How to install Kirby in 5 minutes text: We are using PHP's built-in server to create a simple local development environment.)

Example

Screencast

How to install Kirby in 5 minutes

We are using PHP's built-in server to create a simple local development environment.

This video is loaded from YouTube servers with your consent. Read more…

(glossary: …)

The glossary KirbyTag inserts a link to the corresponding glossary article. 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.

Example

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

(reference: …)

Shows a grid of subpages of a reference page.

(reference: text/kirbytags)

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 with 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 the 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

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** to run Kirby. There’s ton of options available, each of them comes with its individual benefits and pitfalls.
</info>

<success>
Something went really well. Congrats!
</success>

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

<alert>
This is really dangerous. Better know what you are doing.
</alert>

Example

KirbyText groupings

We've added some custom directives to our custom Parsedown parser Marsdown that allow us to group content in various ways.

Columns

You can split your content into a two-column grid by wrapping the group with (columns…) and (…columns). To separate each column, use ++++ as divider:

(columns…)

Column 1

++++

Column 2

(…columns)

Example

Tabs

Similarly, you can organize content in tabs by wrapping it in (tabs) and (tabs). Each content section that should create its own tab needs to start with === followed by the tab title:

(tabs…)
=== Tab title 1
Tab content 1

=== Tab title 2
Tab content 2

=== Tab title 3
Tab content 3
(…tabs)

Example

Since version

To signal that content refers to a specific Kirby version or that the feature was only added in a specific version, wrap the content in a <since> tag:

<since v="4.0.0">
A feature that got added in Kirby 4.0.0
</since>

Example