Site Configuration

Site-level configuration is written in __everkm/everkm.yaml. During rendering, it is merged with config and folders from the theme's everkm-theme.yaml, with site configuration taking precedence over theme defaults.

Templates access it through the global variable __config; directory-level rules are defined in the folders field.

Minimal Example

config:
  timezone: Asia/Shanghai
  default_lang: zh_CN
  site:
    name: My Site
    description: A brief site description
    logo: ~/assets/logos/logo.svg

default_template: post.html

folders:
  "/":
    hide_in_url: true
  "/blog/":
    template: list.html
    url_id_suffix: false
  "/docs/":
    template: book.html
    query:
      nav_file: /docs/_nav.md
    breadcrumbs:
      - title: "@i18n:nav.docs"
        url: /docs/

Common `config` Fields

Field	Description
`config.timezone`	Timezone, defaults to `Asia/Chongqing`
`config.default_lang`	Default language, affects `@i18n:` and `t()` fallback, defaults to `en_US`
`config.site`	Site name, description, logo, etc. Specific fields depend on the theme
`config.code_highlight`	Object; when `server: true`, the publish engine highlights fenced code blocks on the server (theme includes `code-highlight.css`); omit or `server: false` to keep browser Prism
`config.math_render`	Object; when `server: true`, the publish engine renders body math as inline SVG (Typst + mitex; theme may include `math-svg.html` style fragment); omit or `server: false` to keep browser KaTeX

Strings under config can use @i18n:<key> to reference language packs. See Internationalization (i18n).

Theme-specific configuration (such as youlog Algolia search config.algolia, navigation header_nav) is placed under config. See the theme-youlog README for field descriptions. Algolia push and front-end search setup: Embedded Search.

`default_template`

The default page template name for the entire site. Used when a directory does not specify a template in folders.

Can be overridden by template in sibling or child entries within folders.

Resolution priority (high to low):

Article front matter template
  → merged folders.template for that directory
  → everkm.yaml#default_template
  → everkm-theme.yaml#default_template

Themes can preset defaults in everkm-theme.yaml; site everkm.yaml overrides the theme for the same key.

`folders` Directory Rules

In everkm.yaml, declare rendering rules for directories by URL path prefix; themes can preset defaults in everkm-theme.yaml#folders, with site overriding by the same path key. Child directories merge and inherit from ancestors, with deeper entries overriding shallower ones.

Common fields:

Field	Description
`url_slug`	Custom URL path segment; when explicitly set, enters descendant URL prefixes even without a directory `index.md`
`template`	The theme template name used for pages in this directory
`query`	Key-value pairs merged into the template global variable `__qs`
`breadcrumbs`	Breadcrumbs; `title` supports `@i18n:<key>`
`hide_in_url`	When `true`, this directory segment is omitted from the URL
`url_id_suffix`	Defaults to `true`; when `false`, the URL is `{slug}.html` instead of `{slug}-{id}.html`
`hash_scatter`	Whether to scatter article hashes into subdirectories during export

Complete fields, merge rules, and URL generation at Directory Configuration.

folders:
  "/blog/":
    template: list
    url_id_suffix: false   # /blog/my-post.html instead of /blog/my-post-123.html

Relationship with Theme Configuration

The two YAML files serve different roles: the theme package presets out-of-the-box defaults; the site only writes deltas—not every field should be duplicated on both sides.

File	Purpose
`__everkm/theme/<name>/everkm-theme.yaml`	Theme metadata and theme-level default `config` / `folders` / `default_template`
`__everkm/everkm.yaml`	Site operations config; higher priority on mergeable fields

Theme metadata fields at Theme Development.

Config Scope

Field	`everkm-theme.yaml`	`everkm.yaml`	Notes
`name` / `version` / `author` / `repository` / `demo` / `screenshots`	✅	—	Theme package metadata; theme-side only
`config`	✅ preset	✅ override	Merged for `__config` / `config()`
`folders`	✅ preset	✅ override	Field-level extend by path key; see Directory Configuration
`default_template`	✅ preset	✅ override	Fallback chain above
`inject_js` / `inject_css`	—	✅	Site-level HTML injection; project-side only
`redirects`	—	✅	Extra redirects for nginx / Vercel export; project-side only

inject_*, redirects, and theme meta intentionally live in different scopes: theme JS/CSS belongs in templates or assets/; redirects tie to deployment domains and are maintained by site operators; name / version describe the theme package itself, not site config.

Merge Rules for Mergeable Fields

config: theme config as base, site config deep-merged on top (json_patch::merge).

Objects: recursive merge; site overrides theme for same keys
Arrays: whole-array replace, not append (site config.site.nav replaces the theme array under the same key)
@i18n: etc. are materialized before render; __config in templates is the final value for the current language

folders: build effective_folders first (theme base, site extend by path), then merge along the article directory ancestor chain. See Directory Configuration.

default_template: not merged; first non-empty value in the fallback chain (site before theme).

Site-only Fields

The following fields are written only in __everkm/everkm.yaml; theme everkm-theme.yaml does not and need not support them.

inject_js / inject_css: inject extra resources before </head> / </body> in rendered HTML. Per item:

Field	Description
`url`	Resource path; relative paths get site `base_prefix`
`match_path`	Optional glob; omit or empty to match all pages

inject_css:
  - url: ~/assets/extra.css
inject_js:
  - url: https://cdn.example.com/analytics.js
    match_path: "/blog/**"

redirects: extra redirect rules when exporting with --with-nginx-map / --with-vercel (merged with maps from index aliases and permalink).

redirects:
  - source: /old-path
    destination: /new-path
    permanent: true