Skip to content

配置详情

目录结构

以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 Urlhttps://www.yuque.com/api/v2
login个人路径/空间ID-
repo语雀仓库短名称,也称为语雀知识库路径�-
onlyPublic是否只获取公开文章false
onlyPublished是否只获取已发布文章false

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

Notion

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

字段必填类型说明默认值
tokenstringNotion Token
databaseIdstringnotion 中的数据库 id-
filterboolean|object过滤条件true
sortsboolean|object[]排序条件true
catalogboolean|object目录信息配置false

Filter 字段说明

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

  1. 默认值为 true ,即筛选数据库的status属性,且属性值为已发布,对应 Notion 的筛选规则为:
json
{ 
  property: 'status',
  select: {
  	equals: '已发布'
	}
}
  1. filter = false时,不进行筛选,默认下载数据库所有文档
  2. 当需要自定义筛选时,需要按照Notion的筛选规则进行。具体请参考Notion API文档 - Filter database entries

Sorts 字段说明

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

  1. 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', // 升序
}
  1. sorts=true或者不填时,默认按照文档创建时间倒序进行排序
  2. 当需要自定义排序时,需要按照Notion的筛选规则进行。具体请参考 Notion API文档 - Sort database entries

Catalog 字段说明

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

  1. 默认值为false,即不记录文档的目录信息
  2. catalog=true,则表示按照数据库的catalog字段进行记录
  3. 当需要自定义属性时,则可按照以下格式进行配置
jsx
catalog: {
  enable: true,
  property: "自定义属性"
}
  1. 当需要配置catalog字段时,请保证数据库有相关属性存在(支持单选/多选)

部署平台

本地部署(local)

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

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

FormatExt 字段说明

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

  1. 目前只支持 Common Js 标准的处理器
  2. 处理器需要暴露一个同步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

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

图床平台

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

本地存储(local)

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

PrefixKey 字段说明

  1. 本地部署平台一般会有资源根目录,会将某个文件夹视为根目录,而prefixKey就是配置资源目录的前缀
  2. 例如 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到环境变量或者本地,而是通过异步接口获取

  1. 目前只支持 Common Js 标准拓展点
  2. 拓展点需要暴露一个同步/异步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,
}
  1. getSecret 返回的密钥信息需要符合图床实例SDK的字段要求,具体请参考对应图床 SDK/API

环境变量配置

  1. 当 Elog 配置文件为 Js 类型时,可在配置文件中通过process.env.xxx自定义环境变量。
  2. 当 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中进行配置,然后在流水线中注入即可。