merge commit

Author: titerman

.gitignore

@@ -221,3 +221,5 @@ yarn-error.log*
 /versioned_docs/version-3.0/capacitor-sdk-migration-guides.md
 /versioned_docs/version-3.0/migration-to-capacitor-316.md
 /versioned_docs/version-3.0/sdk-installation-capacitor.md
+
+.worktrees/

CLAUDE.md

@@ -0,0 +1,166 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project overview
+
+Adapty documentation site (codename Cassiopeia). Built with **Astro 5 + MDX + React + Tailwind CSS 4**. Covers 7 SDK platforms: iOS, Android, React Native, Flutter, Unity, Kotlin Multiplatform, Capacitor.
+
+Deployed to **https://adapty.io/docs** via AWS S3 + CloudFront. GitHub Actions deploy `develop` → staging, `main` → production.
+
+## Commands
+
+```bash
+npm run dev          # Dev server at localhost:4321 (runs prebuild + build:md first)
+npm run build        # Production build → ./build/
+npm run preview      # Serve production build locally
+```
+
+No test suite or linter is configured. Package manager: **Yarn 1.22**.
+
+## Content architecture
+
+All articles live in `src/content/docs` as `.mdx` files. Subdirectories are for organization only — **URLs are derived from filename alone**, not folder path (e.g., `version-3.0/ios/sdk-installation-ios.mdx` → `/docs/sdk-installation-ios`).
+
+### Frontmatter schema
+
+```yaml
+title: "Required display title"
+description: "SEO description"
+metadataTitle: "Browser tab title | Adapty Docs"
+keywords: ['array', 'of', 'keywords']
+rank: 100          # Sort priority, default 50
+customSlug: "override-url"  # Optional URL override
+```
+
+### Navigation
+
+Sidebars are defined per platform in `src/data/sidebars/*.json` (ios, android, react-native, flutter, unity, kmp, capacitor, tutorial, api). Each entry references an article by its filename-based `id`. To add an article to navigation, add its id to the appropriate sidebar JSON.
+
+### Images
+
+- Article-specific: `src/assets/{article-name}/image.png`
+- Shared: `src/assets/shared/image.png`
+- Use `<ZoomImage id="image.png" width="700px" alt="desc" />` (preferred)
+- Legacy `<Zoom><img src={require(...)}/></Zoom>` still works
+
+### Path aliases
+
+- `@site` → repo root
+- `@components` → `src/components/`
+
+## Key components
+
+| Component | Import required? | Usage |
+|-----------|-----------------|-------|
+| `ZoomImage` | Yes | `<ZoomImage id="file.png" width="700px" alt="..." />` |
+| `Tabs`/`TabItem` | Yes | `<Tabs groupId="platform"><TabItem value="ios" label="iOS">...</TabItem></Tabs>` |
+| `Details` | Yes | `<Details summary="Title">content</Details>` |
+| `InlineTooltip` | Yes | `<InlineTooltip tooltip="hover text">[link](page.md)</InlineTooltip>` |
+| `CustomDocCardList` | Yes | `<CustomDocCardList ids={['id1','id2']} />` or `<CustomDocCardList />` for auto |
+| `Button` | **No** (auto-registered) | `<Button id="page-id">Text</Button>` or `<Button href="url">Text</Button>` |
+| `Callout` | **No** (remark plugin) | `:::note`, `:::tip`, `:::info`, `:::warning`, `:::danger`, `:::important`, `:::link` |
+
+Import path pattern: `import Component from '@site/src/components/Component.astro';`
+
+## Reusable content snippets
+
+`src/components/reusable/` contains MDX snippets that can be imported into multiple articles to avoid content duplication.
+
+## Remark/Rehype plugins (`src/plugins/`)
+
+- `remark-aside` — converts `:::note`/`:::tip`/etc. fenced directives into `<Callout>` components
+- `remark-transform-links` — strips `.md`/`.mdx` extensions from internal links
+- `remark-transform-require` — handles legacy `require()` image imports
+- `remark-transform-details` — processes `<Details>` components
+- `remark-heading-id` — auto-generates heading anchors
+- `remark-strip-imports` — removes imports during markdown export
+- `remark-strip-highlight-comments` — cleans highlight syntax
+
+## Code blocks
+
+````markdown
+```swift title="MyApp.swift" {2,4-6}
+// Line highlighting and title supported via Shiki transformers
+```
+````
+
+## Learning and Memory Management
+
+- YOU MUST use the journal tool frequently to capture technical insights, failed approaches, and user preferences
+- Before starting complex tasks, search the journal for relevant past experiences and lessons learned
+- Document architectural decisions and their outcomes for future reference
+- Track patterns in user feedback to improve collaboration over time
+- When you notice something that should be fixed but is unrelated to your current task, document it in your journal rather than fixing it immediately
+
+## Styling architecture
+
+### CSS files
+
+| File | Role |
+|------|------|
+| `src/styles/global.css` | **Primary stylesheet.** Tailwind import, theme variables (`@theme`), light/dark CSS custom properties, all design block styles (code blocks, details, callouts, tables, zoom images, heading anchors, task lists, highlight lines) |
+| `src/css/custom.css` | Legacy Docusaurus-era variables (`--purplePrimary`, `--ifm-*`). Still loaded via `src/css/custom.scss` but superseded by `global.css` for new work |
+| `src/css/api-reference.css` | Styles for the Stoplight API reference pages |
+| `src/css/fonts/fonts.css` | `@font-face` declarations for Inter, Roboto, Fira Code |
+
+### Theme system
+
+- Light/dark mode toggled via `.dark` class on `<html>` (persisted in `localStorage`)
+- All design tokens are CSS custom properties defined in `:root` (light) and `.dark` (dark) blocks in `global.css`
+- Key tokens: `--bg-primary`, `--bg-secondary`, `--text-primary`, `--text-secondary`, `--accent-primary` (`#5c13ff` light / `#a78bfa` dark), `--border-primary`, `--shadow-sm/md/lg`
+- Brand color: `--color-primary-500: #6720ff`
+- Fonts: Inter (body), Fira Code (code blocks)
+- Tailwind 4 configured in `global.css` via `@theme` block (custom font sizes, line heights, brand colors)
+
+### Design blocks in `global.css`
+
+These are the styled visual blocks that articles use — their CSS lives entirely in `global.css`:
+
+- **Code blocks** (`.code-block-wrapper`) — title bar, copy button, Shiki syntax highlighting, dark mode color inversion, diff styling, line highlighting (`.highlight-line`)
+- **Callouts** — rendered by remark-aside plugin into `<Callout>` (note/tip/info/warning/danger/important/link)
+- **Details/Accordion** (`details`/`summary`) — collapsible sections with chevron animation
+- **Ordered lists** (`.docs-prose ol`) — circular step-number bullets (Mintlify-inspired)
+- **Zoom images** (`.zoom-wrapper`, `.zoom-image`) — bordered, shadowed, hover-scale images
+- **Tables** — word-break handling, code wrapping within cells
+- **Heading anchors** (`.heading-anchor`) — hover-revealed link icon
+- **Task lists** (`li:has(input[type="checkbox"])`) — checkbox styling
+
+### Layout
+
+- Single layout: `src/layouts/DocsLayout.astro` — assembles Header, Sidebar, Breadcrumbs, article content, TableOfContents, FeedbackForm, Footer
+- Layout applies Tailwind prose classes (`.docs-prose`) to article content
+- Right column (ToC + feedback) visible at `xl:` (1280px+), sidebar at `lg:` (1024px+)
+- API reference pages use `isFullWidth` mode (no sidebar/ToC)
+
+### Page routing
+
+- `src/pages/[...slug].astro` — main catch-all route for doc articles
+- `src/pages/[slug].astro` + `src/pages/[slug]/[...rest].astro` — API reference pages
+
+### UI components (non-content)
+
+These are layout/interactive components in `src/components/`, not imported by article authors:
+
+- `Header.astro` — top nav with platform switcher, search, theme toggle
+- `Sidebar.astro` / `SidebarItem.astro` — left navigation tree
+- `PlatformSwitcher.astro` — SDK platform selector in header
+- `Search.astro` — Algolia-powered search
+- `ThemeToggle.astro` — light/dark mode switch
+- `TableOfContents.astro` — right-column heading navigation
+- `FeedbackForm.astro` — page feedback widget
+- `Breadcrumbs.astro` — breadcrumb trail
+- `Footer.astro` — page footer
+- `ZoomLightbox.astro` — fullscreen image lightbox overlay
+- `Calculator.tsx` — interactive React calculator widget
+- `ApiReferencePage.astro` — Stoplight Elements API docs wrapper
+
+## Build pipeline details
+
+- `prebuild` copies shared assets (images, API specs) to `public/`
+- `build:md` generates plain markdown exports and LLM-optimized files (`scripts/generate-md.mjs`, `generate-llms.mjs`, `generate-platform-llms-full.mjs`)
+- Production build runs `astro build` then `build:md:prod` (outputs to `./build/`)
+
+## Reference
+
+Comprehensive component examples and writing guidelines: `TECH_WRITERS_README.md`

