快速开始

安装

手动下载

下载 👉 道盒发布命令行工具，解压缩后，将可执行文件 everkm-publish 放到 PATH 变量设定的搜索目录中，即可在命令行下运行。

Mac Brew 安装

brew install everkm/tap/everkm-publish

Npm / Pnpm 安装

pnpm add everkm-publish

通常用于自定义模板开发。

创建工作区

# 在当前目录创建工作区
everkm-publish create <base name>

--theme 可选。指定样式名称。默认为 yilog。

启动本地预览

启动预览

# 切换到Base目录
cd <base dir>

# 启动预览环境
everkm-publish serve --theme <your theme>

用浏览器打开 http://localhost:9081 (默认监听地址) 可预览。

编辑 <base>/content/post/ 目录下的 Markdown 文件。

导出静态文件

everkm-publish serve --theme <your theme> --export

目录结构

.
├── Makefile            # 辅助命令管理, 可选
├── content             # 数据目录
│   └── post            # 内容根目录
│       ├── _page       # 项目数据, `_` 打头的目录或文件，`posts` 函数会忽略
│       ├── docs        # 项目数据
│       └── guide       # 项目数据
├── dist                # 通常作为发布目录
├── everkm-theme.yaml   # 模板开发, 模板配置文件 
├── everkm.yaml         # 项目配置文件
├── package.json        # 模板开发, javascript 依赖, 可选
├── webpack.config.js   # 模板开发, 可选
├── src                 # 模板开发目录
│   ├── assets
│   └── templates       # 模板文件
│       ├── en_US.i18n.md # 语言包
│       ├── detail.html # 模板详情页
│       ├── index.html  # 模板首页
├── theme               # 模板安装目录
│   ├── dev             # 开发模板预发布目录
│   ├── yilog           # 其他已安装的模板

工作区配置文件

文件名: everkm.yaml

设置渲染的结构、模板及参数，优先级高于 everkm-theme.yaml。

cfg:
  timezone: Asia/Chongqing
  site:
    name: Everkm

sitemap:
  channel_name: "{{t(text='Home')}}"
  children:
    - path: blog/
      channel_name: "{{t(text='Blog')}}"
      channel_path: blog/
      qs:
        dir: /blog/
        __tpl: /list.html
        no_dir: true
        category_url_base: /blog/category/
        page_size: 10
    - path: changelog.html
      channel_name: "{{t(text='Changelog')}}"
      qs:
        __tpl: /details.html
        no_dir: true
        no_time: true

map_url:
  - dir: /blog/**
    url: /blog/{{year}}/{{slug}}.html
  - dir: /docs/**
    url: /docs/{{slug}}.html

`cfg` 字段

cfg 工作区配置，在模板中通过全局变量 __cfg 获取
cfg.timezone 工作区时区，默认值 Asia/Chongqing
cfg.default_lang 默认语言翻译环境, 默认值 en_US

`map_url` 字段

map_url 用于通过文件路径生成对应的 URL
map_url.dir 路径通配符
map_url.url 对应的 URL Path。
支持以下占位符，使用 {{}} 包裹。
1. slug 文件 Slug
2. year 文件创建年份
3. month 文件创建月份
4. day 文件创建 day

`sitemap` 字段

sitemap 覆盖 everkm-theme.yaml 中的 sitemap 配置
sitemap 设置站点结构。所有的字段值支持模板语法，
sitemap.path Url Path 通配符, 省略默认为 /。当以 / 结尾时，表示目录下的所有文件，但不包含孙级后代文件。如：blog/ 等同于 blog/*
sitemap.channel_name 栏目名称，用于面包屑导航，省略时忽略此段
sitemap.channel_path 栏目 URL 片段，用于面包屑导航，省略时使用 path 属性，如果有通配符则报错。
sitemap.qs 渲染模板时的上下文参数，通过全局变量 __qs 获取
sitemap.qs.__tpl 默认采用的模板路径
sitemap.qs.* 其他自定义参数
sitemap.children[] 子路径，类型同 sitemap

预览导出

渲染导出所有页面

everkm-publish serve --export

everkm-publish 会从入口地址开始，抓取其内容，并按 URL Path 部分保存为文件，同时跟踪抓取内容的其它链接，符合指定规则时，继续抓取，直至全部导出完成。除了导出页面内容外，还将包括文章中引用的图片，音频，视频，以及其它文档附件。不会导出未被引用的资源。

特殊目录

如果需要某些未被引用的文件一起发布时，需要将其放入以下特殊目录。

__assets: 发布时复制到静态资源 assets 目录。主要针对页面附属的资源文件。
__public: 发布时复制到内容页面目录。

注意：当目标文件存在时，会被覆盖写入。

详细命令参数

Preview / Export

Usage: everkm-publish serve [OPTIONS]

Options:
      --work-dir <WORK_DIR>
          Working directory
          
          [env: EVERKM_WORK_DIR=]
          [default: ./]

      --dev-dir <DEV_DIR>
          Development directory
          
          Priority over work_dir
          
          [env: EVERKM_DEV_DIR=]

      --dist-dir <DIST_DIR>
          Export directory
          
          [env: EVERKM_DIST_DIR=]

      --theme <THEME>
          Name of theme
          
          [env: EVERKM_THEME=]
          [default: dev]

      --cdn-prefix <CDN_PREFIX>
          CDN's prefix of assets
          
          [env: EVERKM_CDN_PREFIX=]

      --lang <LANG>
          Language code
          
          [env: EVERKM_LANG=]

      --base-prefix <BASE_PREFIX>
          Context base of url
          
          [env: EVERKM_BASE_PREFIX=]
          [default: ]

      --listen <LISTEN>
          Listening address
          
          [env: EVERKM_LISTEN=]
          [default: 127.0.0.1:9081]

  -e, --export
          As export mode

      --start-urls <START_URLS>
          A list of exported entry addresses. Multiple are separated by
          spaces.
          
          Default:  `/index.html`
          
          [env: EVERKM_START_URLS=]

      --stop-urls <STOP_URLS>
          A list of address prefixes to ignore. Multiple are separated by
          spaces
          
          [env: EVERKM_STOP_URLS=]

  -h, --help
          Print help (see a summary with '-h')

安装