docs: add guides

apps/public/content/docs/(tracking)/sdks/astro.mdx

@@ -3,9 +3,14 @@ title: Astro
 ---
 
 import { Step, Steps } from 'fumadocs-ui/components/steps';
+import { Callout } from 'fumadocs-ui/components/callout';
 import CommonSdkConfig from '@/components/common-sdk-config.mdx';
 import WebSdkConfig from '@/components/web-sdk-config.mdx';
 
+<Callout>
+Looking for a step-by-step tutorial? Check out the [Astro analytics guide](/guides/astro-analytics).
+</Callout>
+
 ## Installation
 
 <Steps>

apps/public/content/docs/(tracking)/sdks/express.mdx

@@ -4,11 +4,16 @@ description: The Express middleware is a basic wrapper around Javascript SDK. It
 ---
 
 import Link from 'next/link';
+import { Callout } from 'fumadocs-ui/components/callout';
 import { DeviceIdWarning } from '@/components/device-id-warning';
 import { PersonalDataWarning } from '@/components/personal-data-warning';
 
 import CommonSdkConfig from '@/components/common-sdk-config.mdx';
 
+<Callout>
+Looking for a step-by-step tutorial? Check out the [Express analytics guide](/guides/express-analytics).
+</Callout>
+
 ## Installation
 
 ```bash

apps/public/content/docs/(tracking)/sdks/index.mdx

@@ -13,7 +13,7 @@ For most web projects, we recommend starting with one of these:
 
 - **[Script Tag](/docs/sdks/script)** - The quickest way to get started, no build step required
 - **[Web SDK](/docs/sdks/web)** - For TypeScript support and more control
-- **[Next.js](/docs/sdks/nextjs)** - Optimized for Next.js applications
+- **[Next.js](/docs/sdks/nextjs)** - Optimized for Next.js applications | [Setup guide](/guides/nextjs-analytics)
 
 ## Web & Browser SDKs
 
@@ -38,23 +38,23 @@ For most web projects, we recommend starting with one of these:
 
 ### Frontend Frameworks
 
-- **[Next.js](/docs/sdks/nextjs)** - Optimized for Next.js
+- **[Next.js](/docs/sdks/nextjs)** - Optimized for Next.js | [Setup guide](/guides/nextjs-analytics)
   - ✅ Server and client side tracking
   - ✅ App Router support
   - ✅ Automatic route tracking
 
-- **[Astro](/docs/sdks/astro)** - Astro framework integration
+- **[Astro](/docs/sdks/astro)** - Astro framework integration | [Setup guide](/guides/astro-analytics)
   - ✅ Static and SSR support
   - ✅ Component-based tracking
   - ✅ Island architecture compatible
 
 - **[React](/docs/sdks/react)** - React integration
   - 📝 Use Script Tag or Web SDK for now
 
-- **[Vue](/docs/sdks/vue)** - Vue.js integration
+- **[Vue](/docs/sdks/vue)** - Vue.js integration | [Setup guide](/guides/vue-analytics)
   - 📝 Use Script Tag or Web SDK for now
 
-- **[Remix](/docs/sdks/remix)** - Remix framework integration
+- **[Remix](/docs/sdks/remix)** - Remix framework integration | [Setup guide](/guides/remix-analytics)
   - 📝 Use Script Tag or Web SDK for now
 
 - **Svelte** - Svelte integration
@@ -71,12 +71,12 @@ For most web projects, we recommend starting with one of these:
 
 ## Server-Side SDKs
 
-- **[Node.js (Express)](/docs/sdks/express)** - Express.js middleware
+- **[Node.js (Express)](/docs/sdks/express)** - Express.js middleware | [Setup guide](/guides/express-analytics)
   - ✅ Request tracking
   - ✅ Error tracking
   - ✅ Custom middleware support
 
-- **[Python](/docs/sdks/python)** - Python SDK for server-side tracking
+- **[Python](/docs/sdks/python)** - Python SDK for server-side tracking | [Setup guide](/guides/python-analytics)
   - ✅ Thread-safe
   - ✅ Async support
   - ✅ Django and Flask compatible
@@ -93,18 +93,18 @@ For most web projects, we recommend starting with one of these:
 
 ## Mobile SDKs
 
-- **[React Native](/docs/sdks/react-native)** - Cross-platform mobile analytics
+- **[React Native](/docs/sdks/react-native)** - Cross-platform mobile analytics | [Setup guide](/guides/react-native-analytics)
   - ✅ iOS and Android support
   - ✅ Native performance
   - ✅ Offline support
 
-- **[Swift](/docs/sdks/swift)** - Native iOS, macOS, tvOS, and watchOS SDK
+- **[Swift](/docs/sdks/swift)** - Native iOS, macOS, tvOS, and watchOS SDK | [Setup guide](/guides/swift-analytics)
   - ✅ Apple platform support
   - ✅ Swift Package Manager
   - ✅ Thread-safe API
   - ✅ Automatic lifecycle tracking
 
-- **[Kotlin / Android](/docs/sdks/kotlin)** - Native Android SDK
+- **[Kotlin / Android](/docs/sdks/kotlin)** - Native Android SDK | [Setup guide](/guides/kotlin-analytics)
   - ✅ Android support
   - ✅ System information collection
   - ✅ Thread-safe API

apps/public/content/docs/(tracking)/sdks/kotlin.mdx

@@ -9,6 +9,10 @@ import CommonSdkConfig from '@/components/common-sdk-config.mdx';
 
 The OpenPanel Kotlin SDK allows you to track user behavior in your Kotlin applications. This guide provides instructions for installing and using the Kotlin SDK in your project.
 
+<Callout>
+Looking for a step-by-step tutorial? Check out the [Kotlin analytics guide](/guides/kotlin-analytics).
+</Callout>
+
 ## Installation
 
 <Callout type="warn">

apps/public/content/docs/(tracking)/sdks/nextjs.mdx

@@ -7,9 +7,14 @@ import { Step, Steps } from 'fumadocs-ui/components/steps';
 
 import { DeviceIdWarning } from '@/components/device-id-warning';
 import { PersonalDataWarning } from '@/components/personal-data-warning';
+import { Callout } from 'fumadocs-ui/components/callout';
 import CommonSdkConfig from '@/components/common-sdk-config.mdx';
 import WebSdkConfig from '@/components/web-sdk-config.mdx';
 
+<Callout>
+Looking for a step-by-step tutorial? Check out the [Next.js analytics guide](/guides/nextjs-analytics).
+</Callout>
+
 ## Good to know
 
 Keep in mind that all tracking here happens on the client!

apps/public/content/docs/(tracking)/sdks/python.mdx

@@ -8,6 +8,10 @@ import CommonSdkConfig from '@/components/common-sdk-config.mdx';
 
 The OpenPanel Python SDK allows you to track user behavior in your Python applications. This guide provides instructions for installing and using the Python SDK in your project.
 
+<Callout>
+Looking for a step-by-step tutorial? Check out the [Python analytics guide](/guides/python-analytics).
+</Callout>
+
 ## Installation
 
 <Steps>

apps/public/content/docs/(tracking)/sdks/react-native.mdx

@@ -8,8 +8,13 @@ import { Step, Steps } from 'fumadocs-ui/components/steps';
 import { DeviceIdWarning } from '@/components/device-id-warning';
 import { PersonalDataWarning } from '@/components/personal-data-warning';
 
+import { Callout } from 'fumadocs-ui/components/callout';
 import CommonSdkConfig from '@/components/common-sdk-config.mdx';
 
+<Callout>
+Looking for a step-by-step tutorial? Check out the [React Native analytics guide](/guides/react-native-analytics).
+</Callout>
+
 ## Installation
 
 <Steps>

apps/public/content/docs/(tracking)/sdks/swift.mdx

@@ -9,6 +9,10 @@ import CommonSdkConfig from '@/components/common-sdk-config.mdx';
 
 The OpenPanel Swift SDK allows you to integrate OpenPanel analytics into your iOS, macOS, tvOS, and watchOS applications.
 
+<Callout>
+Looking for a step-by-step tutorial? Check out the [Swift analytics guide](/guides/swift-analytics).
+</Callout>
+
 ## Features
 
 - Easy-to-use API for tracking events and user properties

apps/public/content/guides/astro-analytics.mdx

@@ -0,0 +1,171 @@
+---
+title: "How to add analytics to Astro"
+description: "Add privacy-first analytics to your Astro site with OpenPanel. Track page views, custom events, and user behavior without cookies."
+difficulty: beginner
+timeToComplete: 5
+date: 2025-12-14
+cover: /content/cover-default.jpg
+team: OpenPanel Team
+steps:
+  - name: "Install the SDK"
+    anchor: "install"
+  - name: "Add the component to your layout"
+    anchor: "setup"
+  - name: "Track custom events"
+    anchor: "events"
+  - name: "Identify users"
+    anchor: "identify"
+  - name: "Verify your setup"
+    anchor: "verify"
+---
+
+# How to add analytics to Astro
+
+Adding analytics to your Astro site helps you understand how visitors interact with your content. This guide walks you through setting up OpenPanel to track page views, custom events, and user behavior in about five minutes.
+
+OpenPanel works well with Astro because it's a lightweight script that loads asynchronously and doesn't block your site's rendering. It tracks page views automatically across both static and server-rendered pages, and the component-based API fits naturally into Astro's architecture.
+
+## Prerequisites
+
+- An Astro project
+- An OpenPanel account ([sign up free](https://dashboard.openpanel.dev/onboarding))
+- Your Client ID from the OpenPanel dashboard
+
+## Install the SDK [#install]
+
+Start by adding the OpenPanel Astro package to your project. This package provides Astro components that handle initialization and tracking.
+
+```bash
+npm install @openpanel/astro
+```
+
+You can also use pnpm or yarn if that's your preference.
+
+## Add the component to your layout [#setup]
+
+The `OpenPanelComponent` initializes tracking and should be placed in your root layout so it loads on every page. Add it inside the `<head>` tag to ensure it initializes before any user interactions.
+
+```astro
+---
+import { OpenPanelComponent } from '@openpanel/astro';
+---
+
+<html>
+  <head>
+    <OpenPanelComponent
+      clientId="your-client-id"
+      trackScreenViews={true}
+      trackOutgoingLinks={true}
+    />
+  </head>
+  <body>
+    <slot />
+  </body>
+</html>
+```
+
+The `trackScreenViews` option automatically records a page view event whenever someone navigates to a new page. The `trackOutgoingLinks` option tracks when visitors click links that take them to external sites. Both are optional but recommended for most sites.
+
+You can also pass a `profileId` prop if you already know the user's identity at render time, and `globalProperties` to attach metadata to every event.
+
+## Track custom events [#events]
+
+Beyond automatic page views, you'll want to track specific interactions that matter to your business. OpenPanel exposes a global `op` function that you can call from any event handler.
+
+```astro
+<button onclick="window.op('track', 'button_clicked', {button_name: 'signup'})">
+  Sign up
+</button>
+```
+
+The first argument is always `'track'`, the second is your event name, and the third is an optional object of properties you want to attach to the event. Keep event names consistent across your codebase, using snake_case is a good convention.
+
+For elements where you'd rather not write JavaScript, you can use data attributes instead. Any element with a `data-track` attribute will automatically fire an event when clicked.
+
+```astro
+<button data-track="button_clicked" data-button-name="signup">
+  Sign up
+</button>
+```
+
+Properties are pulled from any `data-*` attributes on the element. The `data-track` value becomes the event name, and other data attributes become event properties.
+
+### Tracking form submissions
+
+Forms are a common tracking target. You can fire an event in the `onsubmit` handler while still allowing the form to submit normally.
+
+```astro
+<form onsubmit="window.op('track', 'form_submitted', {form_name: 'contact'}); return true;">
+  <input type="email" name="email" placeholder="Your email" required />
+  <button type="submit">Submit</button>
+</form>
+```
+
+The `return true` ensures the form submission continues after the tracking call.
+
+## Identify users [#identify]
+
+When a user logs in or you otherwise learn their identity, you can associate their activity with a profile. The `IdentifyComponent` handles this declaratively.
+
+```astro
+---
+import { IdentifyComponent } from '@openpanel/astro';
+
+const user = await getCurrentUser();
+---
+
+<IdentifyComponent
+  profileId={user.id}
+  firstName={user.firstName}
+  lastName={user.lastName}
+  email={user.email}
+  properties={{
+    plan: user.plan,
+  }}
+/>
+```
+
+Place this component on pages where the user is authenticated. Once identified, all subsequent events from that browser session will be linked to this profile until they clear their browser data or you explicitly clear the identity.
+
+### Setting global properties
+
+Sometimes you want to attach the same properties to every event, like an app version or environment. The `SetGlobalPropertiesComponent` lets you do this once rather than repeating it in every tracking call.
+
+```astro
+---
+import { SetGlobalPropertiesComponent } from '@openpanel/astro';
+---
+
+<SetGlobalPropertiesComponent
+  properties={{
+    app_version: '1.0.2',
+    environment: import.meta.env.MODE,
+  }}
+/>
+```
+
+These properties merge with any event-specific properties you pass to individual tracking calls.
+
+## Verify your setup [#verify]
+
+Open your Astro site in the browser and navigate between a few pages. Then open your [OpenPanel dashboard](https://dashboard.openpanel.dev) and check the Real-time view. You should see page view events appearing within seconds.
+
+If events aren't showing up, open your browser's developer console and look for errors. The most common issues are an incorrect Client ID or an ad blocker preventing the tracking script from loading. You can also check the Network tab to confirm requests are being sent to OpenPanel's servers.
+
+## Next steps
+
+The [Astro SDK reference](/docs/sdks/astro) covers additional configuration options like filtering events and customizing the CDN URL. If you're interested in running OpenPanel on your own infrastructure, the [self-hosting guide](/articles/how-to-self-host-openpanel) walks through the setup process.
+
+<Faqs>
+<FaqItem question="Does OpenPanel work with Astro Islands?">
+Yes. The OpenPanelComponent is a client-side script that hydrates independently of your island components. It will track interactions across your entire page regardless of which parts are hydrated.
+</FaqItem>
+
+<FaqItem question="Can I use OpenPanel with Astro's SSR mode?">
+Yes. OpenPanel works with both static and server-rendered Astro sites. The tracking script runs in the browser regardless of how the page was rendered.
+</FaqItem>
+
+<FaqItem question="Does OpenPanel use cookies?">
+No. OpenPanel uses cookieless tracking by default, which means you don't need cookie consent banners for basic analytics under most privacy regulations including GDPR. Read more about [cookieless analytics](/articles/cookieless-analytics).
+</FaqItem>
+</Faqs>