context7.json

@@ -0,0 +1,4 @@
+{
+  "url": "https://context7.com/adaptyteam/adapty-docs",
+  "public_key": "pk_DR8Ko4Aa3rd5yAaPAyqPE"
+}

scripts/generate-llms.mjs

@@ -4,12 +4,13 @@ import { fileURLToPath } from 'node:url';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const SIDEBARS_DIR = path.resolve(__dirname, '../src/data/sidebars');
+const DOCS_BASE = path.resolve(__dirname, '../src/content/docs');
 
 // Get output dir from args or default to public
 const targetDirName = process.argv[2] || '../public';
 const OUTPUT_DIR = path.resolve(__dirname, targetDirName);
 
-const BASE_URL = 'https://docs.adapty.io'; // Base URL for public links
+const BASE_URL = 'https://adapty.io/docs'; // Base URL for public links
 
 // Helper: Ensure directory exists
 async function ensureDir(dir) {
@@ -20,19 +21,80 @@ async function ensureDir(dir) {
     }
 }
 
+// Find a doc file by searching all subdirectories under DOCS_BASE
+async function findDocFile(docId) {
+    const filename = `${docId}.mdx`;
+    async function search(dir) {
+        const entries = await fs.readdir(dir, { withFileTypes: true });
+        for (const entry of entries) {
+            if (entry.isDirectory()) {
+                const result = await search(path.join(dir, entry.name));
+                if (result) return result;
+            } else if (entry.name === filename) {
+                return path.join(dir, entry.name);
+            }
+        }
+        return null;
+    }
+    return search(DOCS_BASE);
+}
+
+// Extract description from MDX frontmatter
+function extractDescription(content) {
+    const match = content.match(/^---\s*\n([\s\S]*?)\n---/);
+    if (!match) return null;
+    const fmMatch = match[1].match(/^description:\s*["']?(.*?)["']?\s*$/m);
+    return fmMatch ? fmMatch[1] : null;
+}
+
+// Collect doc IDs from sidebar items recursively
+function collectDocIds(items, ids) {
+    for (const item of items) {
+        if (item.type === 'category') {
+            if (item.link && item.link.type === 'doc') ids.add(item.link.id);
+            if (item.items) collectDocIds(item.items, ids);
+        } else if (item.type === 'doc' && item.id) {
+            ids.add(item.id);
+        }
+    }
+}
+
+// Build a map of docId → description from all sidebar doc IDs
+async function buildDescriptionMap(sidebarFiles) {
+    const descriptions = new Map();
+
+    const allDocIds = new Set();
+    for (const file of sidebarFiles) {
+        if (!file.endsWith('.json')) continue;
+        const content = await fs.readFile(path.join(SIDEBARS_DIR, file), 'utf-8');
+        const data = JSON.parse(content);
+        const items = Array.isArray(data) ? data : [];
+        collectDocIds(items, allDocIds);
+    }
+
+    for (const docId of allDocIds) {
+        const filePath = await findDocFile(docId);
+        if (filePath) {
+            try {
+                const content = await fs.readFile(filePath, 'utf-8');
+                const desc = extractDescription(content);
+                if (desc) descriptions.set(docId, desc);
+            } catch { /* skip */ }
+        }
+    }
+
+    return descriptions;
+}
+
 // Recursive function to parse sidebar items
-function parseItems(items, depth = 0) {
+function parseItems(items, descriptions, depth = 0) {
     let output = '';
     const indent = '  '.repeat(depth);
 
     for (const item of items) {
         if (item.type === 'category') {
             // Add Category Header
             if (item.label) {
-                // Use consistent markdown header levels based on depth
-                // Tier 1: ### Label, Tier 2: #### Label, etc?
-                // Or just use bullet points for hierarchy which is often cleaner for LLMs.
-                // Let's use headers for top level, bullets for nested.
                 if (depth === 0) {
                     output += `\n### ${item.label}\n\n`;
                 } else {
@@ -42,16 +104,20 @@ function parseItems(items, depth = 0) {
 
             // If category has a link, add it as a doc item too
             if (item.link && item.link.type === 'doc') {
-                output += `${indent}  - [Overview](${BASE_URL}/${item.link.id}.md)\n`;
+                const desc = descriptions.get(item.link.id);
+                const suffix = desc ? `: ${desc}` : '';
+                output += `${indent}  - [Overview](${BASE_URL}/${item.link.id}.md)${suffix}\n`;
             }
 
             // Process children
             if (item.items) {
-                output += parseItems(item.items, depth + 1);
+                output += parseItems(item.items, descriptions, depth + 1);
             }
 
         } else if (item.type === 'doc') {
-            output += `${indent}- [${item.label || item.id}](${BASE_URL}/${item.id}.md)\n`;
+            const desc = descriptions.get(item.id);
+            const suffix = desc ? `: ${desc}` : '';
+            output += `${indent}- [${item.label || item.id}](${BASE_URL}/${item.id}.md)${suffix}\n`;
         } else if (item.type === 'link') {
             // External or manual link
             output += `${indent}- [${item.label}](${item.href})\n`;
@@ -64,8 +130,11 @@ async function generateLLMFiles() {
     await ensureDir(OUTPUT_DIR);
     const files = await fs.readdir(SIDEBARS_DIR);
 
-    let allContent = '# Full Documentation Index\n\n';
-    let mainContent = '';
+    // Build descriptions map upfront
+    const descriptions = await buildDescriptionMap(files);
+    console.log(`Loaded ${descriptions.size} descriptions from doc files`);
+
+    let allContent = '# Adapty Documentation\n\n> Adapty is an in-app purchase platform for mobile apps. It handles subscriptions, one-time purchases, and consumables — from purchase processing and receipt validation to analytics, A/B testing, and integrations.\n\n';
 
     for (const file of files) {
         if (!file.endsWith('.json')) continue;
@@ -76,14 +145,8 @@ async function generateLLMFiles() {
 
         // Generate content for this sidebar
         let sidebarContent = `# ${file.replace('.json', '')} Documentation\n\n`;
-        // Handle array root (tutorial.json) vs object root (others might be different? usually array in Docusaurus/classic structures)
-        // The file I read (tutorial.json) is an array. I'll assume all are arrays of items.
-
         let items = Array.isArray(sidebarData) ? sidebarData : [];
-        // If it's an object with 'items' or similar, handle that (Standard Docusaurus sidebars.js export object)
-        // But here we just see JSON arrays in the file listing.
-
-        sidebarContent += parseItems(items);
+        sidebarContent += parseItems(items, descriptions);
 
         // Save Platform Specific File
         const platformName = file.replace('.json', '');
@@ -94,14 +157,9 @@ async function generateLLMFiles() {
         allContent += sidebarContent + '\n---\n\n';
     }
 
-    // Write Main llms.txt (now same as full or containing all sidebars as requested)
-    // "llms.txt and llms-full.txt ... must contain content of all the sidebars"
+    // Write Main llms.txt
     await fs.writeFile(path.join(OUTPUT_DIR, 'llms.txt'), allContent);
     console.log('Generated: llms.txt (all sidebars)');
-
-    // Write Full Index (redundant but requested)
-    await fs.writeFile(path.join(OUTPUT_DIR, 'llms-full.txt'), allContent);
-    console.log('Generated: llms-full.txt');
 }
 
 generateLLMFiles().catch(console.error);

scripts/generate-md.mjs

@@ -118,7 +118,6 @@ async function processFiles(dir, reusableComponents) {
             const destPath = path.join(OUTPUT_DIR, `${basename}.md`);
 
             await fs.writeFile(destPath, content, 'utf-8');
-            console.log(`Generated: ${basename}.md`);
         }
     }
 }