Help Build Pipeline

Help is compiled before the request, never during it. ui5:help reflects every module's #[Help] declaration, validates the documents behind it, and writes static HTML, a table of contents and a search index into storage/. The runtime only serves files.

The command

bash

php artisan ui5:help            # validate; write nothing
php artisan ui5:help --build    # validate, then write the HTML documents, their assets and toc.html
php artisan ui5:help --index    # validate, then write index.json
php artisan ui5:help --all      # validate, build, index — what a deployment runs

Flag	Reads	Writes
(none)	the registry's modules, each module's `doc/` folder	nothing
`--build`	the compiled model, every locale file, every non-Markdown file in each folder	`storage/ui5/help/{uuid}/{locale}.html`, the copied assets, and `storage/ui5/help/toc.html`
`--index`	the compiled model, each authoring-locale file	`storage/ui5/help/index.json`
`--all`	all of the above	all of the above — including the deprecated `--cache`, which writes a manifest nothing reads
`--cache`	the compiled model	`bootstrap/cache/ui5-help.php` — deprecated, nothing reads it; removed in `2.0`

Two things about --validate: it is the default, and it is not a mode you can switch off. Validation runs on every invocation, and one error stops everything before a single file is written — so a failed run never leaves you with half-compiled help. The command's exit code is non-zero in that case, which is what makes it usable as a CI gate.

--build and --index are independent; you may run either alone, and the order between them does not matter.

What lands where

storage/ui5/help/
├── index.json                     ← the search index
├── toc.html                       ← the table of contents
└── 8f3e6b1c-…/
    ├── en.html
    ├── de.html
    └── states.png                 ← copied verbatim

The documents. One HTML file per locale found in the folder, rendered from Markdown with the help extensions and with internal links, external links and image sources rewritten (Authoring). The UUID's output directory is deleted and rebuilt on every run, so a locale you removed disappears from it.

Which documents. The ones something declares: each module's #[Help] root and every Customizing entry's helpUuid. The compiler does not read your views, so a UUID that only a Context control names is not among them (Concept).

The table of contents lists one block per module root — title, description, and a link carrying the document's UUID — and nothing else. It is flat: a catalog row's document is reached through its row and through search, not from here, and a module without #[Help] is not in it at all.

The index is a bare JSON array, one object per document, authoring locale only:

Field	From
`uuid`	the folder
`title`, `description`, `tags`	the frontmatter
`text`	the body, flattened to plain text

Worth knowing about text, because it decides what search can find: it is assembled from the document's inline text only. Code spans and fenced code blocks do not make it in, and neither do link URLs. So a topic that a reader will search for by a command name or a config key needs that term in prose too, not only inside backticks.

Every message the compiler can give you

info is a note, error fails the command and suppresses all writing. There is no middle: the domain never warns.

Condition	Level	What happens
a module has no `#[Help]`	info	the module is skipped; its `doc/` folder is never looked at
a module has more than one `#[Help]`	error	module skipped
`#[Help]` has an empty locale	error	module skipped
`#[Help]`'s UUID is not a valid RFC 4122 identifier	error	module skipped; the message points at `ui5:doc`
the module has no `doc/` directory	info	module skipped
the root UUID is declared but its folder is missing	error	reported; the module's other documents still compile
a declared folder holds no `*.md` at all	error	that document skipped
the authoring locale's file is missing in the folder	error	that document skipped
that file has no frontmatter	error	that document skipped
that file has unparsable frontmatter	uncaught exception	the whole command stops
`title` or `description` missing	error	that document skipped
a catalog row's `helpUuid` is not a valid UUID	error	that row's help ignored
a catalog row's `helpUuid` has no document	error	reported, with the path it expected
a catalog row's `helpUuid` belongs to another module's document	error	reported — catalog help must live in the declaring module

What passes in silence

The list above is what the command tells you. This is what it will not:

An undeclared folder. A document that neither a module root nor a catalog row names is not reported at all — not even as a note. That includes a document a view binds with a literal uuid: the compiler never reads views. If your document seems not to exist, this is the first thing to check (the declaration rule).
A nonsense locale. notes.md compiles to notes.html.
Missing frontmatter in a secondary locale. Only the authoring locale is inspected.
Placeholder content. description: TBD is a valid description.
Any uuid in a view, literal or bound. A literal one is the undeclared folder above. A bound one, uuid="{help_uuid}", names a column, not a document; the value comes from a catalog row, and that channel is validated on its own.
Unknown frontmatter keys. There is no schema.

And two authoring mistakes surface as an exception rather than a diagnostic, after validation has already passed: an image path with a slash in it, and an unreadable or unparsable file during the render pass.

In a deployment

bash

composer install --no-dev --optimize-autoloader
php artisan migrate --force
php artisan ui5:sync
php artisan ui5:help --all
php artisan ui5:publish

ui5:help belongs in every deployment, not only when help changed. Its output lives in storage/, which is not in your repository, so a fresh checkout or a new release directory has none of it — and without it help is simply unavailable: F1 reports that instead of opening, and search finds nothing. The rest of the shell comes up regardless (LeanShell Overview).

One caveat to keep in mind when you remove things: the command rebuilds each document it compiles, but it does not prune. Delete a document, or drop the declaration that named it, and the previously compiled HTML stays in storage/ and stays served. Clear storage/ui5/help/ before a release if you have removed topics.

Help Build Pipeline ​

The command ​

What lands where ​

Every message the compiler can give you ​

What passes in silence ​

In a deployment ​

See also ​