> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.knapsack.cloud/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.knapsack.cloud/_mcp/server.

# Storage Options

Every Knapsack workspace stores content in one of two places: **Knapsack Database** or **your Git repository**. Database storage gets you started instantly. Git storage gives you version control, CI/CD integration, and live component previews.

***

|                             | Knapsack Database | Git Repository                  |
| --------------------------- | ----------------- | ------------------------------- |
| **Setup time**              | Instant           | Requires deployment             |
| **Branching**               | ✓                 | ✓                               |
| **Review workflow**         | In Knapsack UI    | In Knapsack UI (creates Git PR) |
| **Commit history & diffs**  | —                 | ✓                               |
| **Live component previews** | —                 | ✓                               |
| **CI/CD integration**       | —                 | ✓                               |
| **Content in your repo**    | —                 | ✓                               |

***

## Which Should You Choose?

**Choose Knapsack Database when you want to:**

* Start documenting immediately—no deployment or Git setup required
* Keep your review workflow entirely in Knapsack
* Try Knapsack before committing to full Git integration

**Choose Git Repository when you want to:**

* Full version history and diffs for all content changes
* Live component previews showing your actual code
* Pull Request workflows with your existing review process
* CI/CD integration and content stored locally in your repo

**Not sure which to pick?** Start with Database storage. You can migrate to Git later without losing any content.

***

## What's Stored Where?

Understanding where your content lives helps you plan your workflow and know what to expect during migration.

### Content you control

Your storage choice (Database or Git) determines where this content lives:

| Content                     | Database mode     | Git mode              |
| --------------------------- | ----------------- | --------------------- |
| Pages and documentation     | Knapsack database | Your repo (YAML/JSON) |
| Design tokens and variables | Knapsack database | Your repo (YAML/JSON) |
| Asset sets                  | Knapsack database | Your repo (YAML/JSON) |
| Navigation structure        | Knapsack database | Your repo (YAML/JSON) |
| Pattern definitions         | Knapsack database | Your repo (YAML/JSON) |
| Block content               | Knapsack database | Your repo (YAML/JSON) |
| Demos and tabs              | Knapsack database | Your repo (YAML/JSON) |

### Content Knapsack manages

These stay on Knapsack Cloud regardless of your storage choice—you don't need to manage or migrate them.

| Content                       | Where it lives |
| ----------------------------- | -------------- |
| Uploaded files (images, PDFs) | Knapsack CDN   |
| User accounts and permissions | Knapsack Cloud |
| Branch metadata               | Knapsack Cloud |
| Edit history                  | Knapsack Cloud |

### Content in your codebase

These always live in your repository, independent of your storage choice.

| Content              | Where it lives  |
| -------------------- | --------------- |
| Code components      | Your repository |
| Build configuration  | Your repository |
| Package dependencies | Your repository |
| Knapsack config      | Your repository |

Knapsack reads from your codebase to discover components and render live previews. Your storage choice only affects where documentation content lives—not your code.

**Live previews require a hosted design system.** Your components (Button, Card, Modal) need to be running somewhere Knapsack can reach—cloud-hosted environments like Heroku, self-hosted, or custom domain. Database storage is for teams who want to start documenting before setting that up.

***

## How Branching Works

| Step               | Database storage            | Git Storage                                |
| ------------------ | --------------------------- | ------------------------------------------ |
| **Create Branch**  | Branch created in Knapsack  | Branch created in Knapsack + your Git repo |
| **Make Edits**     | Changes tracked in Knapsack | Changes saved as Git commits               |
| **Request review** | Review in Knapsack          | Review in Knapsack + PR opened             |
| **Publish**        | Changes go live immediately | PR merges → deployment pipeline runs       |

***

## Migrating to Git

Already using Knapsack Database and want to switch to Git? Migration preserves all your content.

Migration is one-way. Once you migrate to Git, you can't switch back to Database storage.

### Requirements

Before you begin, make sure you have:

* Admin permissions in your Knapsack workspace
* A Git provider account (GitHub, GitLab, Bitbucket, or Azure DevOps)
* A deployment URL where your design system is hosted—Knapsack's cloud services need network access to this URL

### Step 1: Request migration access

Contact Knapsack support to enable migration for your workspace. Once enabled, a **Configuration** page appears under Settings → Administration.

### Step 2: Configure your connections

Go to **Settings → Configuration** and add:

* Your **Deployment URL** — where your design system is hosted
* Your **Git Provider** — connect to GitHub, GitLab, Bitbucket, or Azure DevOps

Click **Save Changes** to validate both connections.

### Step 3: Prepare for migration

* Notify your team about the upcoming content freeze
* Publish or delete all open branches — the Start Migration button stays locked until all branches are closed

### Step 4: Start migration

Click **Start Migration** in Settings → Configuration. Knapsack will:

1. Create a branch in your repository containing all your content
2. Open a Pull Request for you to review
3. Freeze publishing until migration is complete

**What you'll see:** A PR containing YAML and JSON files for your pages, tokens, navigation, and settings.

### Step 5: Complete migration

1. Review and merge the PR in your Git provider
2. Wait for your deployment to update with the new content
3. Contact Knapsack support to lift the publishing freeze
4. Notify your team they can resume editing

**What gets migrated:** Pages, tokens, navigation, blocks, demos, tabs, block collections, asset sets, and settings all move to your repository.

***

## FAQ

**Can I switch from Git back to Database?**

**No.** Migration is one-way—once your content is in Git, it stays there. If you have a specific need to revert, contact Knapsack support to discuss options.

**Will I lose content during migration?**

**No.** Migration exports all your content to a Pull Request in your repository. Uploaded files (images, PDFs) remain on Knapsack's CDN and continue working after migration.

**Why don't live component previews work with Database storage?**

Live component previews require Git storage mode. When content is stored in the database, Knapsack doesn't connect to your deployment—even if you have one configured. This is by design: Database storage is for workspaces that want to start quickly without deployment setup.

**Can I use Database storage for documentation only (no code)?**

**Yes.** Database storage is ideal for design system documentation, tokens, guidelines, and pattern definitions without connecting to code components.

**What happens to my open branches during migration?**

You must publish or delete all open branches before migration can start. Once all branches are closed, workspace admins can click **Start Migration** to begin the process.

**How long does migration take?**

The migration PR is created immediately. The total timeline depends on:

* How long your team takes to review the PR
* Your deployment pipeline speed (typically 2–10 minutes)
* Any merge conflicts that need resolution

**What if the migration PR has conflicts?**

Resolve conflicts in your Git provider (GitHub/GitLab), then merge. This typically happens if your repository already has Knapsack content files.

**Do I need to re-upload images after migration?**

**No.** Uploaded files stay on Knapsack's CDN and continue working after migration. Only the content structure (pages, tokens, etc.) moves to Git.

***

## Troubleshooting

**Migration button is disabled**

You have open branches. Publish or delete all branches with "Draft" or "Review Requested" status before migrating.

**Can't find the Configuration page**

The Configuration page only appears after Knapsack support enables migration for your workspace. Contact support if you don't see it under Settings → Administration.

**Git provider connection fails**

Check that your Git credentials have write access to the repository. For GitHub, ensure your token has `repo` scope. For GitLab, ensure `api` and `write_repository` scopes.

**Deployment validation fails**

Verify your deployment URL is accessible to Knapsack's cloud services and running a Knapsack App Client. The URL should return a valid response when visited in a browser.

**Live previews not working after migration**

Verify your deployment URL is accessible to Knapsack's cloud services and running a Knapsack App Client. For firewall-protected deployments, ensure Knapsack's static IP is whitelisted.