Documentation style guide

How articles are written

Articles are Markdown files at src/docs/<lang>/<section>/<slug>.md. Each begins with front matter that drives the sidebar, hub cards, ordering, and search:

---
title: Ask your first question
description: One-line summary shown on section pages and in search.
order: 2
---

Body content starts here…

The section a file lives in (its folder) and the section titles/order come from src/_data/docsSections.json. Everything below is what goes in the body.

Typography

Body text uses the site's sans at a comfortable reading measure. Headings, links, bold, and inline code all get consistent treatment.

A paragraph with [an inline link](/docs/), **bold for a UI label**, and `inline code`.

Second- and third-level headings structure the page; H2s appear in the "On this page" panel and get a rule above them. Only use one H1 (the title, set in front matter).

## A second-level heading

### A third-level heading

Lists

Unordered lists for collections; ordered lists for loose sequences that don't warrant full step blocks.

- Knowledge bases hold your documents
- Connectors keep live systems in sync
- Recipes automate repeatable work

1. Open the admin panel
2. Choose **Members**
3. Select **Invite**

Callouts

Four kinds, each with a fixed label and color. The label comes from the class; add data-label="…" to override it (used for translated docs).

<div class="dx-callout"><p>A plain note adds useful-but-not-critical context.</p></div>

<div class="dx-callout tip"><p>A tip shows a faster or smarter way to do something.</p></div>

<div class="dx-callout warning"><p>A warning flags something that could cause data loss or surprise.</p></div>

<div class="dx-callout important"><p>An important callout marks something the reader must know first.</p></div>

Numbered steps

For real procedures. Each step auto-numbers and reads as one visual thread. The first line is the step's action; following lines explain it, and a step can carry a screenshot.

<div class="dx-steps">
<div class="dx-step">
<p>Name the step in one short line</p>
<p>Then explain it in a sentence or two. Keep each step to one action.</p>
</div>
<div class="dx-step">
<p>Show, don't just tell</p>
<p>Steps can carry screenshots or live demos.</p>
</div>
<div class="dx-step">
<p>End with the result</p>
<p>Tell the reader what they should now see, so they know it worked.</p>
</div>
</div>

Tables

Standard Markdown tables. They scroll horizontally on small screens automatically.

| Plan | Knowledge bases | Members |
| ---- | --------------- | ------- |
| Starter | 3 | Up to 25 |
| Team | 20 | Up to 250 |
| Enterprise | Unlimited | Custom |

Code

Inline code sits in running text; fenced blocks handle longer samples.

curl -X POST https://api.joysuite.com/v1/ask \
  -H "Authorization: Bearer $JOYSUITE_API_KEY" \
  -d '{"question": "What is our refund window?"}'

```
curl -X POST https://api.joysuite.com/v1/ask \
  -H "Authorization: Bearer $JOYSUITE_API_KEY" \
  -d '{"question": "What is our refund window?"}'
```

Images & screenshots

Images get the redesign's flat framed "product shot" treatment automatically. Always include width, height, and descriptive alt text.

Markup

<img src="/images/docs/upload-area.png" alt="The document upload area" width="1200" height="600">

Video embeds

Wrap an iframe in .dx-video for a responsive 16:9 frame.

<div class="dx-video"><iframe src="https://www.youtube-nocookie.com/embed/dQw4w9WgXcQ" title="Placeholder video" loading="lazy" allowfullscreen></iframe></div>

Interactive demos

The pattern that replaces screenshots with live, interactive pieces of the product. Each demo is a self-contained component in src/_includes/docs-demos/; an author embeds one with a single include line (shown under each). They're grouped below by the job they do.

Charts & analytics

For measuring-success, admin, and reporting articles. Charts follow the dataviz discipline — a validated palette, one axis, direct labels, and a table fallback.

Bar chart

Inline SVG with hover tooltips, bar highlighting, a selective value label, and a table-view fallback for accessibility.

{% include "docs-demos/chart-questions.njk" %}

Horizontal bar ranking

A ranked list with proportional bars — top questions, most-cited sources. Reads better than vertical bars when the categories carry long labels.

{% include "docs-demos/chart-bar-ranking.njk" %}

Line / trend chart

