Tiger Data Docs

Documentation site for Tiger Data, built on Astro 6, Starlight, and the Stainless Docs renderer.

Prerequisites

• Node.js (v22.12.0 or later, as required by package.json): nodejs.org
• pnpm (package manager): install with npm install -g pnpm or see pnpm.io/installation

Development quickstart

1. Clone the repo and cd into it
2. Install dependencies: pnpm install
3. Start the dev server: pnpm dev
4. Visit localhost:4321

The development server and production build run without external API credentials. dev:local and build:local remain as aliases for compatibility.

Other commands

pnpm build         # Build for production
pnpm build:local   # Alias for pnpm build
pnpm dev:local     # Alias for pnpm dev
pnpm preview       # Preview production build
pnpm format        # Format code

The Tiger Cloud REST reference is generated locally from stainless/openapi.yml and stainless/stainless.yml. See stainless/README.md for provenance and update instructions.

Site structure

All documentation content lives under src/content/docs/. The structure follows the new Information Architecture with categorical sections, each containing subcategories and individual pages.

Main sections

Folder	Description
get-started/	Welcome and quickstart content for new users
learn/	Conceptual learning content, fundamentals, and deep-dives
build/	Task-oriented guides organized by feature
migrate/	Migration guides from other databases
integrate/	Tool and framework integrations
reference/	API reference, SQL functions, and configuration
deploy/	Deployment options (cloud, self-hosted)

Folder hierarchy

Each main section follows a three-level hierarchy:

src/content/docs/
└── {section}/              # Main section (e.g., build, learn, deploy)
    ├── index.mdx           # Landing page for the section
    └── {category}/         # Category folder (e.g., columnar-storage)
        ├── index.mdx       # Category landing page (optional)
        └── {page}.mdx      # Individual pages (alphabetically ordered)

Example: the build/ section:

build/
├── index.mdx                      # Build section landing page
├── columnar-storage/
│   └── setup-hypercore.mdx
├── continuous-aggregates/
├── cost-optimization/
├── data-management/
├── examples/
├── how-to/
├── performance-optimization/
└── tips-and-tricks/

Key points

• The index.mdx in each folder serves as the "home" or "landing page" for that section/category
• Pages within category folders are ordered alphabetically
• Content was drafted/migrated from existing docs during the IA restructure
• Each subcategory should have sub-pages built out and prepped for migration

Integrate section: hide a page from the /integrate card grid

The Integrate overview page (src/content/docs/integrate/index.mdx) shows a searchable card grid of integrations. Some pages (for example Troubleshoot) should stay in the sidebar and remain reachable by URL, but should not appear as a card on that overview.

In the page’s frontmatter, set:

integrationHideFromOverviewCards: true

This only removes the page from the card grid (and from the overview’s filter options that are derived from visible cards). It does not remove the page from the Starlight sidebar or from search indexing.

Integrate overview: Technology filter and frontmatter

The Technology dropdown on /integrate tags each card with one or more technology labels so readers can filter (for example AWS, Kafka, PostgreSQL). Labels must be declared in the content schema or Astro strips them:

1. keywords (optional array of strings): used for search and, when integrationTechnologies is omitted, to infer technologies by matching substrings (see src/lib/integration-technologies.ts). Example: a keyword containing kafka maps to the Kafka filter.

2. integrationTechnologies (optional array): explicit tags. Use when inference is wrong or too broad. Allowed values are exactly: PostgreSQL, Python, Ruby, Node.js, Go, Java, SQL, Kafka, MQTT, OPC UA, Apache Iceberg, AWS, Azure, GCP, Terraform, Kubernetes, Grafana, Prometheus (the source of truth is INTEGRATION_TECHNOLOGY_KEYS in src/lib/integration-technologies.ts).

Example:

keywords: ["kafka integration", "event streaming"]
integrationTechnologies: ["Kafka", "AWS"]

If you set integrationTechnologies, it replaces inference from keywords for that page (the explicit list wins).

Documentation platform

The site uses Astro and Starlight directly. Project-owned components in src/components/ provide custom callouts, cards, tabs, badges, and navigation.

→ Component usage guide (README-component.md): how to use callouts (Tip, Note, Important, Warning, Callout with button) and other custom components. Instructions are in collapsible sections so you can expand only what you need.

Environment

No environment variables are required for a local build. Optional integrations are documented in .env.example.

Optional: Sentry error monitoring

The site uses @sentry/astro for client and server error monitoring. Set SENTRY_DSN in your environment (or as a CI/CD secret) to enable it:

SENTRY_DSN=https://<key>@o<org>.ingest.us.sentry.io/<project>

Omitting the variable disables Sentry silently: no errors, no events captured.

Sentry MCP for AI assistants

The repo includes pre-configured Sentry MCP configs so AI coding assistants can query Sentry issues, stack traces, and alerts directly:

• .mcp.json: Claude Code (project-level config)
• .cursor/mcp.json: Cursor
• .vscode/mcp.json: VS Code / GitHub Copilot

No extra setup is needed; your assistant discovers the config automatically when you open the repo.

Optional: Algolia instead of Pagefind

By default, search uses Pagefind and needs no extra service. To use Algolia, set the four variables in .env.example.

Doc constants (brand and product variables)

The repo uses shared constants so product and database names can be changed in one place. They live in src/constants.ts and are imported in MDX, Astro, and TS as @constants.

In MDX (docs and partials):

1. At the top of the file, add: import * as C from "@constants"; (if not already present).
2. Use the constants in prose and headings with curly braces, for example {C.PG}, {C.CLOUD_LONG}, {C.TIMESCALE_DB}.

Examples:

• Prose: Connect to {C.PG} and run the query.
• Headings: ## Using {C.PG} with time-series data
• In component props (JS expressions): title={`Install ${C.PG}`}

The database name is intentionally centralized: use {C.PG} or {C.POSTGRESQL} instead of literal "PostgreSQL" or "Postgres" in prose and headings. This is nudged by the TigerData.ProductConstants Vale rule; run pnpm lint:prose to check changed files (see the vale.yml CI workflow). Exceptions: literal "PostgreSQL"/"Postgres" is allowed inside URLs (for example, https://postgresql.org) and inside backticks (UI elements, code, file paths, commands).

Right-rail Learn more card

Any page can surface a "Learn more" card in the right rail (tutorials, related blog posts, and an optional CTA button) by adding a learnMore block to its frontmatter. No imports or per-page wiring required: the card renders automatically when the key is present and hides itself when it isn't.

Minimal example (drop this into any page's frontmatter):

learnMore:
  tutorials:
    - label: Your first hypertable
      href: /build/how-to/your-first-hypertable/
  relatedPosts:
    - label: Why use hypertables
      href: https://www.timescale.com/blog/why-hypertables/
  cta:
    label: Try for free
    href: https://console.cloud.tigerdata.com/signup

→ See src/components/LearnMore.README.md for the full authoring guide: 8 copy-paste recipes (tutorial pages, concept pages, quickstarts, reference pages, custom headings, external links, CTA-only, and so on), field reference, troubleshooting, architecture, and theming notes.

Want to learn more?

• Starlight docs
• Astro docs