本文带你完成第一次预览：安装工具 → 初始化站点 → 写首页 → 浏览器查看。
建议先读 概念与架构 了解工作区、主题与页面模板的关系。主题开发见 主题开发。
1. 安装
任选以下方式安装命令行工具 everkm-publish。
Linux / macOS（curl）
curl -fsSL https://ekmp-assets.everkm.com/install.sh | bash
默认安装到 ~/.local/bin，请确保该目录在 PATH 中。
macOS / Linux（Homebrew）
brew tap everkm/tap
brew trust everkm/tap
brew install everkm-publish
若曾安装过旧版 tap，请先执行 brew untap everkm/tap && brew tap everkm/tap。
升级（已安装时勿再执行 install，应使用 upgrade）：
brew upgrade everkm-publish
若仍显示旧版，手动刷新 tap 后再升级：
git -C "$(brew --repo everkm/tap)" pull --ff-only origin main
brew upgrade everkm-publish
Windows（PowerShell）
irm https://ekmp-assets.everkm.com/install.ps1 | iex
默认安装到 %USERPROFILE%\.local\bin，请确保该目录在 PATH 中。
npm（主题开发常用）
npm i -g everkm-publish
手动下载
下载命令行工具，将 everkm-publish 放入 PATH。
2. 创建工作区
mkdir my-site
everkm-publish init my-site
- 默认安装主题
paper（__everkm/theme/paper/）；远程安装写法为everkm/paper@版本 init后可直接everkm-publish serve，无需再写--theme（与默认一致）- 可用
--theme指定其它主题（远程名如everkm/youlog） - 在站点根目录创建
__everkm/（含everkm.yaml与extend/结构）
init 接受站点根目录路径。请先 mkdir 再 init <目录>。
3. 写首页
cd my-site
创建 HOME.md（Front Matter 详见 文章元数据）：
---
title: 欢迎
slug: index
created_at: 2026-06-19T10:00:00+08:00
---
这是我的第一个 everkm-publish 站点。
可选：编辑 __everkm/everkm.yaml 修改站点名称等，见 站点配置。
4. 本地预览
cd my-site
everkm-publish serve
浏览器打开 http://localhost:9081{target=_blank}。
- 修改 Markdown 后刷新即可看到变化
- 调试入口：http://localhost:9081/__everkm/{target=_blank}（页面列表、状态接口）
- 预览时切换语言：
?_lang=zh_CN或 Cookie__lang=zh_CN，见 多语言
5. 导出静态站点
everkm-publish serve --export
导出、检查与部署详见 导出与发布。
下一步
| 你想做 | 阅读 |
|---|---|
| 配置站点名称、目录规则 | 站点配置、目录配置 |
| 写文档站与章节目录 | 导航与目录、链接与内链、毓知Markdown格式 |
| 多语言 | 多语言 |
| 嵌入卡片、搜索 | 展示卡片 (dcard)、嵌入式搜索 |
| 开发或定制主题 | 主题开发 |
| 报错与排错 | 常见问题 |
目录结构
.
├── __everkm
│ ├── cache
│ │ └── everkm-publish.db
│ ├── everkm.yaml
│ ├── extend
│ │ ├── templates # 站点级模板覆盖
│ │ ├── assets # 站点级静态资源（预览优先于主题）
│ │ ├── dcard # 站点级 dCard 卡片
│ │ └── pages # 导出后覆盖同路径 HTML
│ ├── i18n # 项目语言包（*.i18n.yaml）
│ └── theme
│ └── paper
│ ├── assets-manifest.json
│ ├── everkm-theme.yaml
│ └── templates
├── HOME.md # 内容示例
└── <其他 Markdown 与目录>
__everkm/everkm.yaml：站点配置__everkm/cache：索引缓存，自动管理__everkm/extend/：站点扩展（v0.17.2 统一入口）__everkm/theme/：已安装的主题，每个主题一个子目录- 内容文件：工作区任意位置；
_开头的目录或文件在部分查询中会被忽略
迁移（v0.17.2）：旧路径 __public、__assets、__dcard、__everkm/__theme 已废弃，请迁至 extend/ 对应子目录。详见 更新日志。
安装与切换主题
# 远程安装（推荐写法）
everkm-publish theme install everkm/youlog@0.5.6
# 强制覆盖
everkm-publish theme install everkm/youlog --force
# 本地 zip
everkm-publish theme install /path/to/youlog.zip
开发、打包主题见 主题开发。