FAQ

Preview Won't Open or Shows 404

Verify the workspace path. The --work-dir for serve should point to the site root containing __everkm/ and Markdown content:

cd my-site          # site root
everkm-publish serve

If developing a theme in a subdirectory (e.g., theme-youlog's __everkm/), specify explicitly:

everkm-publish serve --work-dir ../ --theme youlog --theme-dev

Defaults to listening on http://localhost:9081. Health check: GET /__everkm/state/ping should return PONG.

Blank Homepage or Broken Styling

1. Confirm the theme is installed: __everkm/theme/youlog/ exists, or run everkm-publish theme install everkm/youlog
2. Homepage content is required in the root directory: e.g., HOME.md with slug: index in its Front Matter (see Article Metadata)
3. After modifying theme source code, add --theme-dev in development mode and restart or wait for reload

Theme Not Found

everkm-publish theme install everkm/youlog@<version>
everkm-publish serve --theme youlog

The --theme name corresponds to the directory name under __everkm/theme/<name>/, not the author prefix in everkm/youlog. For remote installation syntax, see Quick Start.

During local development, you can specify a theme directory to skip the installed package:

everkm-publish serve --theme-dir ./path/to/theme/youlog

lint Reports Internal Link Ambiguity

When a [[...]] in the body matches multiple pages, errors are reported by line number. How to fix:

• Use a more specific path, e.g., [[docs/guide/quick-start]] instead of [[quick-start]]
• Check for duplicate slug values or files with the same name
• Run everkm-publish lint ./my-site --auto-fix to fix items that can be handled automatically

Internal link rules at Links and Inner Links.

lint Reports Front Matter Issues

Common items:

Error	Fix
Missing created_at	Add an RFC3339 timestamp, or use --auto-fix
date is deprecated	Change to created_at
slug conflict	Modify the duplicate slug or let lint remove it (auto-fix)
Missing id	--auto-fix can fill it in automatically

See Article Metadata.

Missing Images or Attachments After Export

Export only includes resources referenced in the body. Files not referenced in Markdown will not be included in dist/.

To include additional files:

• Place them in __everkm/extend/assets/; they will be copied to the site's assets/ during export
• Or reference them in the body using standard links / media() / dCard to include them in the crawl graph

See Export and Publish.

Multilingual Content Not Displaying

Multilingual sites require placing corresponding Markdown files in language subdirectories:

my-site/zh_CN/blog/hello.md
my-site/en_US/blog/hello.md

Specify the language during preview:

everkm-publish serve --lang zh_CN

Or use ?_lang=zh_CN in the browser. When --lang is not specified, the content root is the workspace root (single-language mode). See Internationalization (i18n).

Config Changed but Page Didn't Update

What was changed	Restart required?
Markdown body	No, just refresh
__everkm/i18n/ language packs	No
extend/ templates or assets	No (triggers reload)
Some everkm.yaml items	Depends on the item; folders changes usually require restarting serve
Theme package (not --theme-dev)	Restart required

For theme development, add --theme-dev to watch for theme directory changes.

Legacy Directory Migration (v0.17.2)

The following paths are deprecated. Please migrate to __everkm/extend/:

Old Path	New Path
__public	extend/pages
__assets	extend/assets
__dcard	extend/dcard
__everkm/__theme	__everkm/theme

See Quick Start and Changelog.

How to Deploy After Export

The exported directory is the static site root. Upload it to Nginx, object storage, Vercel, etc. Recommended workflow: lint -> serve --export -> web ./dist for local verification -> upload. See Export and Publish.

Search Box Not Appearing

1. The theme must support search (e.g., youlog + plugin-in-search build artifact)
2. Configure config.algolia_search in everkm.yaml (not embed_search)
3. You must first push the index as described in Embedded Search

See Embedded Search.

Theme Development vs. Site Usage Confusion

Role	Focus
Site operator	Write content in my-site/, everkm.yaml, Quick Start
Theme developer	Theme source code, everkm-render.js, packaging zip, see Theme Development

Theme is a complete appearance package; Page Template is a specific page rendering method within a theme (e.g., book, list). See Concepts and Architecture.