Instruction file imported from signalwire/docs-legacy (.cursor/rules/docs.mdc). Copyright stays with the author.

description: globs: .md,.mdx alwaysApply: false

SignalWire documentation project rules

This document outlines the comprehensive standards and conventions for writing documentation in the SignalWire docs codebase.

Documentation structure and organization rules

Directory structure

• Use kebab-case for all directory and file names
• Each major section must have a _category_.yaml file defining metadata. Don't use _category_.json.
• Use index.mdx for section overview/landing pages
• Prefix component/partial files with underscore (_) when they're imported by other files
• Organize content hierarchically: /home/{product}/{feature}/{topic}

Category configuration

# _category_.yaml format
label: "Section Name"
position: number  # 0 for overview, 1-3 for main sections
collapsible: false
className: menu-category

File extensions and types

• Use .mdx for all content files (enables React components)
• Use .yaml for configuration files
• Use .md only for pure markdown without component needs

Content standards

Frontmatter requirements

Every content file must include:

---
title: "Page Title"
sidebar_label: "Menu Label" # if different from title
slug: "/custom-url" # required by our style guide
description: "Brief page description" # for SEO
---

Content structure pattern

1. Import statements (components, icons, partials)
2. Main heading (H1) with page title
3. Subtitle component with compelling description
4. Introduction paragraph explaining the content
5. Action sections ("Get started", "Try it out", "Choose an API")
6. Card-based navigation using CardGroup components
7. Popular/Featured content sections

Writing style guide

• Tone: Developer-focused, clear, and actionable
• Voice: Use active voice and action-oriented language ("Build", "Create", "Deploy")
• Length: Keep descriptions concise (1-2 sentences per card)
• Technical level: Assume intermediate technical knowledge
• Calls-to-action: Every section should guide users to next steps
• Titles: Avoid gerunds in titles when practical ('Install package' rather than 'Installing the package')
• Sentence case: Apply sentence case to card titles, tab titles, and pseudo-headers
• Pseudo-headers: Titles made with simple bolded text (either on their own line or in lists with colons) should use sentence case
• Semantic line breaks: Follow the SemBr specification by putting line breaks before and after major clauses. Links should occupy their own complete line.

Header formatting

• Use sentence case for all headers (capitalize only the first word and proper nouns)
• Examples: "Getting started", "API reference", "Content structure pattern"
• Avoid title case: "Getting Started", "API Reference", "Content Structure Pattern"
• Use only header levels 1-4 (H1, H2, H3, H4)
• Avoid H5 and H6 headers for better document structure

Component usage standards

Card components

// Standard card usage for navigation
<CardGroup cols={3}>
  <Card 
    title="Feature Name"
    icon={<IconComponent />}
    href="/link/path"
  >
    Brief description of what this leads to
  </Card>
</CardGroup>

Card content guidelines

• Don't put links in card context/description text
• Don't create bolded "pseudo-headers" within card content
• Keep card descriptions as plain text for better readability

Icon standards

• Use consistent icon libraries: react-icons/md, react-icons/fa, react-icons/lia
• Choose semantically appropriate icons
• Import only needed icons to avoid bundle bloat
• Use custom icons from @site/src/icons when available

Component organization

// Import order:
import Subtitle from "@site/src/components/typography/Subtitle";
import ComponentName from "./_partials/_componentName.mdx";
import { Card, CardGroup } from "@site/src/components/Extras/Card";
import { IconName } from "react-icons/md";

Component import exemptions

• You don't need to import components that are already available from @site/src/theme/MDXComponents/index.js
• These components are automatically available in all MDX files without explicit imports
• Available components include: Language, LangItem, LangSwitch, Tabs, TabItem, Accordion, AccordionGroup, AlphaBadge, BetaBadge, APITable, APITableRow, Card, CardGroup, DocCard, DocCardList, Frame, PreviewCardGroup, PreviewCard, Slideshow, Steps, Subtitle, UseCaseLinks, UseCaseView, Tooltips, GuidesList, GuidesListMirror, ReleaseCard, Tables

