How this project is built, and how to edit it without breaking the design. Exclude this topic from reader publications.
Five rules for safe editing
- Never add colors, fonts or inline styles in topics. All styling lives in one snippet:
snippet-styles. Change the brand color there once, and every page updates. - Use plain editor elements. Headings, numbered lists, tables, Info/Warning boxes and Show More boxes inserted from the ribbon are styled automatically.
- Numbered list = procedure. Use numbered lists only for steps, bulleted lists for everything else. One action per step.
- Keep the two snippet lines at the top (
snippet-styles) and bottom (snippet-page-footer) of every topic. - Never type product facts by hand. Use variables for names, versions, URLs, limits and contacts.
Topic template
<ch:snippet url="/articles/flowdesk-user-guide/snippet-styles/"/>
<p class="fd-meta"><span>⏱ 3 min</span><span>👤 Audience</span></p>
<p class="fd-lead">One sentence: what the reader achieves.</p>
<h2>Task heading starting with a verb</h2>
<ol><li>Step.<span class="fd-result">What the reader sees.</span></li></ol>
<ch:snippet url="/articles/flowdesk-user-guide/snippet-page-footer/"/>Variables
Create these in Project settings › Single-sourcing › Project variables. Until a variable exists, it renders as empty text.
| Variable | Example value | Use case | Current value |
|---|---|---|---|
ProductName | FlowDesk | Rebranding, white-label docs | FlowDesk |
ProductVersion | 4.2 | Version in headers, notes, requirements | 4.2.2 |
ReleaseDate | October 2026 | Release notes, "last updated" | |
CompanyName | FlowDesk Inc. | Legal text, footer (overrides the global variable) | Company1 |
SupportEmail | support@flowdesk.example | Contacts in footer, wizard, FAQ | support@flowdesk.example |
AppURL | https://app.flowdesk.example | Sign-in address, cloud edition | |
OnPremURL | https://flowdesk.your-company.local | Sign-in address, on-premise edition | |
APIBaseURL | https://api.flowdesk.example/v2 | API reference, SCIM setup | |
TrialDays | 14 | Pricing facts that marketing changes | |
MaxFileSize | 250 MB | Product limits |
Insert in Design mode: Single-sourcing › Insert variable. In Source mode: <ch:var name="ProductName"/>.
Conditional variables
To show a different value per edition, place two variables side by side and tag each one. See snippet-sign-in-url:
<ch:var name="AppURL" ch:include="Cloud"/><ch:var name="OnPremURL" ch:include="OnPremise"/>Snippets
| Snippet | What it reuses | Used in |
|---|---|---|
snippet-styles | The whole design system (CSS) and the optional Copy-code script | Every topic |
snippet-page-footer | Previous/Next, "Was this helpful?", support contacts | Every topic |
snippet-before-you-begin | Standard prerequisites | Quick start, Create a board |
snippet-sign-in-url | Edition-specific sign-in address | Quick start, Install and sign in |
snippet-admin-only | Permission warning | Manage users and roles |
Insert: Single-sourcing › Insert snippet. Snippets live in the hidden Snippets (authoring) folder.
Conditional content
Create these output tags in Settings › Single-sourcing › Output tags, then select them when you publish.
| Output tag | Publication | Where it's used |
|---|---|---|
Cloud | Cloud edition | Install and sign in, FAQ, sign-in snippet |
OnPremise | Self-hosted edition | Server requirements, SSO sign-in |
Admin | Administrator guide | SSO and SCIM setup |
<div ch:include="OnPremise">Only in the on-premise publication</div>
<div ch:exclude="Cloud,OnPremise">Only when no edition tag is selected (writer preview)</div>Component library
Copy a block in Source mode and change only the text. Each component works without JavaScript, so it also works after publishing.
Callouts: note, tip, warning, danger
| Note — neutral extra information. |
| Tip — a faster or better way. |
| Warning — something may not work as expected. |
| Danger — data loss or security risk. |
Insert Note and Warning from Quick Parts. For tip and danger, change the class to infobox--tip or infobox--danger.
Badges
NewBetaProEnterpriseAdmin onlyFixedDeprecated
<span class="fd-badge fd-badge--new">New</span>Step result
- Click Save.The card is saved.
<span class="fd-result">What the reader sees.</span>Tabs (platforms, languages)
Use Insert › Tabs in the editor. Each row is a tab: first cell = tab name, second cell = content.
Glossary tooltip
Hover over: board
<span class="fd-term" tabindex="0" data-tip="Definition">term</span>Interactive checklist
<div class="fd-checklist nonPrintable">
<input type="checkbox" id="u1"/><label for="u1">First task</label>
<input type="checkbox" id="u2"/><label for="u2">Second task</label>
<p class="fd-count"></p><p class="fd-alldone">All done!</p>
</div>IDs must be unique within the topic.
Switcher: role picker, quiz, wizard
Inputs first, then an optional <p> with labels, then one <div> per option, in the same order (up to 12).
<div class="fd-switch">
<input type="radio" name="grp" id="o1" checked="checked"/><input type="radio" name="grp" id="o2"/>
<p><label for="o1">Option 1</label><label for="o2">Option 2</label></p>
<div>Content 1</div>
<div>Content 2</div>
</div>Add fd-wizard for a step-by-step troubleshooter, fd-quiz for a knowledge check, and fd-right/fd-wrong on answer panels.
Process flow
<div class="fd-flow"><div>1️⃣<b>Plan</b>Text</div><div>2️⃣<b>Do</b>Text</div></div>Code block with language label and Copy button
echo "Hello"<pre data-lang="bash"><code>echo "Hello"</code></pre>Cards grid, hero, hotspot tour, timeline, API endpoint
See live examples in Welcome (hero, cards, role picker), Create your first board (hotspot tour), Release notes (timeline) and API quick start (endpoints, code tabs). Open the topic in Source mode and copy the block.
Writing style checklist
✅ Ready for review.