配置详情

目录结构

以 Hexo 的根目录为例：

json

.
├── public
├── scaffolds
├── source
├── themes
├── .elog.env						// Elog用于本地调试时的环境变量配置
├── .gitignore					// git忽略文件，请将.elog.env文件加入，防止密码等信息误提交
├── _config.yml
├── elog.cache.json			// Elog的缓存文件，用于缓存上次同步的文件
├── elog.config.js		  // Elog的配置文件
└── package.json

以下配置都是基于elog.config.js来说明

完整示例

javascript

module.exports = {
  write: {
    platform: "yuque",
    yuque: {
      token: process.env.YUQUE_TOKEN,
      baseUrl: "",
      login: process.env.YUQUE_LOGIN,
      repo: process.env.YUQUE_REPO,
      onlyPublic: false,
      onlyPublished: true,
    },
    notion: {
      token: process.env.NOTION_TOKEN,
      databaseId: process.env.NOTION_DATABASE_ID,
      filter: true, // {property: 'status', select: {equals: '已发布'}}
      sorts: true, // [{timestamp: 'created_time', direction: 'descending'}],
      catalog: false,
    },
  },
  deploy: {
    platform: "local",
    local: {
      outputDir: "",
      filename: "",
      format: "",
      catalog: false,
      formatExt: "",
    },
    confluence: {
      user: process.env.CONFLUENCE_USER,
      password: process.env.CONFLUENCE_PASSWORD,
      baseUrl: process.env.CONFLUENCE_BASE_URL,
      spaceKey: process.env.CONFLUENCE_SPACE_KEY,
      rootPageId: process.env.CONFLUENCE_ROOT_PAGE_ID, // 可选
      formatExt: "", // 可选
    },
  },
  image: {
    enable: false,
    platform: "local",
    local: {
      outputDir: "",
      prefixKey: "",
    },
    oss: {
      secretId: process.env.OSS_SECRET_ID,
      secretKey: process.env.OSS_SECRET_KEY,
      bucket: process.env.OSS_BUCKET,
      region: process.env.OSS_REGION,
      host: process.env.OSS_HOST,
      prefixKey: "",
      secretExt: "", // 可选
    },
    cos: {
      secretId: process.env.COS_SECRET_ID,
      secretKey: process.env.COS_SECRET_KEY,
      bucket: process.env.COS_BUCKET,
      region: process.env.COS_REGION,
      host: process.env.COS_HOST,
      prefixKey: "",
      secretExt: "", // 可选
    },
    qiniu: {
      secretId: process.env.QINIU_SECRET_ID,
      secretKey: process.env.QINIU_SECRET_KEY,
      bucket: process.env.QINIU_BUCKET,
      region: process.env.QINIU_REGION,
      host: process.env.QINIU_HOST,
      prefixKey: "",
      secretExt: "", // 可选
    },
    upyun: {
      user: process.env.UPYUN_USER,
      password: process.env.UPYUN_PASSWORD,
      bucket: process.env.UPYUN_BUCKET,
      host: process.env.UPYUN_HOST,
      prefixKey: "",
      secretExt: "", // 可选
    },
    github: {
      user: process.env.GITHUB_USER,
      token: process.env.GITHUB_TOKEN,
      repo: process.env.GITHUB_REPO,
      branch: "",
      host: "",
      prefixKey: "",
      secretExt: "", // 可选
    },
  },
};

字段说明

字段	说明
write	写作平台详细配置
deploy	部署平台详细配置
image	图床平台详情配置

写作平台

语雀

语雀关键信息获取及配置流程请移步关键信息获取页面

字段	必填	说明	默认值
token	是	语雀 Token	-
baseUrl	否	语雀 API 请求的 Base Url	https://www.yuque.com/api/v2
login	是	个人路径/空间 ID	-
repo	是	语雀仓库短名称，也称为语雀知识库路径	-
onlyPublic	否	是否只获取公开文章	false
onlyPublished	否	是否只获取已发布文章	false

baseUrl 为语雀 API 请求路径当知识库类型为个人知识库时，无需配置。当知识库类型为团队知识库时，baseUrl=https://空间id.yuque.com/api/v2，login=空间id，repo=空间中的语雀知识库路径

