The official theme youlog integrates Algolia full-text search. See the youlog demo site for the result.
Recommended workflow: configure config.algolia in everkm.yaml and set push_on_export: true → everkm-publish serve --export (automatic reset → push after successful export) → preview/deploy the static site.
When you need separate control over push timing, or when auto-push is disabled in CI, use everkm-publish algolia (reads everkm.yaml; does not require push_on_export: true; no need to repeat index name and other params).
1. Prepare Algolia
Register on Algolia, create an index, and obtain:
- Application ID
- Admin API Key (for pushing the index; do not commit to the repo)
- Search-Only API Key (for front-end search; can be written to
everkm.yaml)
2. Configure everkm.yaml
Under config in __everkm/everkm.yaml, configure algolia (recommended):
config:
algolia:
push_on_export: true
app_id: YOUR_APP_ID
api_key: YOUR_SEARCH_ONLY_API_KEY # front-end; safe to expose
admin_key: ~ # push key; leave empty to read ALGOLIA_ADMIN_KEY env
index_name: my-index
site: my-site-id # site ID; distinguishes sites sharing one index
channel: main # channel ID; distinguishes channels within one site
url_base: https://your-domain.com/ # absolute page URLs after export push
body_selector: "#article-main" # body CSS selector; default .markdown-body
languages: # written to Algolia indexLanguages (ISO 639-1)
- zh
- en
| Field | Description |
|---|---|
push_on_export | When true, auto-push after export completes; false or omitted skips push |
app_id | Application ID |
api_key | Search-Only API Key, exposed to templates via __config for front-end search |
admin_key | Admin API Key; can be omitted and provided via ALGOLIA_ADMIN_KEY env var |
index_name | Index name; multi-language sites can use translation objects (see Internationalization (i18n)) |
site | Site ID: distinguishes data from different sites when multiple sites share one Algolia index |
channel | Channel ID: distinguishes data from different channels when one site exports and pushes channels independently |
url_base | Must use https://; trailing / recommended |
body_selector | CSS selector to extract body from exported HTML; must match theme DOM |
languages | Algolia indexLanguages / queryLanguages; must be ISO 639-1 (e.g., zh, en). Differs from site i18n codes like zh_CN, but zh_CN is automatically converted to zh on push |
site and channel
These are independent filter dimensions and are not bound to each other:
| Scenario | Recommended config |
|---|---|
| Multiple sites share one index | Configure a distinct site for each site |
| Same site, channels maintained separately | Configure the corresponding channel for each push (single-channel sites can use a fixed value like main) |
| Front-end full-text search | Usually filter by site only to search all channels of that site |
Rebuild index (reset) | Clears old data only for whichever of site and/or channel is configured; clears the entire index only when neither is configured |
When multiple sites share one index, specify at least site on reset to avoid clearing by channel alone and accidentally affecting same-named channels on other sites.
Compatibility: when algolia is not configured, the legacy field algolia_search (youlog old name) is still read with the same behavior.
After saving, restart preview; the top bar search box requires the theme to have built its search plugin assets.
3. Export and Auto-push
export ALGOLIA_ADMIN_KEY="Your Admin API Key" # required when admin_key is not set
everkm-publish serve --export
When export succeeds and config.algolia.push_on_export: true with valid credentials, reset → push runs automatically on dist/. Push failure does not fail export—check logs.
For local dev without push, set push_on_export: false or remove the algolia config.
When a single page push fails (e.g., network timeout), the failure is logged to __everkm/cache/algolia-push-failed.json (page URL and HTML path under dist). Run:
everkm-publish algolia ./my-site retry-failed
Retries cached pages one by one; successes are removed from the file; when all succeed the cache file is deleted; failures update error info.
4. Manual Push (everkm-publish algolia)
Index push is built into everkm-publish algolia, reading config.algolia from the site's everkm.yaml—no separate tool install or repeated --index-name params required.
export ALGOLIA_ADMIN_KEY="Your Admin API Key" # required when admin_key is not set
everkm-publish algolia ./my-site reset
everkm-publish algolia ./my-site push
everkm-publish algolia ./my-site retry-failed
| Subcommand | Description |
|---|---|
reset | Clear old docs by configured site and/or channel (add filters when set; clear entire index when neither is set), and write index settings |
push | Push from dist/ only (does not reset) |
retry-failed | Retry pages in algolia-push-failed.json; deletes cache when all succeed |
reset and push are independent; a full manual push requires reset then push (same as export auto-push reset → push).
Optional: --lang, --dist-dir, --config (same as serve).
For youlog multi-site scenarios: each site should configure a distinct config.algolia.site.
More theme-side fields: theme-youlog.
About ekmp-algolia
A standalone ekmp-algolia npm CLI was provided earlier; that tool is no longer maintained, and push logic has been merged into everkm-publish algolia. New sites should use the commands above; existing CI still calling ekmp-algolia should migrate to everkm-publish algolia.
5. CI Example
Inject secrets via CI environment variables; do not write them to the repo. Choose Option A or B below (do not use Option B when push_on_export: true, or you will push twice):
export ALGOLIA_ADMIN_KEY="$ALGOLIA_ADMIN_KEY"
# Option A: push_on_export: true + complete index params in everkm.yaml → auto reset → push after export
everkm-publish serve --export
# Option B: when push_on_export is false or omitted, manual two-step after export (same as §4)
everkm-publish serve --export
everkm-publish algolia ./my-site reset
everkm-publish algolia ./my-site push