Docs content directory

This directory contains all Talon.One documentation pages, split into two sections:

• product/ — end-user docs for the Campaign Manager (CAMA)
• dev/ — developer docs for integrations, APIs, and SDKs

Pages are Markdown/MDX files rendered by Docusaurus. Every page is published automatically on merge to main.

---

Front matter

Every page requires front matter at the top:

---
title: Page title (sentence case, pluralized)
description: One-line summary shown in search results and link previews.
tags:
  - relevant-tag
---

Use release: beta or release: limited access for unreleased features.

---

Writing rules (condensed from readme/styleguide.md)

Voice and tense

• Active voice. Use you as the subject.
• Present tense only. No future tense (will, would, might, shall).
• Imperative form for tasks: Click Save. not You will need to click Save.

Titles

• Sentence case (only first word capitalized).
• No gerunds: Create a campaign, not Creating a campaign.
• Page titles: plural. Section titles: singular or plural based on outcome.
• No question marks in titles.

Language

• Simple American English. No jargon, no Latin (i.e, e.g → use for example).
• No parentheses, no weasel words (often, probably, possibly).
• No adjectives for difficulty: never write simply, easily, just.
• Spell out zero through nine; numerals for 10+.
• Serial comma: active, inactive, or blocked.

Formatting

• Bold (**text**) for UI elements and calls to action.
• Inline code (`text`) for technical values, field names, and user input.
• Italics sparingly — never for UI elements.
• No double or single quotes for emphasis.

Links

• Link text = page title or the action verb: see [API reference]() or [install the SDK]().
• Never use click here or this page.

Lists

• Introduce with a complete sentence, not a fragment completed by the list items.

Capitalization — always capitalize:

• the Rule Builder, the Campaign Manager, the Integration API, the Management API, the Third-party API, Application (when referring to a CAMA Application)

Capitalization — do not capitalize:

• loyalty programs, loyalty tiers, referrals, coupons, campaigns, rules

Terminology

• user = client's employee with Campaign Manager access
• customer = client's end user (receives coupons, earns points)
• sign in / sign out, not log in / log out
• ecommerce or eCommerce, not e-commerce
• No promotion or strikethrough association with campaigns — use campaigns with promotion rules

Admonitions

Use Docusaurus admonition labels:

• :::note, :::tip, :::important, :::warning
• Custom labels: Feature access (roles/permissions), Feature availability (limited availability)

---

Reusable snippets

Shared content lives in static/snippets/. Include in pages with:

<include path="../../static/snippets/snippet-name.md" />

Create a snippet only when content is reused across multiple pages, not for a single paragraph.

---

MDX components

Import and use these from src/components/:

Component	Use case
<StepsContainer>	Numbered step-by-step procedures. Headings inside become numbered steps.
<StateLabel type="running" name="Running" />	Visual campaign/entity state labels.
<LimitedAccessInfoBox />	Admonition for restricted-access features.
<FeatureAccessInfoBox />	Admonition for role/permission requirements.

Full component list: src/components/ (each has a README or is self-documented via props).

---

API endpoint references

• Use the endpoint summary as it appears in the API docs (no inline code).
• Link text: endpoint summary only. Add endpoint after the link.
  • Do: [Update customer session](integration-api#tag/...) endpoint
  • Don't: [Update customer session endpoint](integration-api#tag/...)

---

Linting

Vale runs on all PRs against the rules in .github/styles/TalonOne/. Run locally with:

vale docs/

Use <!-- vale off --> / <!-- vale on --> sparingly to suppress false positives only.

---

File placement

Content type	Directory
Campaign Manager features	docs/product/
Integration and API guides	docs/dev/
Product update announcements	whats-new/
Reusable content blocks	static/snippets/

When adding a page to a section, ensure it is listed in the relevant _category_.json or sidebar config if the section uses manual ordering.