> ## Documentation Index
> Fetch the complete documentation index at: https://docs.open.cx/llms.txt
> Use this file to discover all available pages before exploring further.

# Help Center theme designs

> Start a Help Center design from a preset, edit its page templates with Companion or MCP, preview with real articles, and publish or restore a version.

Open **Help Center → Settings → Customization → Design with Companion** on a site enrolled in the theme pilot. Your current site opens beside the chat. For example, ask “Move search above the topic cards and add a page at /about.” While Companion edits, the preview shows **Let Companion cook** and the name of your draft. The updated page appears automatically when it’s ready.

1. Open **Templates** and choose a design. **Folio** opens with live article search and topic folders. **Atlas** links straight to popular guides, with more articles grouped by topic below. **Beacon** suggests articles as you type, and **Relay** lets readers switch between products. **Default** opens the classic layout. Branded sites can also choose **Your original design**. Try as many templates as you like with your site’s content. Your first successful edit saves a private draft. To keep a template as it is, choose **Save draft**. Unsaved previews are available for 24 hours.
2. Follow a topic or article in the preview. You can ask Companion about the page you’re reading, including its heading and language, even before you start a draft. Open **Viewport** to check a tablet or mobile layout. Drag the toolbar to the top or bottom, or focus **Pin toolbar** and use the up and down arrow keys. Drafts open with the toolbar pinned. When it’s unpinned, move the pointer to its edge or tab to a control to show it again. On a phone, switch between **Companion** and **Preview**.
3. Open the **Draft** or **Live** menu to see the design you’re viewing. Choose **Rename design** to give it your own name, **Switch design** to open the live site or another saved design, or **Version history** to inspect an earlier version. The arrow in the draft toolbar opens the same page, language, and version in a new tab. To share the preview, copy the link from the toolbar. A teammate with Help Center read access can open it after signing in.
4. Choose **Publish** once the edited preview is ready. If someone published another design while you were reviewing, review the new live version before publishing. To roll back, choose a previously published version in **Version history** and select **Restore version**. To return to the original design, open the live site and choose **Restore original design** from its menu.

To remove a design you have never published, open its **Draft** menu, choose **Delete draft**, and confirm the design name shown. If you have already published the design, choose **Discard unpublished changes** to return the draft to its last published version. Discarded versions and their private preview links are removed. Your public site keeps its current design.

Reading a design and opening a preview require Help Center read permission. Creating, renaming, editing, deleting, publishing and restoring require Help Center write permission. Teammates without Companion authoring access use **Open design studio** in Customization to access their permitted controls. Site-wide CSS and head scripts in **Appearance** are live settings. Private draft previews suppress head scripts, visitor analytics and chat submissions.

