Quick Start

This guide walks you through your first preview: install the tool -> initialize a site -> write a homepage -> view it in the browser.

It is recommended to read Concepts and Architecture first to understand the relationships between workspaces, themes, and page templates. For theme development, see Theme Development.

1. Installation

Install the everkm-publish CLI using any of the methods below.

Linux / macOS (curl)

curl -fsSL https://ekmp-assets.everkm.com/install.sh | bash

Installs to ~/.local/bin by default; make sure that directory is on your PATH.

macOS / Linux (Homebrew)

brew tap everkm/tap
brew trust everkm/tap
brew install everkm-publish

If you previously used an older tap, run brew untap everkm/tap && brew tap everkm/tap first.

Windows (PowerShell)

irm https://ekmp-assets.everkm.com/install.ps1 | iex

Installs to %USERPROFILE%\.local\bin by default; make sure that directory is on your PATH.

npm (commonly used for theme development)

npm i -g everkm-publish

Manual Download

Download the CLI tool and place everkm-publish in your PATH.

2. Create a Workspace

mkdir my-site
everkm-publish init my-site

• Installs the youlog theme by default (__everkm/theme/youlog/); remote installation syntax is everkm/youlog@version
• After init, you can run everkm-publish serve directly without specifying --theme (matches the default)
• Use --theme to specify a different theme (remote name like everkm/youlog)
• Creates __everkm/ in the site root (containing everkm.yaml and extend/ structure)

init accepts the site root directory path. Please mkdir first, then init <directory>.

3. Write the Homepage

cd my-site

Create HOME.md (see Article Metadata for Front Matter details):

---
title: Welcome
slug: index
created_at: 2026-06-19T10:00:00+08:00
---

This is my first everkm-publish site.

Optional: Edit __everkm/everkm.yaml to change the site name, etc. See Site Configuration.

4. Local Preview

cd my-site
everkm-publish serve

Open http://localhost:9081 in your browser.

• Edit the Markdown and refresh to see changes
• Debug endpoint: http://localhost:9081/__everkm/ (page list, status API)
• Switch language during preview: ?_lang=zh_CN or Cookie __lang=zh_CN, see Internationalization (i18n)

5. Export Static Site

everkm-publish serve --export

Export, verification, and deployment details at Export and Publish.

Next Steps

What you want to do	Read
Configure site name and directory rules	Site Configuration, Directory Configuration
Write a documentation site with chapter navigation	Navigation and Table of Contents, Links and Inner Links, Everkm Markdown Format
Multilingual	Internationalization (i18n)
Embed cards and search	Display Cards (dcard), Embedded Search
Develop or customize a theme	Theme Development
Troubleshooting	FAQ

Directory Structure

.
├── __everkm
│     ├── cache
│     │     └── everkm-publish.db
│     ├── everkm.yaml
│     ├── extend
│     │     ├── templates   # Site-level template overrides
│     │     ├── assets      # Site-level static assets (take precedence over theme in preview)
│     │     ├── dcard       # Site-level dCard cards
│     │     └── pages       # Override HTML at the same path after export
│     ├── i18n              # Project language packs (*.i18n.yaml)
│     └── theme
│         └── youlog
│             ├── assets-manifest.json
│             ├── everkm-theme.yaml
│             └── templates
├── HOME.md                 # Content example
└── <other Markdown and directories>

• __everkm/everkm.yaml: Site configuration
• __everkm/cache: Index cache, auto-managed
• __everkm/extend/: Site extensions (unified entry point since v0.17.2)
• __everkm/theme/: Installed themes, one subdirectory per theme
• Content files: anywhere in the workspace; directories or files starting with _ are ignored in some queries

Migration (v0.17.2): The old paths __public, __assets, __dcard, __everkm/__theme are deprecated. Please migrate to the corresponding subdirectories under extend/. See Changelog.

Installing and Switching Themes

# Remote install (recommended)
everkm-publish theme install everkm/youlog@0.5.6

# Force overwrite
everkm-publish theme install everkm/youlog --force

# Local zip
everkm-publish theme install /path/to/youlog.zip

For theme development and packaging, see Theme Development.