Notion

Notion 模版获取、关键信息获取及配置流程请移步关键信息获取页面

字段	必填	类型	说明	默认值
token	是	string	Notion Token
databaseId	是	string	notion 中的数据库 id	-
filter	否	boolean ｜ object	过滤条件	true
sorts	否	boolean ｜ object[]	排序条件	true
catalog	否	boolean ｜ object	目录信息配置	false

Filter 字段说明

filter字段是为了筛选 Notion 数据库文档，表示哪些文章需要被 Elog 下载。

默认值为 true ，即筛选数据库的status属性，且属性值为已发布，对应 Notion 的筛选规则为：

json

{
  "property": "status",
  "select": {
    "equals": "已发布"
  }
}

当filter = false时，不进行筛选，默认下载数据库所有文档
当需要自定义筛选时，需要按照 Notion 的筛选规则进行。具体请参考Notion API 文档 - Filter database entries

Sorts 字段说明

sorts字段是为了对 Notion 数据库文档进行排序，以便生成一定顺序的目录信息，对文档的同步不影响。 例如，使用 VitePress 部署文档时，需要对文档按照指定顺序和结构生成路由和 sidebar。详情见 Elog Docs 文档源码

elog 提供了一些预设参数，如下。例如sorts=sortDesc即按照数据库的 sort 字段进行倒序排列

typescript

export const enum NotionSortPreset {
  /** 按自定义日期排序 */
  dateDesc = "dateDesc", // 倒序
  dateAsc = "dateAsc", // 升序
  /** 按创建时间排序 */
  createTimeDesc = "createTimeDesc", // 倒序
  createTimeAsc = "createTimeAsc", // 升序
  /** 按更新时间排序 */
  updateTimeDesc = "updateTimeDesc", // 倒序
  updateTimeAsc = "updateTimeAsc", // 升序
  /** 按数据库的sort字段进行排序 */
  sortDesc = "sortDesc", // 倒序
  sortAsc = "sortAsc", // 升序
}

当sorts=true或者不填时，默认按照文档创建时间倒序进行排序
当需要自定义排序时，需要按照 Notion 的筛选规则进行。具体请参考 Notion API 文档 - Sort database entries

Catalog 字段说明

catalog字段是为了配置文档的目录信息，如果需要按照指定目录分类下载时，则需要进行配置，对文档的同步不影响。

默认值为false，即不记录文档的目录信息
当catalog=true，则表示按照数据库的catalog字段进行记录
当需要自定义属性时，则可按照以下格式进行配置

jsx

catalog: {
  enable: true,
  property: "自定义属性"
}

当需要配置catalog字段时，请保证数据库有相关属性存在（支持单选/多选）

部署平台

本地部署（local）

适用于所有类似 Hexo 的框架：通过向指定目录存放 markdown 文档来进行渲染的博客平台

字段	必填	说明	默认值
outputDir	否	文档输出目录	-
filename	否	生成文档的命名格式，取值 urlname ｜ title	title
format	否	适配器，取值 markdown ｜ matter-markdown ｜ wiki ｜ html	markdown
catalog	否	是否按照目录生成文档	false
formatExt	否	自定义文档处理适配器路径	-

FormatExt 字段说明

自定义文档处理适配器.js文件路径，当需要对文档进一步处理时，可配置此选项

目前只支持 Common Js 标准的处理器
处理器需要暴露一个同步的 format 的方法，不支持异步方法

javascript

// 如果需要返回带有front-matter的md字符串，则需要安装并引入此库
const { matterMarkdownAdapter } = require("@elog/plugin-adapter");

/**
 * 自定义文档处理器
 * @param {DocDetail} doc doc的类型定义为 DocDetail
 * @return {string} 返回处理后的文档内容字符串
 */
const format = (doc) => {
  doc.body = process(body);
  // 直接返回md内容字符串
  return doc.body;
  // 返回带有front-matter的md字符串
  // return matterMarkdownAdapter(doc);
};

module.exports = {
  format,
};