Workspace audit logs record who created, edited, renamed, or discarded a saved design. Opening a template preview leaves the audit history untouched. [Audit logs](https://docs.open.cx/security/audit-logs.md)

When you publish or restore, the studio compares search and article pages with your live design in each site language. For example, it catches a design that drops the vote buttons only on longer articles or shows untracked links only for larger sets of search results. If tracking would be lost, choose **Keep editing** to put the controls back, or choose **Publish with these changes** or **Restore with these changes** to accept.

Studio also checks sample pages using the published content in each language. If a page would appear empty or fail to open, Studio tells you which page and language need attention. Your current site stays live. Choose **Ask Companion to fix it** to repair the design in a private draft. Open the corrected page in the preview, then choose **Publish** when you’re ready. If you were restoring an older version, Companion preserves newer edits in the existing design. Teammates who edit without Companion can choose **Keep editing**.

If a template later fails for a visitor, that visitor gets the page in your site's original design.

If the studio can’t verify a condition around a tracked control, it names the template and control to change. Keep the control outside that condition or simplify the condition, then try again. You can restyle the controls freely. Check their visibility in the preview when changing CSS.

## Editable files

| File | Where it appears |
| - | - |
| `__root.html` | Shared layout around every page. Place `{% block content %}{% endblock %}` where the current page belongs. |
| `index.html`, `category.html`, `article.html`, `search.html` | Home, category, article and search pages. |
| `_components/topic-card.html` | Reusable markup. Include it with `{% render '_components/topic-card.html', topic: item %}`. |
| `about/index.html` | An additional page at `/about` in each site language. Nested directories are supported. |
| `theme.css` | Styles for the design, including responsive layouts. Use Help Center media in image elements. |

Templates use ordinary HTML, CSS, values in double braces, and tags for loops and conditions. The site supplies localized names, navigation, category and article URLs, and search results. Use `urls.base` when linking to a custom page, so it works on the primary domain, on custom domains and inside previews. Choose a path that’s free of built-in pages, language paths, articles and old article redirects. A published custom page keeps its URL when someone adds an article. If an article draft was saved before the page took that URL, choose a different article slug before publishing.

```html theme={"dark"}
<h1>{{ site.name }}</h1>
<hc-search></hc-search>
{% for topic in topics %}
  <a href="{{ topic.url }}">{{ topic.name }}</a>
{% endfor %}
<a href="{{ urls.base }}/about">{% case locale %}{% when 'ar' %}عن فريقنا{% else %}About our team{% endcase %}</a>
```

Topics expose their direct `articles`, child `topics` and up to four `featured_articles` from the whole branch. Each entry includes its localized URL. Use `navigation` for the full topic tree on any page.

A custom page uses its first heading as the browser and search title in the reader’s language.

To give visitors search on every page and a topic menu on phones, add these buttons to the header in `__root.html`. You can also place either button on an individual page.

```html theme={"dark"}
<header>
  <hc-mobile-nav></hc-mobile-nav>
  <hc-search-dialog></hc-search-dialog>
</header>
```

Beacon, Folio, Atlas and Relay include a keyboard skip link, header search and a mobile menu. On a topic page use `<hc-category-articles></hc-category-articles>` to let readers search within that topic.

The mobile menu includes the homepage and nested topics in the visitor’s language. Selecting a link closes the menu. The search button opens article search, also available with **⌘K** on Mac or **Ctrl+K** on Windows and Linux. Both buttons have translated labels. Add a `class` to style a button or put your own localized text between its tags.

Companion writes new headings, links and custom pages in the languages your site serves. To change just one translation, name the language in your request. For a contact page, supply any support hours or response times you want it to promise.

Use `hc-search-suggestions` for live article suggestions or `hc-search` for a search form. Use `<hc-topic-icon name="{{ topic.icon }}"></hc-topic-icon>` to show a topic’s icon. Use `hc-article-body` for formatted article content, `hc-feedback` for helpfulness votes, `hc-toc` for the table of contents, `hc-search-results` for results, and `hc-languages` for language selection on multilingual sites. A `details` element with a `summary` creates a disclosure. Use `hc-tabs` with directly nested `hc-tab` panels, each with a label and a unique value, for tabbed sections.

Add `<hc-chat></hc-chat>` to reopen support chat with its current messages. Add `<hc-ask></hc-ask>` to let a visitor enter a question and send it as the first message. Both use your site's chat widget. If your existing integration handles `opencx:open` or `opencx:ask`, call `event.preventDefault()` in its event listener to take over that action.

## Editing through MCP

`get_help_center_theme` returns the site's current `languages` with the primary language first, including when you read an older version. Use `locale` to select custom text as in the bilingual link above. Use the supplied `labels` for standard actions.

Call `list_help_center_themes` to find the site’s presets, saved designs and live revision. Use `try_help_center_theme` to sample a template, `create_help_center_theme` to explicitly save a new design, and `get_help_center_theme` to read its files. The preset IDs for Beacon, Folio, Relay and Atlas are `search-first`, `documentation`, `multi-product` and `atlas`. When editing a template already open in Companion, read its design ID directly. Its first successful update adds it to Saved designs. Send the complete contents of each changed file to `update_help_center_theme` with the current draft revision. Omit untouched paths. A null value removes an optional file. If another editor saved first, read the new revision and reapply your change.

Use `preview_help_center_theme` to get a signed-in review link. Set `page` to a localized path such as `/ar/about` or include a section, such as `/en/guide#billing`, to take a teammate straight to the heading you reviewed. `publish_help_center_theme` and `restore_help_center_theme` also take the live revision you reviewed. A conflict asks you to review the intervening change before switching the live site. [Help Center design API](https://docs.open.cx/api-reference/help-center/themes/list.md)

If a call returns `theme_tracking_confirmation_required`, review its `tracking_losses`. To accept them, repeat the same request with those values in `confirmed_tracking_losses`. Otherwise, keep the tracked controls in the design and review the new revision.

Use `rename_help_center_theme` with the current name and your new name to update the design label. [Rename a design](https://docs.open.cx/api-reference/help-center/themes/rename.md)

Use `delete_help_center_theme_draft` with the draft’s `expected_revision_id` to delete or discard it. On a conflict, review the latest draft before trying again. [Delete a draft](https://docs.open.cx/api-reference/help-center/themes/delete-draft.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.