Help Build Pipeline

Help is compiled before the request, never during it. ui5:help reads every module's documents and the views that name them, validates both, and writes static HTML, a table of contents and a search index into storage/. The runtime only serves files.

The command

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

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. Every UUID-named folder under the doc/ of a module with #[Help], whether anything names it or not (Concept).

The table of contents lists one block per module root: title, description, and a link carrying the document's UUID. Below it come the module's other documents, as links sorted by title. There is no third level, 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, warning is worth reading and leaves the exit code alone, error fails the command and suppresses all writing. Every locale file is parsed, so a broken translation is caught here and not in the render pass.

Condition	Level	What happens
a module has no #[Help]	info	the module's documents are not compiled
an app without #[Help] has documents in doc/	warning	not compiled: no locale, no root
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's folder is missing	error	reported; the module's other documents still compile
a folder under doc/ is not named after a UUID	warning	not compiled
a folder holds no *.md at all	error	that document skipped
the same UUID lies in two modules	error	names both folders; the second is skipped
the authoring locale's file is missing in the folder	error	that document skipped
that file has no frontmatter	error	that document skipped
a file in any locale cannot be parsed, or has unparsable frontmatter	error	names the file
an image path with a slash in it, in any locale	error	names the file and the path
an image path starting with ../	warning	it stays as written, and nothing serves it
title or description missing	error	that document skipped
description: TBD	warning	compiled; the table of contents and the search show it
a secondary locale has no frontmatter	warning	compiled
a Markdown file not named after a locale	warning	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
a view cannot be parsed	error	names the file
a literal uuid in a view is no valid UUID	error	names the view
a literal uuid in a view has no document	error	names the view and the folder it expected
a literal uuid in a view belongs to another module	error	names the view and both modules
a literal uuid in a view names a document in a module without #[Help]	error	names the view and the module

What passes in silence

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

• A bound uuid in a view. uuid="{help_uuid}" names a column, not a document; the value comes from a catalog row, and that row is validated on its own.
• A package without Component-preload.js. Its views cannot be read, and the build notes that as info.
• Unknown frontmatter keys. There is no schema.

In a deployment

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).

Removing a document is safe: --build deletes the output of every document that no longer exists. Run --all, so that index.json follows.

See also

• Concept: what a document is, and which UUIDs get compiled
• Authoring: frontmatter, Markdown, links and assets
• Runtime: the endpoints that serve what this writes
• Artisan Commands: ui5:help and ui5:doc among the rest