---
title: Getting Started
description: Create a Geistdocs project and start writing documentation
type: guide
summary: Create a Geistdocs project, run it locally, and edit your first documentation page.
url: /docs/getting-started
source: apps/template/content/docs/getting-started.mdx
related:
  - /docs/configuration
  - /docs/migration
  - /docs/syntax
  - /docs/deployment
---

# Getting Started

Create a new Geistdocs site with the package CLI, then customize its identity, content, and navigation. If you already have a documentation site, use [Migrate to Geistdocs](/docs/migration). Read [Choose a Geistdocs package](/docs/packages) before using the private package.

> Note:
  Use `@vercel/geistdocs-private` only for Vercel-internal applications that
  are not open source and already restrict npm access to authorized Vercel
  users, such as `next-site` or `vercel-docs`. Vercel-owned OSS repositories,
  repositories with external contributors, and all other projects must use the
  public `@vercel/geistdocs` package. See
  [Choose a Geistdocs package](/docs/packages) for the full comparison.

  Create a new Geistdocs project with `pnpm dlx @vercel/geistdocs@latest init --name my-docs`. Confirm the prerequisites, run `pnpm dev`, and help me customize `geistdocs.tsx`, `content/docs/index.mdx`, and `content/docs/meta.json`. Keep the generated integrations package-backed.

## Prerequisites

Before you begin, install:

- Node.js 20.9 or later
- pnpm
- Git

The CLI always uses pnpm to install the generated project's dependencies.

## Create a project

Run the Geistdocs CLI from an empty parent folder. For stable Geistdocs, run:

```bash title="Terminal"
pnpm dlx @vercel/geistdocs@latest init --name my-docs
```

The CLI copies the template bundled in the package, rewrites the generated app to depend on the same `@vercel/geistdocs` version, installs dependencies, copies `.env.example` to `.env.local`, and initializes Git.

### Create a Labs starter

To reuse the same template with [Vercel Labs](https://vercel.com/labs) navbar branding, run:

```bash title="Terminal"
pnpm dlx @vercel/geistdocs@latest init --name my-labs-docs --brand labs
```

`--brand` accepts `vercel` (default) or `labs`. Omitting it or passing `--brand vercel` preserves the starter defaults. Invalid values fail before prompts or writes. Add `--disable-git` to skip Git initialization, not dependency installation.

Labs changes only `navbarBrand` in `geistdocs.tsx`, independently of the `navbarVariant` layout, project `Logo`, and navigation.

`@vercel/geistdocs-private` accepts the same flag. Its public-repository prompt still selects the public or private package; either choice preserves the selected brand.

Read [Choose a navbar brand](/docs/configuration#choose-a-navbar-brand) to change the brand in an existing project.

## Understand generated dependencies

Generated projects pin the resolved package version and include AI SDK v6 and `@ai-sdk/react` v3. The public package does not require private npm access. The template already configures styles, fonts, Cache Components, Partial Prefetching, source adapters, search, Ask AI, and agent-readable routes.

Keep those integrations package-backed. Update Geistdocs instead of copying package internals into the app.

## Start the development server

Open the generated project and start Next.js:

```bash title="Terminal"
cd my-docs
pnpm dev
```

Open `http://localhost:3000` in your browser.

Start with these files:

- `geistdocs.tsx` for the site title, logo, navigation, repository, and AI prompt.
- `content/docs/index.mdx` for the documentation overview.
- `content/docs/meta.json` for sidebar order and groups.

Only customize `components/geistdocs/*`, `lib/geistdocs/*`, or route adapters when the generated defaults do not fit your site.

## Edit your first page

Docs live in `content/docs`. Edit the overview page:

```mdx title="content/docs/index.mdx"
---
title: Overview
description: Learn how to use my project.
---

My project helps developers build with clear documentation.

## Start here

Add the first workflow you want readers to complete.
```

Add more pages by creating new `.mdx` files in `content/docs`.

## Update the sidebar

Use `content/docs/meta.json` to control page order and groups:

```json title="content/docs/meta.json"
{
  "title": "Documentation",
  "root": true,
  "pages": ["index", "getting-started", "---Guides---", "deploy"]
}
```

Page and folder entries use names without extensions. A value such as `---Guides---` creates a non-clickable separator label. Read [Configure sidebar navigation](/docs/guides/nested-navigation) to add folder landing pages, deeply nested folders, custom links, and `defaultOpen` behavior.

## Configure the site

Use `geistdocs.tsx` to customize the site shell:

```tsx title="geistdocs.tsx"
export const title = "My Documentation";

export const nav = [
  { label: "Docs", href: "/docs" },
  { label: "GitHub", href: "https://github.com/my-org/my-repo" },
];
```

Read [Configuration](/docs/configuration) for the full configuration surface.

## Update Geistdocs

For package-based projects, `geistdocs update` updates the `@vercel/geistdocs` package version. It does not overwrite your local content or adapter files. Projects already using a canary version continue to follow the `canary` dist-tag; stable projects follow `latest`.

```bash title="Terminal"
pnpm exec geistdocs update
```

Review and test dependency changes before committing.

## Verify and deploy

Run a production build before publishing:

```bash title="Terminal"
pnpm build
```

Then follow [Deploy to Vercel](/docs/deployment), including environment-variable setup. Private-package access is required only for `@vercel/geistdocs-private`.