DocDetail 类型定义如下：

typescript

/** 文章详情 */
export interface DocDetail extends BaseDoc {
  /** 实际部署时的markdown文档字符串 */
  body: string;
  /** 原始markdown文档字符串 */
  body_original: string;
  /** 部署到wiki时会存在 */
  body_wiki?: string;
  /** html字符串 */
  body_html?: string;
  /** 文章属性 */
  properties: DocProperties;
  /** 语雀文章目录路径， Notion暂不支持 */
  catalog?: YuqueCatalog[];
}

export interface BaseDoc {
  /** 文章唯一ID */
  id: string;
  /** 文章ID */
  doc_id: string;
  /** 更新时间，冗余字段 */
  updated: number;
}

/** 文章属性 */
export interface DocProperties {
  urlname: string;
  title: string;
  date: string;
  updated: string;
  [key: string]: any;
}

/** 语雀知识库目录 */
export interface YuqueCatalog {
  /** 类型：文章/分组 */
  type: "DOC" | "TITLE";
  title: string;
  uuid: string;
  child_uuid: string;
  parent_uuid: string;
  slug: string;
  depth: number;
  level: number;
}

Confluence

字段	必填	说明	默认值
baseUrl	是	Confluence API 请求 Base Url	-
spaceKey	是	空间 Key	-
rootPageId	是	根页面 ID，Elog 会把文档统一存到此目录下	-
user	是	Confluence 账号	-
password	是	Confluence 密码	-
formatExt	否	自定义文档处理适配器路径，需要符合 Confluence 格式要求	-

图床平台

图床关键信息获取及配置流程请移步关键信息获取页面。

本地存储（local）

字段	必填	说明	默认值
outputDir	是	图片输出目录	-
prefixKey	否	图片资源统一前缀	-

PrefixKey 字段说明

本地部署平台一般会有资源根目录，会将某个文件夹视为根目录，而prefixKey就是配置资源目录的前缀
例如 Vitpress，如果outputDir=./docs/asset/images，则prefixKey=/asset/images

腾讯云（cos）/阿里云（oss）/七牛云（qiniu）

字段	必填	说明	默认值
secretId	是	图床密钥 ID	-
secretKey****	是	图床密钥 KEY	-
bucket	是	桶名称/七牛云空间	-
region	是	存储区域	-
host	否	指定域名，七牛云必填	-
prefixKey	否	上传路径，默认上传到根路径	-
secretExt	否	图床密钥拓展点	-

又拍云（upyun）

字段	必填	说明	默认值
user****	是	操作员账号	-
password	是	操作员密码	-
bucket	是	地区	-
host	否	指定域名，又拍云会默认提供 30 天的临时测试域名，建议配置自定义域名	临时域名：http://xxx.est.upcdn.net
prefixKey	否	上传路径，默认上传到根路径	-
secretExt	否	图床密钥拓展点	-

Github 图床（github）

字段	必填	说明	默认值
token	是	Github Token	-
user	是	用户名	-
repo	是	仓库名	-
branch	否	分支	master
host	否	加速域名，取值 cdn.jsdelivr.net	-
prefixKey	否	上传路径，默认上传到根路径	-
secretExt	否	图床密钥拓展点	-

secretExt 字段说明

图床密钥拓展点路径，一般适用于不想直接配置 AK 到环境变量或者本地，而是通过异步接口获取

目前只支持 Common Js 标准拓展点
拓展点需要暴露一个同步/异步的 getSecret 的方法

typescript

const axios = require("axios");

const getOssSts = async () => {
  return await axios.get("https://xxxx/oss/sts?directory=elog");
};

const getSecret = async () => {
  const res = await getOssSts();
  const { accessKeyId, accessKeySecret, securityToken, dir, region, bucket } =
    res.data.data;
  return {
    secretId: accessKeyId,
    secretKey: accessKeySecret,
    stsToken: securityToken,
    secure: true,
    prefixKey: dir,
    region,
    bucket,
  };
};

module.exports = {
  getSecret,
};

getSecret 返回的密钥信息需要符合图床实例 SDK 的字段要求，具体请参考对应图床 SDK/API

