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:
- 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.
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.
$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.
Available data types:
Multiple data types:
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.
This works either by parsing normal inline code:
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:
And it does work:
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:
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.
Common programming languages
The examples shown below list all programming languages supported by the syntax highlighter:
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 (
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.
Adds a box with a screencast video:
How to install Kirby in 5 minutes
We are using PHP's built-in server to create a simple local development environment.
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:
You can also add a custom text (useful for adding the tooltip to conjugated words):
You can find more information about the Panel in our docs.
Shows a grid of subpages of a reference page.
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
…, the corresponding item is displayed without an icon.
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
<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.
You need to setup a local development environment to run Kirby. There’s a ton of options available, whereas each of them comes them with its individual benefits and downsides.
Something went really well. Congrats!
Before updating your Kirby installation, always create a backup before changing any files.
This is really dangerous. Better know what you are doing.