A single-series trend with a crosshair tooltip that snaps to the nearest week, plus a table view. For usage, adoption, and rate-over-time stories.

{% include "docs-demos/chart-trend.njk" %}

Donut composition

Parts of a whole — answers by source, license usage. Uses a validated categorical palette (non-adjacent hues), a legend with values, and a center total.

{% include "docs-demos/chart-donut.njk" %}

Activity heatmap

Volume across two dimensions — day of week × time of day. A sequential plum ramp (light→dark) with a legend and per-cell tooltips.

{% include "docs-demos/heatmap.njk" %}

Stat tiles (KPI row)

Big hero numbers for the top of an analytics or admin page. Deltas pair a color with an arrow glyph and words, so meaning never rests on color alone.

{% include "docs-demos/stat-tiles.njk" %}

Product recreations

Live, clickable miniatures of the product — the alternative to a screenshot sequence. Canned data, no backend, but the interactions are real.

Mini Joy assistant

A fully fabricated chat UI — app chrome, message thread, typing state, and a scripted multi-turn conversation with citations and context-aware follow-up chips. The conversation graph is a plain object in the partial, so each article can ship its own script.

{% include "docs-demos/joy-assistant.njk" %}

Ask bar

The ask experience with suggested-question chips, a thinking state, and a canned grounded answer plus citation.

{% include "docs-demos/ask-bar.njk" %}

Grounded answer with citations

A grounded answer whose inline citation markers open the exact source passage they came from — JoySuite's core value made tangible.

{% include "docs-demos/answer-citation.njk" %}

Setup wizard

A multi-step flow — authorize → choose folders → sync — with a progress indicator and Back/Next. Collapses a long screenshot sequence into one walkthrough.

{% include "docs-demos/wizard.njk" %}

Source browser

An expandable file tree of the Knowledge Center. Native <details>, so it works even without JavaScript.

{% include "docs-demos/source-browser.njk" %}

Permission matrix

Roles × capabilities with toggleable cells, so readers can feel how permissions combine. Ideal for admin and security docs.

{% include "docs-demos/permission-matrix.njk" %}

Command runner

Pick a command, run it, and see the formatted output — shows what a command actually produces.

{% include "docs-demos/command-runner.njk" %}

Task board (Kanban)

A recreation of the Tasks page: columns for each stage, task cards, and click-to-complete that moves a card to Completed. For task-management and assignment articles.

{% include "docs-demos/task-board.njk" %}

Instructional components

Reusable teaching patterns that aren't tied to a specific product surface.

Annotated screenshot

Numbered pins over a screenshot that reveal a caption on hover, tap, or keyboard focus — a guided screenshot instead of a static one.

1 2 3

Markup

{% include "docs-demos/hotspots.njk" %}

Tabbed panels

The same instructions in per-connector or per-platform variants, without stacking every version on the page. Arrow-key navigable.

{% include "docs-demos/tabs.njk" %}

Pipeline diagram

How a question becomes a grounded answer: query → retrieve → ground → cite → answer. Hover or focus a stage to reveal what it does.

{% include "docs-demos/pipeline.njk" %}

Before / after slider

Drag to wipe between two states — here a raw keyword search versus a grounded answer. Keyboard-operable via the range control.

{% include "docs-demos/before-after.njk" %}

FAQ accordion

Collapsible question/answer pairs; only one opens at a time. Native <details> underneath.

{% include "docs-demos/accordion.njk" %}

Decision tree

Branching choices that guide a reader to a recommendation — which plan, which connector. The tree is data-driven, so it's easy to extend.

{% include "docs-demos/decision-tree.njk" %}

Design tokens

The colors these patterns draw from. Ink and hairline carry the design-v2 look; plum is the single accent. The chart data color is a lighter, validated plum (the brand plum is too dark to read as a data mark).

Status hues used by callouts: tip green #3f9a6a, warning amber #c77b1e.

Categorical series (donut and other multi-series charts) — a validated set of non-adjacent hues, assigned in this fixed order and never cycled:

Sequential ramp (heatmap intensity) — a single plum hue, light→dark: #f3eef8 · #d8c9ea · #b79cd6 · #8a5cc9 · #5e3099.