diff --git a/docs/getting-started/index.md b/docs/getting-started/index.md
index d1ed739..4a55a19 100644
--- a/docs/getting-started/index.md
+++ b/docs/getting-started/index.md
@@ -21,5 +21,6 @@ Follow these in order:
 
 ## Upgrading & Migrating
 
+- **[[whats-new|What's New in Quartz 5]]** — Overview of new features and changes
 - **[[upgrading|Upgrading Quartz]]** — Keep your Quartz installation up to date
 - **[[migrating|Migrating to Quartz 5]]** — Migrate from Quartz 4 or Quartz 3
diff --git a/docs/getting-started/whats-new.md b/docs/getting-started/whats-new.md
new file mode 100644
index 0000000..d759b3d
--- /dev/null
+++ b/docs/getting-started/whats-new.md
@@ -0,0 +1,179 @@
+---
+title: "What's New in Quartz 5"
+aliases:
+  - "changelog"
+  - "v5"
+---
+
+Quartz 5 is a ground-up rearchitecture of Quartz focused on extensibility, performance, and Obsidian compatibility. If you're coming from v4, see [[migrating|Migrating to Quartz 5]] for the upgrade path.
+
+## Plugin Ecosystem
+
+The biggest change in v5 is the move to a **community plugin ecosystem**. Plugins are now standalone packages maintained in the [quartz-community](https://github.com/quartz-community) GitHub organization and installed via git:
+
+```bash
+npx quartz plugin add github:quartz-community/explorer
+```
+
+This means:
+
+- **Independent versioning**: Plugins can be updated without upgrading Quartz itself
+- **Community contributions**: Anyone can publish a Quartz plugin
+- **Smaller core**: Quartz core is leaner; features live in plugins
+- **Plugin registry**: Discover plugins via `npx quartz tui` or the [plugin registry](https://github.com/quartz-community/registry)
+
+Over 40 official plugins ship with Quartz, covering everything from search and graph view to encrypted pages and canvas rendering.
+
+## YAML Configuration
+
+Configuration moved from TypeScript (`quartz.config.ts`) to **YAML** (`quartz.config.yaml`):
+
+```yaml title="quartz.config.yaml"
+configuration:
+  pageTitle: My Digital Garden
+  enableSPA: true
+  enablePopovers: true
+  locale: en-US
+  baseUrl: mysite.github.io
+  theme:
+    typography:
+      header: Schibsted Grotesk
+      body: Source Sans Pro
+      code: IBM Plex Mono
+plugins:
+  - source: github:quartz-community/obsidian-flavored-markdown
+    enabled: true
+    order: 30
+  - source: github:quartz-community/explorer
+    enabled: true
+    layout:
+      position: left
+      priority: 50
+```
+
+Benefits:
+
+- **No TypeScript knowledge required** for basic customization
+- **JSON Schema validation** — editors with YAML support show errors inline
+- **Layout defined per-plugin** — each plugin declares its own position and priority
+- **Templates** — `npx quartz create` offers preconfigured templates (default, obsidian, ttrpg, blog)
+
+For advanced options that need JavaScript (callbacks, custom components), the `quartz.ts` override system provides full programmatic control.
+
+## Improved Obsidian Compatibility
+
+Quartz 5 aims for full compatibility with Obsidian's core features:
+
+- **Wikilinks** — all variations including aliases, headings, block references, and pipe escaping in tables
+- **Callouts** — all built-in types, collapsible variants, and nested callouts
+- **Highlights** — `==highlighted text==` syntax
+- **Comments** — `%%hidden comments%%` (inline and block)
+- **Tags** — `#tag` and `#nested/tag` with tag pages
+- **Custom task characters** — `[?]`, `[!]`, `[>]`, etc. preserved as `data-task` attributes
+- **Mermaid diagrams** — rendered with expand button
+- **YouTube and Tweet embeds** — via image syntax
+- **Block references** — `^block-id` with broad character support
+- **Video/audio embeds** — full format support (mp4, webm, ogv, mov, mkv, avi, flac, aac, etc.)
+- **Canvas files** — rendered as interactive, pannable pages via the canvas-page plugin
+- **Obsidian URI links** — marked with CSS class for custom styling
+- **Footnotes** — via the GitHub Flavored Markdown plugin
+
+See [[Obsidian compatibility]] for the full list.
+
+## Page Type System
+
+Quartz 5 introduces **page types** — plugins that define how different kinds of pages are rendered:
+
+- **Content pages** — regular markdown notes
+- **Folder pages** — directory listing pages
+- **Tag pages** — pages listing notes with a given tag
+- **Canvas pages** — interactive JSON Canvas renderings
+- **Bases pages** — database-style views of your content
+
+Each page type can use a different [[layout#Page Frames|page frame]] for fundamentally different HTML structures (three-column, full-width, minimal, etc.).
+
+## Layout System
+
+The layout system is now declarative. Plugins declare their position (`left`, `right`, `beforeBody`, `afterBody`) and priority in the config:
+
+```yaml
+plugins:
+  - source: github:quartz-community/explorer
+    layout:
+      position: left
+      priority: 50
+  - source: github:quartz-community/graph
+    layout:
+      position: right
+      priority: 10
+```
+
+Additional features:
+
+- **Groups** — combine components into flex rows/columns (e.g., toolbar with search + darkmode toggle)
+- **Conditional rendering** — show/hide components based on page properties (`condition: not-index`, `condition: has-tags`)
+- **Display modifiers** — `display: mobile-only` or `display: desktop-only`
+- **Per-page-type overrides** — different layouts for content, folder, tag, and 404 pages
+
+## Performance
+
+- **Parallel processing** — markdown parsing uses a worker pool across all CPU cores
+- **Incremental rebuilds** — watch mode only re-processes changed files
+- **Pre-built plugins** — community plugins ship compiled `dist/` directories, skipping build-from-source on install
+- **SPA routing** — client-side navigation with `micromorph` for instant page transitions
+- **CDN-cached fonts** — Google Fonts with aggressive caching, or fully self-hosted with `fontOrigin: local`
+
+## CLI Improvements
+
+The CLI is simpler and more helpful:
+
+| Command | Description |
+|---------|-------------|
+| `npx quartz create` | Interactive setup wizard with templates |
+| `npx quartz build --serve` | Build and serve with hot reload |
+| `npx quartz sync` | Commit and push to GitHub |
+| `npx quartz upgrade` | Pull latest Quartz updates |
+| `npx quartz plugin install` | Install plugins from lockfile |
+| `npx quartz plugin add <source>` | Add a new plugin |
+| `npx quartz plugin list` | List installed plugins |
+| `npx quartz plugin prune` | Remove unused plugins |
+
+Other improvements:
+
+- **Node.js version check** — clear error message if running on Node < 22
+- **Port conflict handling** — helpful message when port is already in use
+- **Plugin lockfile** — `quartz.lock.json` pins plugin versions for reproducible builds
+- **Concurrency control** — `--concurrency` flag for memory-constrained environments
+
+## Internationalization
+
+Quartz 5 supports multiple locales out of the box. Set `locale: ja-JP` (or any supported locale) in your config to translate all UI strings — search placeholders, "table of contents", date formatting, and more.
+
+## New Plugins
+
+Plugins new to v5 (not available in v4):
+
+| Plugin | Description |
+|--------|-------------|
+| [[CanvasPage]] | Renders `.canvas` files as interactive pages |
+| [[BasesPage]] | Database-style views with filters, sorts, and grouping |
+| [[EncryptedPages]] | Password-protect individual pages |
+| [[NoteProperties]] | Display frontmatter properties on the page |
+| [[UnlistedPages]] | Hide pages from navigation while still publishing them |
+| [[StackedPages]] | Andy Matuschak-style stacked page navigation |
+| [[ReaderMode]] | Distraction-free reading toggle |
+| [[Spacer]] | Flexible spacer for layout adjustments |
+
+## For Plugin Developers
+
+If you built plugins for v4, the development model has changed significantly:
+
+- Plugins are **standalone npm packages** with their own `package.json`, `tsconfig.json`, and build system
+- The **factory function pattern** (inspired by Astro integrations) replaces class-based plugins
+- **`@quartz-community/types`** provides full type safety without depending on the Quartz core
+- **`@quartz-community/utils`** provides shared path, DOM, and language utilities
+- **`@quartz-community/runtime`** provides browser runtime utilities
+- Plugins can ship **components**, **frames**, **stylesheets**, and **client scripts**
+- A **plugin template** is available at [quartz-community/plugin-template](https://github.com/quartz-community/plugin-template)
+
+See [[making plugins]] for the full guide.
diff --git a/docs/index.md b/docs/index.md
index 45250da..f3e5952 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -9,8 +9,8 @@ Quartz is a fast, batteries-included static-site generator that transforms Markd
 Quartz requires **at least [Node](https://nodejs.org/) v22** and `npm` v10.9.2 to function correctly. Ensure you have these installed on your machine before continuing.
 
 ```shell
-# 1. Clone the Quartz repository (v5 branch)
-git clone -b v5 https://github.com/jackyzha0/quartz.git
+# 1. Clone the Quartz repository
+git clone https://github.com/jackyzha0/quartz.git
 cd quartz
 
 # 2. Install dependencies