Getting Started

In-app help widget

Add permission-aware help to your application with one Blade component.

Docent can open your help center in a compact panel inside the application it documents. The panel is a same-origin iframe, so it receives the same session cookie and runs through the same middleware, gates, audiences, conditions, and dynamic values as the full documentation site.

You can try the widget on the reference page.

Add the launcher

Enable the widget, then place the Blade component near the end of your application layout:

blade

<body>
    @yield('content')

    <x-docent::widget />
</body>

Nothing is injected automatically. Pages that do not render the component do not load the launcher runtime.

On a multi-site install, the site attribute picks which documentation site the widget opens. Omit it and the widget uses your default site. Two widgets on the same host page can target different sites:

blade

<x-docent::widget site="public" />

Configuration

php

'widget' => [
    'enabled' => true,
    'mode' => 'overlay',       // overlay or push
    'position' => 'right',     // right or left
    'offset' => 24,
    'launcher' => 'button',    // button or none
    'icon' => 'book-open',
    'preload' => false,
],

overlay floats a 400-pixel panel above the page. On screens narrower than 640 pixels it becomes a full-screen sheet.

push docks the panel to one side and adds a matching margin to the document root, allowing ordinary page content to reflow beside it. Fixed-position and viewport-width elements may not move with that margin, so test your own headers, drawers, and application chrome before enabling push mode.

The icon can be any bundled Heroicon name or an absolute path or URL to an image. Set launcher to none when your application supplies all of its own triggers.

Open help from your interface

Any element can open the widget home or jump straight to an article:

html

<button data-docent-open>Help</button>
<a href="#" data-docent-article="billing/refunds">Refund help</a>

The global API covers the same actions:

Docent('open')
Docent('close')
Docent('toggle')
Docent('navigate', 'billing/refunds')
Docent('search', 'refunds')

Calls made before the deferred widget script finishes loading are queued and replayed automatically.

Suggest guides for the current screen

Register the guides that are most useful in a part of your application. The first argument is a page identifier pattern; * works as a wildcard.

php

use STS\Docent\Facades\Docent;

Docent::suggest('billing.*', [
    'billing/overview',
    'billing/payment-methods',
]);

Suggestions registered this way apply to every site. Use Docent::site('public')->suggest(...) when a suggestion only makes sense for one site's widget.

The launcher captures the current route name on its own, so a classic Blade application needs nothing more: render a page on a billing.* route and the matching guides appear under "Suggested for this page" on the widget home. For SPA or Livewire navigation, tell the widget where the visitor is:

Docent('page', 'billing.invoices')

You can also hand the widget an explicit list, which wins until the next page call:

Docent('suggest', ['billing/refunds', 'billing/payment-methods'])

Docent checks every suggested guide against the current viewer before returning it, so a suggestion never bypasses a gate or audience rule, and docent:check fails when a registration points at a page that does not exist.

Preloading and analytics

The widget frame loads on first open. Set preload to true and Docent loads it hidden while the browser is idle instead, which makes the first open feel immediate at the cost of an extra request on pages where nobody opens help.

Widget activity is exposed as a browser event. Docent does not send it to an analytics service for you:

window.addEventListener('docent:analytics', ({ detail }) => {
    analytics.track(detail.event, detail)
})

Events cover opening and closing the widget, readiness or load failure, page context changes, article views, searches, search-result clicks, and suggestion clicks.

Links and search results inside the panel stay in its compact chrome. "Full docs" opens the current article in the normal documentation layout. Escape and the close button return focus to the control that opened the panel.