Beacon Widget

The beacon is a lightweight (~47KB) Preact widget that you can embed on any website. It gives your users instant access to help articles, product updates, and a contact form without leaving your app.

Installation

Add two script tags to your site's HTML, just before the closing </body> tag:

<script>
  window.MarkdeskConfig = {
    helpCenterUrl: 'https://help.example.com',
    title: 'Help',
  };
</script>
<script src="https://help.example.com/beacon.js" async></script>

Replace https://help.example.com with your deployed help center URL.

Configuration options

Option	Default	Description
helpCenterUrl	—	The URL of your deployed Markdesk help center (required)
title	'Help'	Title shown in the beacon panel header
position	'bottom-right'	Position of the beacon button: 'bottom-right' or 'bottom-left'
autoShowModal	true	Automatically show product update modals. Set to false to control manually

JavaScript API

Once loaded, the beacon exposes a global Markdesk object with these methods:

Markdesk.open(tab)

Open the beacon to a specific tab:

Markdesk.open('answers')  // Help articles and search
Markdesk.open('updates')  // Product updates
Markdesk.open('ask')      // Contact form

Markdesk.close()

Close the beacon panel.

Markdesk.toggle()

Toggle the beacon open or closed.

Markdesk.identify({ email })

Pre-fill the contact form with the user's email address:

Markdesk.identify({ email: 'jane@example.com' });

Markdesk.showModal()

Enable the product update modal. Only needed when autoShowModal is set to false in the config. Use this to defer the modal until your app is ready — for example, after login:

Markdesk.identify({ email: user.email });
Markdesk.showModal();

Markdesk.article(slug)

Open a specific help article by its slug:

Markdesk.article('getting-started-guide')

This is useful for contextual help — for example, linking a "Learn more" button directly to a relevant article.

Product update modals

When a product update has showModal: true in its frontmatter, the beacon can display it as a popup notification. By default (autoShowModal: true), this happens automatically for all visitors.

If you want to control when modals appear — for example, only after a user logs in — set autoShowModal: false in your config and call Markdesk.showModal() when ready.

Dismissals are stored in localStorage. Updates older than 6 months are never shown as modals.

What's in the beacon

The beacon has three tabs:

• Answers — Searchable list of help articles. Users can search by keyword and read articles inline.
• Updates — Product changelog with category badges. New updates can appear as popup notifications.
• Ask — Contact form that sends messages to your configured email address.

CORS setup

If the beacon is embedded on a different domain than your help center, add that domain to allowedOrigins in markdesk.config.ts:

allowedOrigins: ['example.com', 'app.example.com'],

This allows the beacon to fetch articles and submit the contact form from your app's domain.