内置函数 | Everkm Publish

range

返回指定规格的列表

参数：

start：可选。默认为0，开始数值
end：必选，结束数字，不包括该数字
step_by：可选，默认1，每次增长步长

now

返回当前时间，以日期字符串或者时间戳的格式。

参数：

timestamp：可选，默认false，是否返回时间戳
utc：可选，默认false，是否返回utc时间

random

获取一个随机数，范围区间 [start, end)

参数

start：可选，默认0。最小值
end：最大值，范围不包括该值。

env

返回指定名称的系统变量。

参数：

name: 变量名称。
default: 如果不存在，使用此默认值。

asset

输出静态资源引用。依赖模板路径下的assets-manifest.json，通常由webpack插件 webpack-assets-manifest 输出，插件配置如下：

new WebpackAssetsManifest({
    publicPath: true,
    entrypoints: true,
    output: 'assets-manifest.json',
}),

参数：

type：assets类型。有效值 js或css。
section：入口（entrypoint）名称。
cdn：可选。该资源优先使用的CDN前缀。注意仅当非绝对路径才会附加CDN前缀。

imgsrc

获取打包后的图片地址。数据来源于 img-manifest.json 文件，常用于 Webpack 打包资源后输出的 Manifest 文件。

{# 显式使用函数 #}
<img src="{{ imgsrc(file="a/b/logo.png") }}" />

{# 上面函数的语法糖，自动转换以"@"打头格式的地址。#}
<img src="@a/b/logo.png" />

参数：

file: 文件路径。

当存在以语言代码为文件名后缀文件时，将被优先采用。

例如, 当启动参数设置 --lang=en_US

img-manifest.json

{
  "assets/img/arrow-down.png": "assets/img/arrow-down.9685e4b1.png",
  "assets/img/arrow-down.en_US.png": "assets/img/arrow-down.9685e4b1.en_US.png"
}

模板

<img src="{{img_src(file='assets/img/arrow-down.png')}}" />

输出

<img src="assets/img/arrow-down.9685e4b1.en_US.png" />

t

多语言输出。

<div class="">{{ t(text="meta description", memo="hello world") }}</div>
<div class="">{{ t(text="memo/body2 ") }}</div>
<script>var msg = "hello {{ __T_my name__ }}";</script>

语法糖：T__label，多用于js字符串中，label为语言关键字。

text：语言内容。
memo：可选。内容注释。

data

数据源指定。支持json、yaml、toml格式，加载后自动(默认根据扩展名)转换为对象。数据源可以是本地模板目录中文件或者远程Url地址。

参数：

src：数据源地址
format：可选，通过扩展名推测。返回内容的解析格式。有效值为：json、yaml、toml、csv
bearer：可选, OAuth Token。
post：可选, 默认 false，是否为POST请求。
json_payload：可选, POST请求发送的JSON数据对象。
csv_delimiter：可选, CSV分隔符，默认为 ,。
cache_secs：可选, 缓存的时间，单位为秒。默认不缓存。

script

Javascript脚本扩展。脚本返回值可为普通数据类型或者json对象。示例如下：

{% set hi_js = `
function sayHello(name){
    return `hello ${name}`
}
sayHello(args.name)
` %}
<p>{{script(content=hi_js, name=file.name)}}</p>

参数：

content：脚本内容。
file：脚本文件名。脚本需放在模板目录 _everkm/_js/ 中。
其他参数键值对，转换为JS全局变量args的属性。

content, file 参数二选一。

base_url

输出导出页面的URL前缀，多用于导出后部署至二级目录。

post_meta

返回指定内容的元数据。

参数

id 或 path：二选一，定位内容。
path：内容 logical path 字符串；或用 [[...]] 内链语法（与正文内链、nav_* 的 from_file 规则一致，见链接与内链）。plain path 仍按 strict logical path 查找；整段 [[...]] 包裹时走 inner link（slug / 标题 / 绝对路径等）；可写 [[目标|显示名]]，仅 | 前参与定位。相对路径（[[./x]]、[[../x]]）须在当前文章页渲染上下文中调用（当前页有 post），否则报错；slug / 标题 / [[/abs/path.md]] 可在任意页面使用。

返回格式

键名	含义	类型	可选	说明
id	ID	字符串		常用于参数传递。
title	标题	字符串
dir	目录	字符串		两端有字符 `/`
path	文件路径	字符串
url_path	前端URL路径	字符串
slug	文件Slug	字符串		默认为标题URL编码
summary	摘要	字符串	✔️	Frontmatter 可选。缺省时由发布索引从正文截取纯文本（约 100 字，跳过标题与代码块）；显式空串表示不要摘要。自动摘要与正文渲染一致，会尊重业务侧内容块排除标签（默认含 `private`，对应 `{#private}`），被排除块不会进入摘要。
created_at	创建时间	整数（秒级时间戳）		旧版 `date` 仍可作为别名使用
updated_at	更新时间	整数（秒级时间戳）	✔️	别名 `updated`
draft	是否草稿	布尔值
tags	标签集	字符串数组		索引时已规范化后的值（空格等→`-`；多层 `/` 展开后以 `__` 连接，如 `tech/rust` → 同时含 `tech` 与 `tech__rust`）。写法见文章元数据。
weight	权重	整数	✔️
meta	元属性	对象	✔️	Markdown FrontMatter 中未提升为顶层字段的键（如自定义字段、旧版 `categories` 等）均保留在此，前端可通过 `post.meta.categories` 读取。

post_detail

内容详情

参数

id 或 path：二选一，定位内容（path 支持 [[...]] 内链语法，规则同 post_meta）。
allow_missing: 可选，默认 false。为 true 时：文章不存在返回空（post_detail/post_meta 为 null，has_post 为 false）；若 path 为 [[...]] 且内链无法解析，同样返回空而非报错。plain logical path 找不到时本就返回空，无需此参数。
lazy_img: 可选。图片延迟加载。
exclude_tags: 可选。内容块排除标签。多个 Tag 用空格隔开；默认含 private（对应 Markdown {#private} 块）。注意：当匹配 Tag 为标题时，该标题及下级标题、内容都将忽略。

返回格式

在内容元数据基础上，增加以下

键名	含义	类型	可选	说明
content_html	转换HTML后的详细内容	字符串

has_post

内容是否存在

参数

path: 内容路径（支持 [[...]] 内链语法，规则同 post_meta）。
allow_missing: 可选，语义同 post_detail。

posts

返回指定条件的文章列表，格式见post_meta。默认排序规则为：weight↓, updated_at↓, title↑, created_at↑。

参数

dir: 可选。按目录筛选。以 / 开头为绝对逻辑目录；否则相对当前页所在目录解析（需页面上下文），支持 ./、../、.（当前目录）；空字符串非法。解析结果必须仍在内容根之内，越界将报错。
tags: 可选。按标签筛选（多值 OR：命中任一即可）。值为规范化后的标签串（精确匹配）；多层请写 tech__rust，不要写原始的 tech/rust。
exclude_tags: 可选。按标签排除文章；默认含 private。
recursive: 可选，默认false。按目录筛选时是否递归所有子孙目录。
include_myself: 可选，默认false。是否把当前页面文章计入列表。为false时会在分页与total统计之前排除调用者（依赖页面上下文中的当前文章）。
include_dir_index: 可选，默认false。是否把目录默认页计入列表（slug=index / index.md / 同名页如 foo/foo.md）。为false时在分页与total统计之前排除；recursive 时子孙目录默认页一并排除。
order_by: 可选。排序字段。有效值：default、updated_at、created_at、title。
order_direction: 可选。排序方向。有效值：asc、desc。
offset / limit: 可选。分页偏移与每页条数。

环境变量

EVERKM_DRAFT: 当值为1时，返回包括草稿在内的所有内容，默认0。
EVERKM_PRIVATE: 预览下当值为 1 时，关闭系统默认的 private 排除（含 {#private} 内容块与带 private 标签的文章）；导出不受影响。

posts_tag_list

返回标签和其对应文件数量的列表。键为规范化后的标签串（与 post.tags / posts({ tags: ... }) 一致）；多层标签在父级与子级上分别计数。

参数

参数名	含义	类型	可选	说明
dir	目录	字符串	✔️	`/` 打头

{
    "<tag>": 1,
}

posts_directory_list

获取指定条件的目录集合。

参数

参数名	含义	类型	可选	说明
dir	目录	字符串	✔️	`/` 打头
max_depth	最大层级	正整数	✔️	`/` 为1级
prefix	限定前缀	字符串	✔️	以 `/` 打头

字符串数组。按字典顺序排列。

[
    "/blog/2013/",
    "/docs/",
]

media_remote

将远程图片、音频、视频资源本地化。

参数

url: 远程地址

对象类型。

键名	含义	类型	可选	说明
url	本地地址	字符串

media_dimension

返回图片的尺寸。

参数

file: 文件绝对路径

返回格式

对象类型。

键名	含义	类型	可选	说明
width	宽度	数字
height	高度	数字

nav_indicator

返回当前页面在导航树内的前后项。

参数

from_file: 导航树文件路径。可用普通路径字符串，或用 [[...]] 内链语法指向目标 Markdown（与正文内链规则一致，见链接与内链）；可写 [[目标|显示名]]，仅 | 前参与定位。

返回格式

{
    "prev": { // 可选
        "title": "标题",
        "link": "链接"
    },
    "next": { // 可选
        "title": "标题",
        "link": "链接"
    },
}

page_query

修改当前页查询参数并输出。

参数

所有输入参数覆盖更新旧的同名参数。

修改后的参数键值对，application/x-www-form-urlencoded 格式。

oops

终止模板解析，并展示错误信息。

参数

键名	含义	类型	可选	说明
message	错误信息	字符串

config

获取上下文语言相关的配置项。

参数

键名	含义	类型	可选	说明
key	键名	字符串		多级嵌套请使用 `/` 分割，必须以 `/` 开始，遵循RFC6901标准。如：`/site/name`
default	默认值	同系统常量类型	✔️

配置文件 everkm.yaml 中 __config 下指定 key 的值。

has_config

检测配置项是否存在

参数

键名	含义	类型	可选	说明
key	键名	字符串		同 config

布尔值

media

资源文件引用。如音频、视频、PDF文档等。

参数

键名	含义	类型	可选	说明
file	文件路径	字符串	相对路径基于所属 markdown 文件目录

URL 地址，同时在发布时，资源文件会自动打包到发布目录。

nav_tree

从指定的导航文件（通常是 Markdown 文件）解析出导航树结构，适用于书籍、文档等层级导航场景。

参数

from_file: 必选。导航文件路径。支持 [[...]] 内链语法（见链接与内链）；可写 [[目标|显示名]]，仅 | 前参与定位。
__page_path: 内部参数，当前页面路径（由模板上下文自动注入）。

{
    "nodes": [ // 导航树节点
        {
            "title": "节点标题",
            "link": "链接地址",
            "children": [ /* 子节点，结构同上 */ ]
        }
    ],
    "paths": [ // 当前页在导航树中的路径（面包屑）
        { "title": "标题", "url": "链接" }
    ]
}

nav_path

获取当前页面在导航树中的路径（面包屑），支持合并页面级面包屑。

参数

from_file: 必选。导航文件路径。支持 [[...]] 内链语法（见链接与内链）；可写 [[目标|显示名]]，仅 | 前参与定位。
merge: 可选。页面级面包屑数组，会与导航路径合并去重。
__page_path: 内部参数，当前页面路径（由模板上下文自动注入）。

LinkItem 数组。

[
    { "title": "标题", "url": "链接" },
]

post_neighbors

在与 posts() 相同的过滤/排序条件下，查询指定文章的前一篇与后一篇文章 ID。

邻接顺序与 posts() 列表完全一致：复用相同的 dir、tags、order_by、order_direction、include_dir_index 等参数。忽略 offset、limit、include_myself（邻接始终在全量过滤结果上计算）。

参数

id: 必选。当前文章 ID。
其他参数同 posts 函数（dir、tags、recursive、order_by、include_dir_index 等；offset / limit / include_myself 无效）。

{
    "prev_id": "前一篇文章 ID（可为 null）",
    "next_id": "后一篇文章 ID（可为 null）"
}

post_resources

读取单篇文章正文中引用的媒体资源（图片、音视频等），并物化为可发布的 URL。

参数

id 或 path：二选一，定位文章（同 post_meta；path 支持 [[...]] 内链语法）。
kinds：可选。过滤资源类型：image、audio、video、other。

文章不存在时返回 null；否则：

{
    "items": [
        {
            "kind": "image",
            "src": "./photo.jpg",
            "via": "image",
            "url": "/assets/media/...",
            "alt": "说明文字",
            "width": 1920,
            "height": 1080
        }
    ],
    "total": 1
}

post_meta / posts() 列表项不包含 content_resources，需显式调用本函数或 posts_resources。

posts_resources

在与 posts() 相同的过滤、排序与分页条件下，返回每篇文章的正文物化资源列表。

参数

列表参数同 posts（dir、tags、limit、offset 等）。
kinds：可选，同 post_resources。

{
    "items": [
        {
            "post": { /* 与 posts().items 单项结构一致 */ },
            "resources": [ /* 同 post_resources.items */ ]
        }
    ],
    "total": 42
}

total 为符合条件的文章总数（按文章分页，非资源条数）。

lang

返回当前生效的语言代码。

参数

无。

字符串，如 zh_CN、en_US。

asset_base_url

输出静态资源的 CDN 前缀地址。用于导出时资源引用添加 CDN 前缀。

参数

url: 可选。如果提供且以 ~/ 开头，会将 ~ 替换为 CDN 前缀后返回。

CDN 前缀字符串，或转换后的 URL。