Concepts and Architecture

everkm-publish is a static site generator and local preview CLI tool: you write Markdown in a workspace, the tool renders it into HTML using a theme, and you can preview or export it as deployable static files.

A Publishing Cycle

Markdown content  +  Theme (appearance and layout)  →  Preview / Export HTML  →  Deploy to server or CDN

1. Write content: Place .md files in the workspace root (or a language subdirectory)
2. Choose a theme: Determines page layout, navigation, and styling
3. Preview: Run everkm-publish serve to start a local server and see changes live
4. Export: Run everkm-publish serve --export to generate a static site directory
5. Go live: Deploy the exported directory to Nginx, object storage, Vercel, etc. (see Export and Publish)

Core Concepts

Concept	What is it	Where is it
Workspace (work-dir)	Site root directory containing content and __everkm/	Your created my-site/
Content	Markdown articles, images, etc.	Workspace root and subdirectories
Theme	Complete appearance package: templates, static assets, optional frontend scripts	__everkm/theme/<name>/
Page Template	Rendering method for a specific page type (e.g., book, list)	Inside theme templates/, specified by folders.template
everkm.yaml	Site-level configuration: site info, directory rules	__everkm/everkm.yaml
extend/	Site-level extensions: override templates, assets, dCard	__everkm/extend/

Theme != Page Template. A theme is a complete skin package; the template field in folders specifies which page template within the theme is used to render a given directory.

Workspace Directory Overview

my-site/                          <- work-dir (workspace root)
├── HOME.md                       <- Content: homepage Markdown
├── blog/
│   └── hello.md
├── __everkm/
│   ├── everkm.yaml               <- Site configuration
│   ├── cache/                    <- Index cache (auto-managed)
│   ├── extend/                   <- Site extensions
│   ├── i18n/                     <- Project language packs
│   └── theme/
│       └── youlog/               <- Installed theme
└── zh_CN/                        <- Multilingual content directory (optional)
    └── blog/

Full details at Quick Start.

Two Learning Paths

Site operators (writing content, configuring the site, exporting and deploying):

1. Concepts and Architecture (this page) -> Quick Start -> Article Metadata -> Site Configuration
2. As needed: Navigation and Table of Contents, Links and Inner Links, Everkm Markdown Format, Internationalization (i18n), Display Cards (dcard), Export and Publish, CLI Quick Reference, FAQ

Theme developers (developing or customizing appearance):

1. First understand theme vs template in this page
2. Theme Development -- Theme structure, Tera / JsRender, packaging and installation
3. Introduction -- Template syntax (Tera); built-in functions at Built-in Functions

CLI

The role of each subcommand in the publishing workflow is described at CLI Quick Reference; for complete parameters, use everkm-publish <subcommand> --help.