Navigation and user experience

Information architecture

• Overview first: Always start with high-level concepts
• Progressive disclosure: Move from general to specific
• Multiple pathways: Provide different entry points (beginner, migration, specific use case)
• Cross-linking: Reference related sections consistently

Section types

Each major section should include:

• "Get started" - Quick entry points for new users
• "Choose an API/Tool" - Decision-making guidance
• "Popular guides" - Most commonly needed content
• "Try it out" - Hands-on examples or demos

Link formatting

• Internal links: Link to the page's /slug. Avoid relative links (eg., '../../file.mdx')
• External links: Full URLs with proper attribution
• Link text should be descriptive, not "click here"
• Use reference-style links if a link appears more than once in the same document

Reusability and maintainability

Partial files

• Create reusable content as _filename.mdx in same directory
• Export data arrays for consistent card collections:

export const products = [
  {
    name: "Product Name",
    description: "Product description",
    icon: <IconComponent />,
    link: "/product/path",
  }
];

Content data management

• Store card data as JavaScript objects for easy maintenance
• Use consistent property names: name, description, icon, link
• Group related items in logical arrays

SEO and accessibility

• Include description in frontmatter for meta tags
• Use semantic heading hierarchy (H1 → H2 → H3)
• Provide alt text for custom images
• Ensure proper focus management for interactive elements

Development and build commands

Package manager

This project uses Yarn, not npm. Always use yarn for all package management commands.

• Build: yarn --cwd website build
• Develop: yarn --cwd website start (for local preview)
• Install: yarn install
• Do NOT use: npm install, npm run, npx - use yarn equivalents instead

Quality assurance

Content review checklist

• Follows file naming conventions
• Includes required frontmatter
• Uses consistent component patterns
• Links are functional and properly formatted
• Icons are semantically appropriate
• Content flows logically from general to specific
• Includes clear next steps for users
• Headers use sentence case formatting

API specifications

TypeSpec definitions

API specs are defined in TypeSpec and output to OpenAPI format. All specs are located in the specs/ directory:

• specs/signalwire-rest - SignalWire REST API specifications
• specs/compatibility-api - Compatibility API specifications
• specs/swml - SWML schema definitions
• specs/_shared - Shared TypeSpec definitions

SWML JSON schema

The authoritative SWML schema is generated from TypeSpec and located at:

• specs/swml/tsp-output/@typespec/json-schema/SWMLObject.json

This JSON Schema defines the complete structure of valid SWML documents.

SWML and SWML AI source code references

Source code repositories

For deep implementation details about SWML and SWML AI, reference the cloned source code repositories in the temp directory:

• temp/mod_infrastructure - Core SWML engine, methods, string templates, variable resolution, call control
• temp/mod_openai - AI method implementation, SWAIG protocol, global_data, TTS/ASR integration

Finding SWML implementation details

Core SWML logic:

• Method implementations: temp/mod_infrastructure/swml.c (search for swml_handle_<method>)
• Variable templates: temp/mod_infrastructure/swml.c (search for resolve_swml_var)
• Control flow: temp/mod_infrastructure/swml.c (if, switch, while handlers)
• Schema validation: temp/mod_infrastructure/swml_schema.c

AI and SWAIG features:

• AI sessions: temp/mod_openai/mod_openai.c (search for ai_session)
• SWAIG protocol: temp/mod_openai/swaig.c
• Global data: temp/mod_openai/mod_openai.c (search for global_data, prompt_vars)
• Webhooks: temp/mod_openai/webhook.c

Quick search patterns

# Find method handlers
grep -r "swml_handle_" temp/mod_infrastructure/swml.c

# Find variable resolution
grep -r "resolve_swml_var" temp/mod_infrastructure/

# Find AI features
grep -r "global_data\|prompt_vars" temp/mod_openai/

Serena memory reference

For comprehensive navigation and search patterns, use Serena's read_memory tool with: swml_source_code_references

These rules ensure consistency, maintainability, and excellent user experience across the SignalWire documentation platform.