開始使用

本指南從安裝到發佈第一篇文章，帶你完成第一個 EmDash 網站。

必要條件

• Node.js v22.12.0 或更新版本（不支援奇數版本）
• npm、pnpm 或 yarn
• 程式碼編輯器（建議 VS Code）

建立新專案

npm create emdash@latest

pnpm create emdash@latest

yarn create emdash

依照提示命名專案並完成偏好設定。

啟動開發伺服器

完成設定精靈

第一次開啟管理後台時，EmDash 的設定精靈會引導你完成初始設定:

通行金鑰註冊完成後，你會登入並前往管理儀表板。

第一篇文章

專案結構

EmDash 專案在標準 Astro 結構上略有擴充:

my-emdash-site/
├── astro.config.mjs      # Astro + EmDash 設定
├── src/
│   ├── live.config.ts    # Live Collections 設定
│   ├── pages/
│   │   ├── index.astro   # 首頁
│   │   └── posts/
│   │       └── [...slug].astro  # 動態文章頁
│   ├── layouts/
│   │   └── Base.astro    # 基礎版面
│   └── components/       # 你的 Astro 元件
├── .emdash/
│   ├── seed.json         # 範本種子檔
│   └── types.ts          # 產生的 TypeScript 型別
└── package.json

設定檔

astro.config.mjs

將 EmDash 設定為 Astro 整合:

import { defineConfig } from "astro/config";
import emdash, { local } from "emdash/astro";
import { sqlite } from "emdash/db";

export default defineConfig({
	integrations: [
		emdash({
			database: sqlite({ url: "file:./data.db" }),
			storage: local({
				directory: "./uploads",
				baseUrl: "/_emdash/api/media/file",
			}),
		}),
	],
});

src/live.config.ts

將 EmDash 連接到 Astro 的內容系統:

import { defineLiveCollection } from "astro:content";
import { emdashLoader } from "emdash/runtime";

export const collections = {
	_emdash: defineLiveCollection({ loader: emdashLoader() }),
};

環境變數

正式環境部署需要設定:

# Required for authentication
EMDASH_AUTH_SECRET=your-secret-here

# Optional: for content preview
EMDASH_PREVIEW_SECRET=your-preview-secret

產生安全的驗證密鑰:

npx emdash auth secret

在頁面中查詢內容

在 Astro 頁面中使用 EmDash 的查詢函式。它們遵循 Astro 的 live collections 模式：集合回傳 { entries, error }，單筆回傳 { entry, error }:

---
import { getEmDashCollection } from "emdash";
import Base from "../layouts/Base.astro";

const { entries: posts } = await getEmDashCollection("posts");
---

<Base title="Home">
  <h1>Latest Posts</h1>
  <ul>
    {posts.map((post) => (
      <li>
        <a href={`/posts/${post.slug}`}>{post.data.title}</a>
      </li>
    ))}
  </ul>
</Base>

查詢單筆內容:

---
import { getEmDashEntry } from "emdash";

const { slug } = Astro.params;
const { entry: post } = await getEmDashEntry("posts", slug);

if (!post) {
  return Astro.redirect("/404");
}
---

<h1>{post.data.title}</h1>

產生 TypeScript 型別

為取得完整型別安全，可依資料庫結構描述產生型別:

npx emdash types

這會建立 .emdash/types.ts，內含所有集合的介面。編輯器會自動完成欄位名稱並找出型別錯誤。

下一步

你現在已有一個可運作的 EmDash 網站。可繼續閱讀:

• 核心概念 — 了解 EmDash 的內部運作
• 使用內容 — 查詢與呈現內容
• 媒體庫 — 上傳與管理圖片與檔案
• 建立部落格 — 打造含分類與標籤的完整部落格
• 部署到 Cloudflare — 將網站上線到正式環境