配置详情

目录结构

以Hexo的根目录为例：

.
├── 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来说明

完整示例

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: '', // 可选
    },
  },
}

字段说明

写作平台

语雀

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

Notion

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

Filter 字段说明

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

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

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

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

Sorts 字段说明

sorts字段是为了对 Notion 数据库文档进行排序，以便生成一定顺序的目录信息，对文档的同步不影响。

例如，使用 VitePress 部署文档时，需要对文档按照指定顺序和结构生成路由和 sidebar。

详情见 Elog Docs 文档源码

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

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

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

Catalog 字段说明

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

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

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

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

部署平台

本地部署（local）

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

FormatExt 字段说明

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

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

// 如果需要返回带有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 类型定义如下：

/** 文章详情 */
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

图床平台

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

本地存储（local）

PrefixKey 字段说明

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

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

又拍云（upyun）

Github图床（github）

secretExt 字段说明

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

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

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,
}

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

环境变量配置

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

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

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

本地调试

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

elog sync -e .elog.env

# 语雀
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=

线上部署

线上部署时，只需要提前将以上用到的信息配置到环境变量上即可。

以 Github 为例，可以在仓库的设置-Secrets and variables-Actions-Secrets中进行配置，然后在流水线中注入即可。