Render Help Articles Inside Your Own Website (Headless)

Your website already has a design, navigation and search of its own. With headless hosting, your site fetches your Helpdesky articles through the public Content API and renders them inside its own templates, at an address such as comparekit.app/help/getting-started. You keep writing in the Helpdesky editor, and the widget, Ask AI and the dashboard keep working. Your site owns the page around the article.

This guide covers when headless is the right choice, the quickest way to set it up (a prompt for an AI coding agent), the Content API calls and the stylesheet for developers who prefer to write the code themselves, the SEO rules, the Check setup and Make it live steps, and a reference of the HTML your site receives.

Headless or subfolder?

Both options put your help center on your own domain, which is the strongest setup for search rankings. The difference is who renders the page.

• Subfolder. Your website forwards yourdomain.com/help/* to Helpdesky with one proxy rule, and Helpdesky renders the complete page: layout, navigation, search, sitemap and 404s. Setup takes about half an hour for someone with access to your hosting or Cloudflare settings. No code changes on your site.
• Headless. Your website calls the Content API and renders the articles itself. You get your own header, footer, fonts, navigation and search, and the article body keeps every Helpdesky feature (callouts, action cards, numbered headings, embeds) through a small stylesheet. In return you own the routes, the sitemap entries and the 404 pages. Expect an afternoon of work for a developer, or well under an hour with an AI coding agent that can edit your site.

Compared with a custom domain (one DNS record, no developer needed) and a subfolder (one proxy rule, hosting access needed), headless is the most work and gives the most control. Pick it when the help center must look and behave like the rest of your site, or when your site already has a search and navigation you want the help pages to join.

Quickest path: ask an AI coding agent

The Domain & Address page writes the integration instructions for you.

1. In your Helpdesky dashboard, open Help Center → Domain & Address. In the Hosting card, choose Headless (your own templates).
2. Under Public address, enter the address where your site will render the help center, for example https://comparekit.app/help, and click Save address. Articles will live at this address followed by /<article-slug>.
3. The card now shows Ask an AI coding agent to build it with a prompt filled in with your values: your help center slug, the Content API address, the stylesheet, your public address and the link to the spec. Click Copy prompt.
4. Paste the prompt into the agent that works on your website (Replit, Cursor, Lovable, Bolt, Claude Code and similar tools all work). The prompt tells it to read the spec at https://helpdesky.io/docs/headless.md, add the three routes inside your existing layout, return your own 404 page for unknown slugs, set canonical tags, add the pages to your sitemap and report back.
5. Deploy your site, then come back, click Check setup and confirm with Make it live (see below).

Do it by hand: the Content API

If you would rather write the code yourself, open Do it by hand in the same card for a Next.js (App Router) and an Express example filled in with your values. The full reference lives at helpdesky.io/docs/api and the agent spec at helpdesky.io/docs/headless.md. The essentials:

• Base: https://helpdesky.io/api/content/v1/helpdesk/<your-slug>. No API key, CORS open, rate limited per IP, responses cacheable for about a minute.
• GET …/categories returns every category with its published articles (title, slug, excerpt, url), plus uncategorized articles and a helpdesk object with the help center’s name, slug and live url.
• GET …/articles lists every published article with updatedAt, which is what your sitemap needs.
• GET …/articles/<article-slug> returns one article: title, slug, excerpt, html, toc, category, authors, showAuthors, numberHeadings, updatedAt and its canonical url. A draft or unknown slug answers 404; a renamed article answers with its new slug, so redirect to it with a 301.
• GET …/search?q= powers an optional search page.

Forward the visitor’s User-Agent and IP (X-Forwarded-For) on article requests so view counts in your dashboard stay accurate.

The stylesheet

Link https://helpdesky.io/api/content/v1/article.css in your <head> and put the html field inside <article class="helpdesky-article">. Every rule in the file is scoped to that class, so it cannot touch the rest of your page. Add the class numbered-headings when the article’s numberHeadings is true. Restyle it with CSS variables on :root: --helpdesky-accent, --helpdesky-text, --helpdesky-font, --helpdesky-radius, --helpdesky-accent-from / --helpdesky-accent-to and --helpdesky-code-bg.

The URL structure

With base as your public address (for example /help), your site must serve:

Route	Data	Page
base/	GET …/categories	Index: each category with its articles, then uncategorized articles
base/<article-slug>	GET …/articles/<article-slug>	Article: breadcrumb, title, optional authors, table of contents, the HTML, last updated
base/category/<category-slug>	GET …/categories	Category: name, description, its articles

Match base/category/<slug> before base/<article-slug>. Keep the slugs exactly as the API returns them: the hosted help center, the widget and the dashboard build links from the same <article-slug> and category/<category-slug> paths, so old links map one to one when you move in or out of headless.

SEO rules your routes must follow

• Canonical tags. Set <link rel="canonical"> to the page’s own address on your site. Once headless is active, Helpdesky points the canonical, Open Graph and JSON-LD tags of the hosted copy at your URLs as well, so Google sees one home for each article.
• Page titles and descriptions. Article pages take their <title> and meta description from the article’s title and excerpt. For the index page use the metaTitle and metaDescription fields that every Content API response carries in its helpdesk object: they are the SEO title and description of your help center from Settings (null when unset, then fall back to " Help Center"), followed by your site name. Title category pages " - " with the category description as meta description. A title made from the path alone, such as "Tutorials", tells search engines nothing about the page.
• Structured data. Mirror the hosted pages: CollectionPage with WebSite JSON-LD on the index, CollectionPage plus BreadcrumbList (index → category) on category pages, and Article or TechArticle plus BreadcrumbList on article pages, built from the API fields (title, createdAt, updatedAt, authors). Every URL in them points at your site.
• Robots. Do not add noindex to help pages and do not block the base path in robots.txt. An explicit index, follow robots meta tag is optional and harmless.
• Sitemap. Add the index, every category page and every article (with updatedAt) to your site’s own sitemap. The hosted sitemap at your Helpdesky address lists your URLs too, but search engines expect to find them on your domain.
• llms.txt. If your site serves /llms.txt (or you are adding one), include a help center section that links the index and every published article as - [title](url): excerpt, grouped by category. Generate it from the categories endpoint so it stays current as you publish, rename and unpublish articles. Mirror it at /.well-known/llms.txt if your site serves that path. The hosted copy at helpdesky.io/help/yourcompany/llms.txt shows the format.
• Root files. Keep the sitemap at yourdomain.com/sitemap.xml and the llms file at yourdomain.com/llms.txt, at the root of the site that renders the help center, even when the help center lives under /help. Once headless is active, a previous help center address (custom domain or subfolder) redirects its old sitemap.xml and llms.txt to those two paths, so crawlers and AI agents that still hold the old address find your lists.
• 404 for unknown slugs. When the API answers 404 (unknown slug or an unpublished article), return your site’s own 404 page with a 404 status. Never a placeholder page, never a redirect to the index. A 410 from the API should be a 410 page.
• Links inside articles. Links to other articles arrive as absolute URLs under the helpdesk.url of the response. Replace that prefix with your base path so visitors stay on your site. Leave image URLs alone: they are served from Helpdesky.

Check setup

Once your pages are deployed, open Help Center → Domain & Address again and click Check setup in the headless card. Helpdesky opens one of your published articles at your address and looks for its title. The check has four steps:

1. A published article to look for. You need at least one published article.
2. Your website answers. The article address must be reachable from the internet.
3. The article page returns HTTP 200. A 404 means the route is not serving that slug yet; a redirect means your route sent the visitor elsewhere.
4. The article title is on the page. Render the title from the API response as the page’s <h1> and <title>.

When all four pass, the result line says your pages are ready and a Make it live confirmation opens. It spells out what changes once you confirm: your headless address becomes the main one; every “View” and “Open” link in the dashboard, the widget’s “open full article” links and the url fields of the Content API use your pages; the hosted pages at helpdesky.io/help/yourcompany keep serving with canonical tags that point at you; and your custom domain or your old subfolder address redirects to your pages path for path. Click Make it live to confirm, or Cancel to leave it for later. Helpdesky runs the same check once more and, if it still passes, the header reads “Your help center is live at” your address. Nothing changes for visitors until you confirm, however many times you run the check, so you can take your time. You can undo it at any time with Remove headless address.

Moving away later

Helpdesky cannot serve redirects from your server, so the redirect rule lives in your routes: every Content API response carries the help center’s live canonical url. When that URL is not on your host, respond with a 301 to it instead of rendering. The agent prompt and both examples include this rule. If you later switch back to the Helpdesky address, a custom domain or a subfolder, your pages start redirecting on their own, with no redeploy. Click Remove headless address in the card and your old address shows up as the previous address with the same banner.

What the article HTML contains

The html field is finished, server rendered HTML, not Markdown. Inject it as HTML and do not sanitize it with a library that strips classes or iframes. It is already sanitized for a foreign origin: no scripts, styles, inline event handlers or forms. Everything authors can create in the editor arrives as one of the elements below. The syntax itself is covered in the Markdown and visual editor guide, Using callout blocks and Enhanced article styling; this table shows what each one becomes on your site.

You author	Your site receives	The stylesheet	Restyle with
Callouts (> [!info], > [!warning], > [!danger])	<div class="callout callout-info"> with callout-warning and callout-danger variants, content in <p>	Tinted box per variant with rounded corners	--helpdesky-radius
Buttons ({.btn} and {.btn-outline})	<a class="btn-block btn-block-primary"> or btn-block-outline, with target="_blank" and rel="noopener" unless the author chose same tab; two or more in a row are wrapped in <div class="btn-row">, a lone button stays in its <p>	Filled or outlined button in the accent colour; the row is a wrapping flex line, so adjacent buttons sit side by side	--helpdesky-accent, --helpdesky-radius, --helpdesky-font
Action cards	<div class="action-card-wrap"><a class="action-card" data-icon="…"> with icon, title and description spans; two or more in a row are wrapped in <div class="action-card-grid">	Card with accent border and icon; the grid is two columns, one column under 640px	--helpdesky-accent, --helpdesky-radius
Numbered headings (article setting)	Plain <h2> elements; the setting arrives as numberHeadings: true	Numbered badge before each H2 when you add numbered-headings to the wrapper	--helpdesky-accent-from, --helpdesky-accent-to
Headings	<h2 id="…">, <h3 id="…"> with unique, URL safe ids that match toc[].id	Heading sizes and spacing	--helpdesky-text, --helpdesky-font
YouTube embeds	<div class="video-embed"><iframe src="https://www.youtube.com/embed/…">	Responsive 16:9 box	--helpdesky-radius
Code blocks	<pre><code class="language-xyz">	Dark block with rounded corners, no syntax highlighting	--helpdesky-radius
Inline code	<code>	Light tinted background	--helpdesky-code-bg
Tables	<table> with <thead> and <tbody>, sometimes inside <div class="table-wrapper">	Borders, header row, horizontal scrolling	--helpdesky-text
Images	<img src="https://helpdesky.io/api/images/…" alt="…">, optionally data-align="center" or data-align="right"	Rounded corners and alignment	--helpdesky-radius
Lists and quotes	<ul>, <ol>, <blockquote>	Accent coloured markers and quote bar	--helpdesky-accent

Allow https://helpdesky.io in your img-src and www.youtube.com in your frame-src if your site sets a Content Security Policy.

Next steps

Save your public address in Help Center → Domain & Address, copy the prompt or the example that matches your stack, deploy, run Check setup and confirm with Make it live. If something does not pass, the failing step tells you exactly what arrived. Questions about the API itself? The full reference is at helpdesky.io/docs/api.