Plugin Help

Overview

A plugin package can ship a user guide that the Racona Help app displays:

• The plugin’s pages appear in the Help table of contents under the plugin’s name, after Applications.
• The help button (?) appears in the plugin window’s title bar and opens the main page of the plugin’s help.

No permission or manifest field is needed: a help/ folder in the package is enough.

Help or knowledge base?

help/ is for users: a readable guide with illustrations. knowledge-base/ is for the AI assistant: short, keyword-rich sections. Both can contain the same text, but the folders are packaged separately.

Folder Structure

my-app/
├── manifest.json
└── help/
    ├── hu/
    │   ├── index.md          # main page: the help button opens this
    │   ├── projects.md
    │   └── settings/
    │       └── notifications.md
    ├── en/
    │   └── index.md
    └── assets/
        └── projects-list.webp

• Main page: help/<locale>/index.md. Without it, the help button opens the first page in order.
• Languages: locale folders are named by language code (hu, en). Help uses the interface language if the plugin ships content for it; otherwise Hungarian, and finally any available language is shown. Writing in one language is enough.
• Subfolders: allowed; in the menu the plugin’s pages appear in a single list ordered by sidebar.order.
• Files: only .md pages and images (png, jpg, jpeg, gif, webp, svg), at most 10 MB in total. Any other file makes the installation fail.
• Single page: if the plugin ships only one page, the menu shows a single item with the plugin’s name instead of a group.

The build-package.js generated by the CLI (bun run package) includes the help/ folder. For an older plugin, add it to the packaged folders:

build-package.js

if (existsSync(join(ROOT, 'help'))) entries.push('help');

A Page

help/en/projects.md

---
title: Projects
description: Creating and managing projects
sidebar:
  order: 2
---

You manage projects in the **Projects** menu.

![Project list](../assets/projects-list.webp)
_The project list with filters_

## New Project

1. Click **New project**
2. ...

See [Notifications](./settings/notifications.md) for notification settings.

• title is the menu item and page title, description is shown as a subtitle, sidebar.order sets the order (index.md comes first by default).
• Don’t repeat the page title as a # heading; start the text at ## level.
• An italic line right after an image is shown as its caption.

Links and Images

Target	How	Example
Another page of the plugin	relative path, with or without .md	./projects.md, ../index.md
A heading	# + the lowercase, hyphenated heading	./projects.md#new-project
The built-in Racona help	/en/user/... path	/en/user/ui-components/data-tables/
An external page	full URL, opens in a new browser tab	https://example.com
An image	path relative to the Markdown file, inside help/	../assets/projects-list.webp

Links that cannot be resolved are shown as plain text.

Access

A plugin’s help is visible only to users who can access the plugin: the same rules decide as for the app list (role, group, public app). A disabled plugin’s help is hidden, and the server does not serve its files either.

Permissions inside the plugin (e.g. requiredCapability in the menu) do not filter the help: anyone who can access the plugin can read all of its help. If a feature is only available to certain roles, say so on the page.

Lifecycle

• Install, update, uninstall: the Help table of contents refreshes after these actions in the Plugin Manager, and reloads every time a Help window opens.
• Dev mode: help for a plugin loaded on the Dev Plugins tab is not shown yet; try the help with the installed package.