---
title: How Jamdesk Works
description: Git push to live docs in under 60 seconds. Learn how Jamdesk builds, deploys, and optimizes your documentation site with zero infrastructure to manage.
---

> **For AI agents:** the complete documentation index is at [llms.txt](/docs/llms.txt). Append `.md` to any page URL for its markdown version.

Jamdesk builds documentation sites from MDX files in your GitHub repo. You write Markdown with React components, push to GitHub, and your site is live on a global CDN in under 60 seconds. Your content stays in your repo as plain files. Nothing proprietary, nothing to migrate away from.

## Architecture Overview

Your repo is the source of truth. Jamdesk connects to it, builds your site, and deploys to a global edge network. You don't manage any infrastructure.

<Frame caption="How content flows from your repo to your users">
  <Mermaid minWidth="700px">
{`%%{init: {'theme': 'neutral', 'themeVariables': {'background': 'transparent'}, 'flowchart': {'nodeSpacing': 25, 'rankSpacing': 40, 'curve': 'basis', 'useMaxWidth': false}}}%%
flowchart LR
    subgraph Source["Your Repository"]
        A[("MDX Files")]
        B[("docs.json")]
    end

    subgraph Build["Build Phase"]
        C["Validate"]
        D["Process"]
    end

    E[("CDN Storage")]

    subgraph Serve["Serve Phase"]
        F["Render on Request"]
        G["Edge Cache"]
    end

    Source -->|"git push"| C
    C --> D
    D -->|"Upload"| E
    E --> F
    F --> G
    G -->|"< 50ms"| H["Your Users"]`}
  </Mermaid>
</Frame>

## The Build Pipeline

Typically 30–60 seconds, start to finish. Builds are fast because Jamdesk doesn't pre-render pages. Your raw content goes to the edge, and pages render on-demand when visitors request them.

<Steps>
  <Step title="Source Retrieval">
    You push to your connected GitHub branch (or hit Rebuild in the dashboard). Jamdesk clones your repo and finds your docs directory.
  </Step>
  <Step title="Validation">
    Your `docs.json` config is validated against the schema, and internal links are checked for broken pages and bad anchors.
  </Step>
  <Step title="Content Processing">
    Jamdesk generates your search index, [AI chat](/ai/chat) embeddings, sitemap, [`llms.txt`](/ai/llms-txt), and redirect rules from your content.
  </Step>
  <Step title="Deploy to Edge">
    Content uploads to the CDN and propagates to 300+ edge locations. Only changed files transfer, so redeploys are fast.
  </Step>
</Steps>

## Built Into Every Site

All of this comes free with every site. Nothing to configure.

<Columns cols={2}>
  <Card title="AI Search" icon="magnifying-glass" href="/ai/chat">
    Natural language search that understands intent, not just keywords. Powered by vector embeddings generated from your content at build time.
  </Card>
  <Card title="llms.txt" icon="robot" href="/ai/llms-txt">
    AI-readable index following the llmstxt.org spec. Coding assistants and AI agents can consume your docs directly.
  </Card>
  <Card title="SEO Essentials" icon="chart-line">
    Sitemap, robots.txt, Open Graph images, and meta tags. Your docs are indexable from the first deploy.
  </Card>
  <Card title="Built-in Analytics" icon="chart-bar" href="/setup/analytics-overview">
    Privacy-focused analytics dashboard with no cookies required. Or bring your own — supports Google Analytics, Plausible, PostHog, and more.
  </Card>
</Columns>

## What Triggers a Build

A git push to your connected branch, the Rebuild button in the dashboard, or [`jamdesk deploy`](/cli/deploy) from the CLI. If you push multiple commits in quick succession, Jamdesk debounces them into one build so you're not burning resources.

For operational details (status monitoring, rollbacks, environment variables, branch deployments), see [Build & Deploy Lifecycle](/deploy/lifecycle).

## Security & Infrastructure

You don't need to think about this stuff, but if your security team asks: builds run in isolated containers and your GitHub App connection is read-only.

<Columns cols={2}>
  <Card title="Minimal Permissions" icon="shield-check">
    The GitHub App only requests read access to repositories you select. No write access, no org-wide scopes.
  </Card>
  <Card title="Isolated Builds" icon="box">
    Every build gets its own container that's destroyed after deployment. Nothing persists between builds or customers.
  </Card>
  <Card title="HTTPS Everywhere" icon="lock">
    Automatic SSL certificates for custom domains and subdomains. No manual cert management.
  </Card>
  <Card title="Global CDN" icon="globe">
    Served from Cloudflare's network with 300+ edge locations and 99.9% uptime.
  </Card>
</Columns>

## Performance

Whether your docs get found depends partly on how fast they load. Google uses [Core Web Vitals](https://jamdesk.com/blog/why-google-pagespeed-matters) as a ranking signal, and AI crawlers like GPTBot and ClaudeBot give themselves 1–5 seconds per page. If your docs don't load in that window, they don't get cited.

Every Jamdesk site ships from the edge with sub-50ms time to first byte. Fast enough for Google, fast enough for AI crawlers to cite.

| Metric | Typical Value |
|--------|---------------|
| Build time | 30-60 seconds |
| Deploy propagation | < 30 seconds |
| First byte (edge) | < 50ms |
| Full page load | < 500ms |

## Next Steps

<Columns cols={3}>
  <Card title="Create a Project" icon="plus" href="/setup/creating-projects">
    Set up a new documentation site in the dashboard
  </Card>
  <Card title="Connect GitHub" icon="github" href="/setup/connecting-github">
    Link your repository to enable automatic builds
  </Card>
  <Card title="Preview Locally" icon="terminal" href="/cli/overview">
    Use the Jamdesk CLI to preview and validate your docs before you push
  </Card>
</Columns>