环境变量配置

当 Elog 配置文件为 Js 类型时，可在配置文件中通过process.env.xxx自定义环境变量。

当 ELog 配置文件为 Json 类型时，Elog 会优先从配置文件中获取，如果获取不到，则会从环境变量中获取。Elog 默认只会读取以下环境变量值：

Key	Value
YUQUE_TOKEN	语雀 Token
NOTION_TOKEN	Notion Token
CONFLUENCE_USER	Confluence 账号
CONFLUENCE_PWD	Confluence 密码
GITHUB_TOKEN	Github Token
COS_SECRET_ID	腾讯云 COS 的 secretId
COS_SECRET_KEY	腾讯云 COS 的 secretKey
OSS_SECRET_ID	阿里云 OSS 的 AccessKey ID
OSS_SECRET_KEY	阿里云 OSS 的 AccessKey Secret
QINIU_SECRET_ID	七牛云的 AccessKey
QINIU_SECRET_KEY	七牛云的 SecretKey
UPYUN_SECRET_ID	又拍云的操作员账号
UPYUN_SECRET_KEY	又拍云的操作员密码

⚠️ 为了安全，在实际配置中请不要将敏感信息写在配置文件中，Elog 提供了更优雅的本地调试方式。

本地调试

为了方便本地调试，Elog 支持从本地文件中获取环境变量。只需要在部署平台根目录新增.elog.env文件，将用到的配置写入，然后在执行同步命令时指定环境变量文件即可。

bash

elog sync -e .elog.env

bash

# 语雀
YUQUE_TOKEN=
YUQUE_LOGIN=
YUQUE_REPO=

# Notion
NOTION_TOKEN=
NOTION_DATABASE_ID=

# Confluence
CONFLUENCE_BASE_URL=
CONFLUENCE_USER=
CONFLUENCE_PASSWORD=
CONFLUENCE_SPACE_KEY=
CONFLUENCE_ROOT_PAGE_ID=

# 腾讯云
COS_SECRET_ID=
COS_SECRET_KEY=
COS_BUCKET=
COS_REGION=
COS_HOST=

# 阿里云
OSS_SECRET_ID=
OSS_SECRET_KEY=
OSS_BUCKET=
OSS_REGION=
OSS_HOST=

# 七牛云
QINIU_SECRET_ID=
QINIU_SECRET_KEY=
QINIU_BUCKET=
QINIU_REGION=
QINIU_HOST=

# 又拍云
UPYUN_USER=
UPYUN_PASSWORD=
UPYUN_BUCKET=
UPYUN_HOST=xxx.xx.upaiyun.com

# Github
GITHUB_USER=
GITHUB_TOKEN=
GITHUB_REPO=

⚠️ 注意：请将**.elog.env**文件加入 **.gitignore** ，防止误提交到 git 仓库

线上部署

线上部署时，只需要提前将以上用到的信息配置到环境变量上即可。以 Github 为例，可以在仓库的设置-Secrets and variables-Actions-Secrets中进行配置，然后在流水线中注入即可。

配置详情 #

目录结构 #

完整示例 #

字段说明 #

写作平台 #

语雀 #

Notion #

Filter 字段说明 #

Sorts 字段说明 #

Catalog 字段说明 #

部署平台 #

本地部署（local） #

FormatExt 字段说明 #

Confluence #

图床平台 #

本地存储（local） #

PrefixKey 字段说明 #

腾讯云（cos）/阿里云（oss）/七牛云（qiniu） #

又拍云（upyun） #

Github 图床（github） #

secretExt 字段说明 #

环境变量配置 #

本地调试 #

线上部署 #

配置详情

目录结构

完整示例

字段说明

写作平台

语雀

Notion

Filter 字段说明

Sorts 字段说明

Catalog 字段说明

部署平台

本地部署（local）

FormatExt 字段说明

Confluence

图床平台

本地存储（local）

PrefixKey 字段说明

腾讯云（cos）/阿里云（oss）/七牛云（qiniu）

又拍云（upyun）

Github 图床（github）

secretExt 字段说明

环境变量配置

本地调试

线上部署