# On-Screen Help > How to make the admin's on-screen help describe your installation: amend or replace the note on any screen, add your own articles in a Customizations section… Source: CBX documentation, version 4.0 preview (unreleased). Canonical page: https://docs.configbox.at/docs/4.0-preview/customization/help_customization. Last updated 2026-08-03. --- How to make the **admin's on-screen help** describe *your* installation: amend or replace the note on any screen, add your own articles in a **Customizations** section of the guide, and shadow a shipped article entirely. Nothing here touches core, and none of it is overwritten by an update. This is the counterpart to the fields you add. A heavily customized product or question form is only half-delivered if the help drawer still describes the stock screen. Read `com_configbox_customization_overview.md` first. All paths are relative to the customization directory, `KenedoPlatform::p()->getDirCustomization()` — Joomla `data/customization/`, WordPress the separate customization plugin, Magento the `ConfigboxCustomizations` module. --- ## 1. Where it goes Everything lives under **one folder**, `help/`, whose layout mirrors the guide's — so there is no second convention to learn: ``` /help/ _screens/ adminquestions.md amend or replace that screen's note img/ our-fields.png images for screen notes customizations/ _category_.json the section's label and position README.md its landing page our-workflow.md your own articles img/ workflow.png settings/ tour-the-settings-sections.md SHADOWS the shipped article at that path img/ our-settings.png ``` Three capabilities, one folder: | You want to… | Put a file at | Result | |---|---|---| | Add to a screen's help | `help/_screens/.md` | Appended below the shipped note | | Replace a screen's help | the same, with `mode: replace` | Yours instead of the shipped note | | Add your own articles | `help/customizations/*.md` | A **Customizations** section in the guide | | Take over a shipped article | `help//.md` | Yours is served; core's is not | **Images live with the content that uses them.** A customization file's images resolve against the customization directory, so `![](img/our-fields.png)` in `help/_screens/adminquestions.md` means `help/_screens/img/our-fields.png`. You never reference the component's folders, and the component never reaches into yours. --- ## 2. Amending a screen note The help drawer shows a short **screen note** above the linked article. To document fields you added, drop a file named after the screen's controller: ```markdown ## Fields added by this project - **Minimum width (mm)** — refuses a configuration narrower than this. Leave empty for no minimum. - **Cut-length warning** — shows the customer an advisory when a part would be under 250 mm. ![The added fields](img/our-fields.png) ``` That is the whole file. **No front matter is needed** — the default is to append, which is what you almost always want: the shipped note is still true, you are adding to it. The appended block is wrapped in `.cb-help-note-customization`, so a site that wants it to read as one voice with the shipped note can style or hide it. ### Replacing instead When the screen has been reworked enough that the shipped note is misleading: ```markdown --- mode: replace title: Questions (this store) --- Our question forms differ from stock CBX — start with the workflow article. ``` `mode: replace` drops the shipped note entirely. `title` and `article` override the shipped values where you set them, so you can retitle the screen or point its "read more" at your own article. > **Prefer append.** A replaced note is a copy of core's that will rot: the next CBX version > improves the shipped note and your replacement silently keeps the old story. Replace only when > the shipped note is actually *wrong* for your install. ### Which filename? The screen's **controller** name — `adminquestions`, `adminproducts`, `adminconfig`. A form view (`adminproduct`) shares its controller's note, exactly as core notes do, and you can also name the view specifically if you want a note on the form but not the list. You can also document a screen core says nothing about; your note then stands alone. --- ## 3. Your own section: `customizations/` Anything in `help/customizations/` becomes a **section of the guide**, listed beside Products, Pricing and the rest, and included in the help area's search. ```json // /help/customizations/_category_.json { "label": "Acme customizations", "position": 50 } ``` `position` orders it against the shipped sections (they run 1–8, so a high number puts yours last; omit it and it sorts after them anyway). Articles use the same front matter as the guide: ```markdown --- sidebar_label: Our order workflow sidebar_position: 2 description: How orders move through Acme's approval steps. --- # Our order workflow Orders here pass an approval step before they are released... ![The approval panel](img/approval.png) ``` `README.md` becomes the section's landing page. Write these the way the shipped guide is written — the authoring standard in `docs/admin-guide/_authoring-standard.md` applies, and it is also exactly the construct set the in-admin renderer supports. **Link a screen at one of your articles** by naming it in the screen note's front matter: ```markdown --- article: customizations/our-order-workflow.md --- ``` --- ## 4. Shadowing a shipped article Put a file at the **same path** a shipped article uses and yours is served instead: ``` /help/settings/tour-the-settings-sections.md ``` The guide still lists one article at that path — yours. Its images resolve against your directory, and it is indexed for search in place of the original. > **This is the sharpest tool here.** A shadowed article no longer benefits from anything CBX > improves in it, and nothing announces that to the reader. Shadow when the shipped article is > actively wrong for your install; otherwise a `customizations/` article that links to the > shipped one ages far better. --- ## 5. Deployment checklist 1. Create `/help/` and the files you need. 2. Put images in an `img/` folder **beside the file that uses them**. 3. Open the screen in the admin and check the drawer; open **Help** in the CBX menu for the section and article views. 4. Search the help area for a phrase from your article — new articles are indexed automatically. No cache clear, no registration, no database entry: the files are read at request time. --- ## 6. Gotchas - **Append is the default; `mode: replace` is opt-in.** A note with no front matter appends. - **Only `.md` files are served**, and only from inside `help/` — paths are resolved with `realpath()` and anything escaping the folder is refused. Help paths arrive from request variables, so this matters. - **Images belong to their own layer.** A customization file cannot reference the component's images with a relative path, and does not need to: keep your own in your `img/` folders. - **The renderer is the guide's, not Markdown at large.** Headings, paragraphs, lists, tables, blockquotes, fenced code, images, emphasis, inline code and relative links. **No inline HTML.** - **Shadowing hides core silently.** Nothing warns the reader that they are not seeing the shipped article — see §4. - **A replaced note loses core's front matter** unless you restate it: if the shipped note pointed at an article and yours does not, that link disappears. ## See also - `com_configbox_customization_overview.md` — the layer, and where it lives per platform - `com_configbox_custom_properties.md` — the fields you are documenting - `com_configbox_language_overrides.md` — changing shipped *text* rather than adding help - `docs/admin-guide/_authoring-standard.md` — how the shipped guide is written, and the construct set the in-admin renderer supports (underscore-prefixed, so it is not published to the docs site)