CLAUDE

Claude Code instructions for flowx-docs

Project-specific instructions for FlowX documentation.

Platform

• Platform: Mintlify
• Format: MDX files
• Navigation: docs.json
• Images: https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/

---

Frontmatter

---
title: Page Title
description: Short 1-2 sentence description
icon: icon-name        # Optional, Heroicons naming
mode: wide             # Optional, for release notes
---

---

Heading structure

## Major section           # H2 for main sections
### Subsection             # H3 under major sections
#### Detail section        # H4 rarely, for deep nesting

Common section order:

1. Overview
2. Key features/characteristics
3. Configuration/How it works
4. Implementation steps
5. Troubleshooting
6. Related resources

---

Terminology

• Use “app” not “application”
• Use “turn off” not “disable”
• Spell out acronyms on first use
• Placeholders: {your-client-name} pattern
• Sentence-style capitalization for headings

---

Formatting

UI elements

• Bold for buttons, tabs, fields: Click **Save**
• Arrows for paths: **Settings** → **Access Management**
• Toggle states: Toggle **ON** or Toggle **OFF**

Values and defaults

**Default:** `value`

**Examples:**
- `example1`
- `example2`

Section dividers

Use --- between major sections

---

Tables

Setup guides (env vars)

| Environment Variable | Description | Default Value |
|---------------------|-------------|---------------|
| `ENV_VARIABLE`      | What it does | `value`      |

Deployment guidelines (env vars)

| Environment Variable | Description | Default Value | Component |
|---------------------|-------------|---------------|-----------|
| `ENV_VARIABLE`      | What it does | `value`      | service-name |

Include Component column to show which service uses the variable.

General properties

| Property | Description | Default |
|----------|-------------|---------|
| **Property Name** | What it does | `value` |

• Bold for property names
• Backticks for env vars and values
• Always include Default column for config tables

---

Code blocks

Language	Use for
yaml	Configuration, environment variables
json	API requests/responses, data structures
bash	Commands, CLI
javascript / python	Business rules

---

Mintlify components

Callouts (by frequency)

<Info>
Technical details, version availability, specifications
</Info>

<Warning>
Breaking changes, critical requirements, deprecated features
</Warning>

<Tip>
Best practices, shortcuts, recommendations
</Tip>

<Note>
Secondary context, alternatives
</Note>

<Check>
Validation confirmations (setup guides)
</Check>

Usage per doc: Info 3-4, Warning 1-2, Tip 2-3

Cards

<CardGroup cols={2}>
  <Card title="Feature" icon="icon-name">
    Brief description
  </Card>
</CardGroup>

• cols={2} for features (most common)
• cols={3} for role cards in release notes
• Single <Card> for highlights with href for links

Steps (for procedures)

<Steps>
  <Step title="Action verb phrase">
    Description of step
  </Step>
</Steps>

Use for 3+ sequential actions. Use numbered lists for 1-2 steps.

Tabs

<Tabs>
  <Tab title="Overview">Content</Tab>
  <Tab title="Configuration">Content</Tab>
  <Tab title="Examples">Content</Tab>
</Tabs>

Common tab titles: Overview, Key Features, Configuration, Benefits, Use Cases

Accordions

<AccordionGroup>
  <Accordion title="Expandable section" icon="icon">
    Detailed content
  </Accordion>
</AccordionGroup>

Use for: component properties, troubleshooting, optional details

ParamField (configuration docs)

<ParamField path="fieldName" type="string" required>
Description of the field.

**Default:** `value`

<Tip>
Additional guidance
</Tip>
</ParamField>

Frame (images)

<Frame>
![Alt text](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/image.png)
</Frame>

Always wrap images in Frame.

Badges (release notes)

<Badge color="blue" icon="cloud">SaaS</Badge>
<Badge color="green" icon="globe">All Deployments</Badge>
<Badge color="purple" icon="star">Major Feature</Badge>

---

Doc type patterns

Feature documentation

1. Frontmatter with icon
2. Info box if new version feature
3. Overview with Frame image
4. Key features CardGroup
5. When to use / decision matrix
6. Implementation Steps
7. Configuration sections
8. Troubleshooting AccordionGroup
9. Related resources CardGroup

Setup guides

1. Simple frontmatter
2. Prerequisites / Dependencies
3. Configuration sections with env var tables
4. Check boxes for validation steps
5. Related links

Heavy on tables, light on Cards/Tabs.

Release notes

<Tabs>
  <Tab title="Category">
    📦 [**Feature**](#anchor) - Description

    ### **Feature name**
    <Card title="Feature" icon="icon" iconType="duotone">
      <Tabs>
        <Tab title="Overview">...</Tab>
        <Tab title="Key Features">
          <CardGroup>...</CardGroup>
        </Tab>
      </Tabs>
      <Badge>...</Badge>
    </Card>
  </Tab>
  <Tab title="Info">
    Deployment, compatibility, migration
  </Tab>
</Tabs>

---

Version callouts

<Info>
**Available starting with FlowX.AI 5.4.0**

Description of feature
</Info>

Or as a Card:

<Card title="New in 5.4.0" icon="sparkles">
Brief description
</Card>

---

Links and cross-references

Link path types

Type	When to use	Example
Relative same-dir ./	Same folder	./redis-configuration
Relative parent ../	Up one level	../actions/business-rule-action
Absolute /5.1/	Cross-directory, release notes	/5.1/setup-guides/redis-configuration

Link text patterns

Use these standard phrases:

For more information, see the [X documentation](path).
For complete X configuration including Y and Z, see the [X Configuration](path) guide.
Learn more about [X](path).
See the [X](path) for details.

Inline vs Card links

Inline links - within paragraph text:

For more information about business filters, refer to the [Business Filters](../user-roles-management/business-filters) section.

Card links - for Related Resources sections and navigation:

<CardGroup cols={2}>
  <Card title="Redis Configuration" icon="database" href="./redis-configuration">
    Cache and session configuration
  </Card>
</CardGroup>

Section anchors

• Auto-generated from headings: ## Database configuration → #database-configuration
• Use kebab-case, lowercase
• Cross-doc anchors: ./configuring-an-iam-solution#scheduler-service-account

Related resources section

Always at end of doc:

## Related resources

<CardGroup cols={2}>
  <Card title="Doc Title" icon="icon" href="./path">
    Brief description
  </Card>
</CardGroup>

Most-linked docs (reference these consistently)

Doc	Use for
./redis-configuration	Cache setup references
./ingress-configuration	Routing/CORS references
./configuring-an-iam-solution	Auth/Keycloak references
./workspaces-access-rights	Access control references
./roles-permissions-matrix	Permission details

External links

Common external domains:

• keycloak.org - Identity management
• mongodb.com - Database docs
• elastic.co - Elasticsearch
• kafka.apache.org - Messaging
• academy.flowx.ai - Training resources

---

Common mistakes

1. Creating duplicate docs - search existing coverage first
2. Wrong version scope - check if NEW or enhancement
3. Missing docs.json entry
4. Images without Frame wrapper
5. Numbered lists instead of Steps component
6. Missing --- dividers between sections
7. Inconsistent table formats

---

File locations

Type	Path
Feature docs	5.1/docs/ or 5.1/ai-platform/
Setup guides	5.1/setup-guides/
Release notes	release-notes/v5.x/
Specs	specs/ (temporary)

---

Before committing

1. Search for duplicate/overlapping content
2. Update docs.json for new files
3. Verify internal links
4. Run ./scripts/validate-docs.sh