Article format

Every article here follows one shape. This is not house style for its own sake — a predictable shape means a merchant can skim to the section they need, and a writer never has to invent structure.

The skeleton lives at templates/article.md in this repo. Copy it.

The shape

Section	Holds	Skip it when
Lede (no heading)	Two or three sentences: what this is, what the article covers.	Never.
Availability note	Where it lives in settings; plan, beta, or default-off gating.	Nothing gates it.
When to use it	The merchant problem, then concrete situations.	Never.
How it works	The behaviour, in order. Diagram only if it genuinely branches.	Never.
Set it up	Numbered steps naming exact dashboard labels.	The feature has no configuration.
What shoppers see	The portal-side result.	Shoppers never encounter it.
What your team sees	Dashboard status, timeline, notification, report column.	Nothing changes in the dashboard.
Limits caution	What does not recalculate, sync, or undo.	Never — write “None known” instead.
FAQ	Three to six real questions, from support tickets.	You have no real questions yet.
Related	Two or three link cards.	Nothing is genuinely related.

Target 800–1,500 words. Past that, split the configuration detail into a companion article and link to it.

Rules that matter

Start at ##. Starlight renders the frontmatter title as the page’s only <h1>, and builds the right-hand table of contents from your ## and ###. Using # in the body produces a second <h1> and a broken TOC.

The description is a search result. It shows up in search, in link cards, and in social previews. Write it as the sentence that makes someone click, and keep it under about 160 characters.

Name the exact UI label. “Go to Settings > Returns > Policies” beats “go to your policy settings”. Merchants search for the words on their screen.

Split shopper-side from team-side. Support answers questions about the portal while looking at the dashboard. Keeping those two views in separate, consistently-named sections means they can jump to the right one.

Diagram only real branching. A flowchart of five sequential steps is worse than five numbered steps. Save Mermaid for eligibility logic and outcome trees — see Eligibility rules for the case where it earns its place.

Why this shape

It is adapted from Loop’s help center, which is the bar our merchants will compare us against. Their article template — lede, why it matters, capabilities, setup, admin and portal experience, FAQ — is genuinely good, and it is worth matching rather than inventing something new.

Four deliberate changes:

1. No “Overview” heading. Loop opens every article with an OVERVIEW heading above a paragraph that repeats the search snippet. The paragraph is useful; the heading is clutter and pushes the real content down.
2. Proper heading levels. Loop’s articles use <h1> for body sections, so the built-in navigation does not work and the page announces a dozen top-level headings to screen readers. Ours start at ## and get a working TOC for free.
3. Shopper and team views always split, always named the same. Loop folds these into one “Admin and portal experience” section, and only on some articles. Making it consistent is the single biggest readability win available.
4. A mandatory Limits section. Loop buries constraints in inline Important: callouts — their exchange-address article hides a real tax-recalculation gotcha mid-paragraph. A fixed, predictable place for “here is what will bite you” is what makes docs trustworthy.

Site structure

One site, not two. Loop splits merchant help (help.loopreturns.com) from developer docs (docs.loopreturns.com, on Mintlify), which means two search boxes and two places to look when a question spans both. Starlight handles reference docs and task guides equally well, so API and webhook material lives in this site under Developer, in one search index.

Revisit that if the developer surface grows past roughly fifty pages.

Known gap

There is no “Was this article helpful?” widget yet. Loop has one, and it is the cheapest way to find the articles that are failing. Starlight has no built-in equivalent — it needs a small component override plus somewhere to send the votes. Worth doing before this site goes in front of merchants at scale.

Before you write

The “planned articles” tables in each section are leads, not an outline. Their one-line descriptions were inferred from the filenames in .claude/features/, and spot-checks found them unreliable — one sample of three had a description that actively misdescribed the feature. Open the source note and write from it.

The nine articles under How the shopper portal behaves predate this site and have not been verified against the current code. Check them before citing them as reference.

Collapsible questions

The FAQ uses a <Faq> component so answers start hidden. A reader scans the questions and opens only the one they came for, instead of scrolling a wall of prose.

import Faq from '~/components/Faq.astro';

<Faq q="Will this change returns that are already open?">
No. It only looks at new ones.
</Faq>

• Answers are closed by default. Pass open to start one expanded, but that defeats the point — use it only for a question nearly every reader has.
• Each question opens independently. It is not an accordion, so opening one does not close the others.
• Answers stay in the page source while collapsed, so site search still finds them and a search result can link straight to the question.
• The component lives at src/components/Faq.astro. It needs an .mdx file — plain .md cannot import components.

The ~/ prefix is an alias for src/, set up in tsconfig.json, so the import path is the same no matter how deep the article sits.