LaravelUi5
Get Started

Help Runtime ​

At runtime, the help system serves pre-rendered HTML and a plain JSON search index. There is no Markdown processing on the request path; everything happens at build time.

Endpoints ​

MethodPathControllerReturns
GET/ui5/help/{uuid}/{name}Http\Controllers\HelpControllerHTML, images, diagrams
GET/ui5/help/index.jsonHttp\Controllers\HelpIndexControllerSearch index (JSON array)
GET/ui5/help/toc.htmlHttp\Controllers\TocControllerHelp table of contents

All three live in routes/ui5-sdk-web.php under Core's /ui5 route prefix. They run a plain ['web', 'auth'] middleware stack, not config('ui5.middleware'): help is global, not scoped to a UI5 artifact, so any signed-in user can read it.

index.json and toc.html return 404 until ui5:help --index and ui5:help --build (or --all) have written them.

How a request resolves ​

  1. The frontend asks for GET /ui5/help/<uuid>/<name>.
  2. HelpController serves storage/ui5/help/<uuid>/<name>.html if it exists — name read as a locale.
  3. Otherwise it serves storage/ui5/help/<uuid>/<name> as an asset.
  4. Otherwise it returns 404.

In practice the LeanShell asks for en.html, not en: it appends the extension itself. So a document resolves through step 3, the asset branch, and both branches end at the same file. Worth knowing before you "fix" either side — a change on one of them has to move the other.

There is no cache lookup and no server-side locale fallback: a locale that was not compiled is a 404. The locale is chosen on the client. When a link carries no locale, the LeanShell uses helpManager.defaultLocale from the shell manifest (ui5.shell.manifest, default en).

Asset resolution ​

Images and other static assets referenced from a topic are served through the same HelpController endpoint. Put them in the topic folder next to the Markdown and reference them with a relative path. ui5:help --build copies them to storage/ui5/help/<uuid>/ and rewrites the image URL to /ui5/help/<uuid>/<file>.

Search index ​

index.json is the plain array written by ui5:help --index, one entry per document in the primary locale:

  • uuid
  • title
  • description
  • tags
  • text: plain text of the body

It is not a prebuilt Lunr index and carries no locale field. The LeanShell fetches it once and builds a Lunr index in the browser. Search is part of the <help-viewer> component; there is no separate search component. Search results open in the default locale. No server-side full-text engine is required.

Performance ​

The runtime is intentionally trivial:

  • HTML responses are pre-rendered files → no Markdown parsing
  • the search index is a static JSON file and Lunr runs in the browser → no server-side query engine

This is what makes the help system viable in shells where F1 must respond instantly.

See also ​