Build and Deploy Markdown source

---
title: "Build and Deploy"
description: "The full pipeline — dev server, production build, Pagefind search, and Cloudflare Pages."
kind: guide
maturity: evergreen
confidence: high
origin: ai-drafted
author: "Agent"
directedBy: "krow"
tags: [astro, fundamentals]
published: 2026-03-15
modified: 2026-05-31
wordCount: 1020
readingTime: 5
series: "learn-astro"
series_order: 9
prerequisites: [astro-mental-model]
url: https://krowdev.com/guide/astro-build-and-deploy/
---
## Agent Context

- Canonical: https://krowdev.com/guide/astro-build-and-deploy/
- Markdown: https://krowdev.com/guide/astro-build-and-deploy.md
- Full corpus: https://krowdev.com/llms-full.txt
- Kind: guide
- Maturity: evergreen
- Confidence: high
- Origin: ai-drafted
- Author: Agent
- Directed by: krow
- Published: 2026-03-15
- Modified: 2026-05-31
- Words: 1020 (5 min read)
- Tags: astro, fundamentals
- Series: learn-astro (#9)
- Prerequisites: astro-mental-model
- Content map:
  - h2: The Three Commands
  - h3: Dev Server
  - h3: Production Build
  - h2: Pagefind — Build-Time Search
  - h2: Cloudflare Pages Deployment
  - h2: The Full Workflow
  - h2: What You've Learned
  - h2: Sources
- Diagrams: Mermaid fences are paired with adjacent ASCII companions in this document (1 Mermaid, 1 ASCII); HTML figures expose rendered SVG plus copyable Mermaid/ASCII source tabs.
- Crawl policy: same canonical content is exposed through HTML, Markdown, and llms-full; no crawler-specific content gate.

## The Three Commands

This assumes you have shipped [content collections](/guide/astro-content-collections/) and understand [markdown rendering](/guide/astro-markdown-and-code/). For the wider stack philosophy see the [mental model](/guide/astro-mental-model/) and the way [.astro files](/guide/astro-files/) compose into static output.

| Command | What It Does | Analogy |
|---|---|---|
| `npm run dev` | Starts live-reload dev server at localhost:4321 | `jupyter notebook` — hot-reloading preview |
| `npm run build` | Compiles everything to `dist/` | `make all` — full production build |
| `npm run preview` | Serves `dist/` locally | Opening the final PDF to check it |

### Dev Server

```bash
npm run dev
```

Opens `http://localhost:4321`. When you edit an `.astro`, `.md`, or `.css` file, the browser auto-refreshes. Use this while writing content and tweaking design.

:::key
The dev server runs your build pipeline on every change, but incrementally — only recompiling what changed. It's fast because Astro uses Vite under the hood, which does hot module replacement.
:::

### Production Build

```bash
npm run build
```

krowdev's build command chains three steps:

```json
"build": "node scripts/check-mermaid-cache.mjs && astro build && npx pagefind --site dist"
```

1. **`node scripts/check-mermaid-cache.mjs`** — verifies the pre-rendered Mermaid diagram cache is current before the build
2. **`astro build`** — compiles all pages, optimizes images, downloads fonts, generates sitemap
3. **`npx pagefind --site dist`** — scans the HTML output and builds a search index

The output lands in `dist/`:

```tree
dist/
├── index.html                          # homepage
├── guide/
│   ├── agentic-coding-getting-started/index.html
│   ├── agentic-coding-prompt-patterns/index.html
│   ├── astro-mental-model/index.html
│   └── ... (one per guide entry)
├── article/
│   └── welcome-to-krowdev/index.html
├── _astro/
│   ├── fonts/                          # self-hosted Inter + JetBrains Mono
│   └── *.css                           # compiled stylesheets
├── pagefind/                           # search index
│   ├── pagefind-entry.json
│   └── fragment/...
├── favicon.svg
└── sitemap-index.xml
```

:::analogy
This `dist/` folder is your final artifact — like a compiled binary or a rendered PDF. Everything needed to serve the site is in there. No runtime dependencies, no database, no server process.
:::

## Pagefind — Build-Time Search

Pagefind creates a client-side search engine from your static HTML. It:

1. Scans all `.html` files in `dist/`
2. Extracts text from elements with `data-pagefind-body`
3. Builds a compressed search index
4. Ships a tiny JS widget that searches the index in the browser

The search index is typically 10-50KB — small enough to load instantly. No server needed.

In krowdev, kb entries have `data-pagefind-body` on their content area:

```astro
<article data-pagefind-body>
  <slot />
</article>
```

This tells Pagefind: "index the content inside this element." Headers, footers, and sidebars are excluded.

## Cloudflare Pages Deployment

Cloudflare Pages serves the `dist/` folder. Setup:

1. **Push to GitHub** — your repo containing the Astro project at the root
2. **Connect in Cloudflare Dashboard** — Workers & Pages → Create → Connect to Git
3. **Configure build:**
   - Root directory: leave blank (or set to your subdirectory if you use a monorepo)
   - Build command: `npm run build`
   - Output directory: `dist`
   - Environment variable: `NODE_VERSION` = `24` (match your project's `engines.node`)
4. **Auto-deploy** — every push to `main` triggers a rebuild

```mermaid
graph LR
  accTitle: Push-to-deploy pipeline
  accDescr: Pushing code fires a GitHub webhook that triggers a Cloudflare Pages build, which publishes the site.
  push["You push code"] --> hook["GitHub webhook"] --> build["Cloudflare builds"] --> live["Site goes live"]
```
```ascii
You push code → GitHub webhook → Cloudflare builds → site goes live
```

Cloudflare's free tier: unlimited bandwidth, 500 builds/month, global CDN. More than enough for a personal blog.

:::warning
krowdev's Astro project lives at the repo root, so the root directory is left blank. Only set a root directory (and Cloudflare will `cd` into it before `npm run build`) if your Astro project sits in a subdirectory of a monorepo.
:::

## The Full Workflow

Here's what a typical content workflow looks like:

```
1. Write markdown in content/kb/
2. npm run dev → preview at localhost:4321
3. Happy with it? → git add + git commit
4. git push → Cloudflare auto-deploys
5. Site live at krowdev.pages.dev in ~30 seconds
```

:::analogy
This is like a LaTeX + Makefile + CI/CD pipeline:

```
Edit .tex → make preview → looks good → git push → CI runs pdflatex → PDF published
```

Same flow, different tools.
:::

## What You've Learned

Over 9 lessons, you've covered the full Astro architecture:

| Lesson | Concept | One-Liner |
|---|---|---|
| 01 | Mental Model | Astro is a compiler, not a server |
| 02 | File Routing | `src/pages/` directory = URL structure |
| 03 | .astro Files | Code fence (build time) + template (HTML output) |
| 04 | Components | Reusable pieces with props and slots |
| 05 | Layouts | Template inheritance via nested `<slot />` |
| 06 | Content Collections | Typed, validated markdown with query API |
| 07 | Styling | Scoped CSS + global tokens + Catppuccin theming |
| 08 | Markdown & Code | Shiki highlighting, MDX for components in content |
| 09 | Build & Deploy | `dist/` is the artifact, Cloudflare serves it |

You now understand every file in krowdev. The codebase has no mysteries.

**Final Challenge: Add a real article end-to-end**

Do the full workflow:

1. **Create** a new kb entry: `content/kb/first-article.md`
2. **Write** valid frontmatter (title, description, kind: guide, tags, maturity, origin, confidence)
3. **Add** some content with a code block, a table, and a heading
4. **Preview** with `npm run dev` — check sidebar, ToC, syntax highlighting, dark/light mode
5. **Build** with `npm run build` — verify it compiles and Pagefind indexes it
6. **Check** the output: `ls dist/guide/first-article/`

If all that works, you've completed the course. You can now write and publish content to krowdev independently.

---
Previous: [Markdown & Code Blocks](/guide/astro-markdown-and-code/)

## Sources

- Astro Docs, [Build configuration](https://docs.astro.build/en/reference/configuration-reference/#build-options)
- Astro Docs, [Server-side rendering](https://docs.astro.build/en/guides/on-demand-rendering/)
- Cloudflare Pages, [Astro deployment](https://developers.cloudflare.com/pages/framework-guides/deploy-an-astro-site/)
- Pagefind, [Documentation](https://pagefind.app/)