Download the PHP package medienbaecker/kirby-help-view without Composer

Kirby Help View

A Kirby plugin that adds a help view to the Panel for your clients.

Features

• Custom Panel area with help articles
• Supports categories with nested articles
• KirbyText in articles (links, images, formatting)
• Render real Panel buttons, boxes and icons inside articles
• Icons and colors for each article card
• Previous/next navigation between articles
• Breadcrumbs for nested articles
• Multilanguage support

Content Structure

Create a site/help folder with your articles:

• Number prefixes (1_, 2_) control the order
• Folders with article.txt become articles
• Folders without article.txt but with subfolders containing articles become categories. You can add an optional category.txt to overwrite the title.
• For multilanguage support, add language codes to filenames (e.g. article.de.txt). Depending on the user's Panel language, the appropriate article version will be shown.

Seems familiar, doesn't it? I tried to keep it close to Kirby's content structure while also keeping it out of the actual site content so you don't accidentally expose help articles on the public site.

Example article

You can define an icon from Kirby's icon set and colors from the Kirby color variables.

Example category

If you don't add a category.txt, the folder name will be used as the title (e.g. "2_editing" → "Editing"). If you're not having to deal with German Ümläuts (or other fancy characters) in your folder names, don't worry about it.

Panel buttons, boxes and icons

To make your documentation match what clients actually see, you can drop <k-button>, <k-box> and <k-icon> straight into your articles. They render as the real Panel buttons, boxes and icons, reusing Kirby's own styles and icon set, so they always look like the real thing.

Buttons

Because they render as Kirby's own buttons, the Kirby Lab is the live, visual reference for the icons, themes, variants and sizes you can use. All attributes are optional:

• icon – any icon name from the icon set
• theme – a button theme like positive, negative, info or notice. For page status buttons use the -icon variants: negative-icon (draft), info-icon (unlisted), positive-icon (listed).
• variant – filled (default) or dimmed
• size – xs, sm, md, lg (default md)
• link – turns the button into a link. Reference a file in the article's folder by name (e.g. link="template.zip"), just like the (image:) and (file:) tags. Relative URLs (e.g. /panel/site), mailto:, tel: and external links also work; external links open in a new tab.
• download – on a button that links to a file, saves it under its original filename instead of opening it in the browser
• title – accessible label for an icon-only button, e.g. <k-button icon="add" title="Add"></k-button> (matches Kirby's k-button; not needed when there's visible text)

Ideally put buttons on their own line. Avoid placing one in the middle of a sentence – a button is taller than your text and will disrupt the line height.

Boxes

Boxes look like Kirby's info field and are handy for tips, warnings and other callouts. Their content is KirbyText, so formatting, links, images and buttons work inside.

Both attributes are optional:

• icon – any icon name from the icon set
• theme – a box theme like info, positive, negative, notice or warning. Without a theme the box has no background, just like Kirby's k-box.

Put boxes on their own lines with an empty line before and after. Boxes can't be nested. Like Kirby's info field, they are made for a sentence or two: longer content with headings or lists is better placed outside the box.

Icons

Icons are inline and decorative by default (aria-hidden). When an icon carries meaning, add alt so screen readers announce it:

Use any name from the icon set.

Options

Notes

• The help menu item only appears if the site/help folder exists.
• Help articles are trusted content (like your templates) – any HTML in them is rendered as-is.

Requirements

Kirby 5.2.0 or higher (I'm using the new Str::label() method)

Installation

Composer

Manual

Download and copy this repository to site/plugins/kirby-help-view.

Credits

kirby-helpsection by amteich was the original inspiration for this plugin. I've been using it for years and my clients loved it. Unfortunately it has not been updated since 2021 and is not compatible with Kirby 5, so I created this new version from scratch, trying to stick to core components as much as possible.