# yuque-hugo-exporter

**Repository Path**: ssttddeeff/yuque-exporter

## Basic Information

- **Project Name**: yuque-hugo-exporter
- **Description**: 基于token的语雀文档导出工具，支持全部知识库导出，单个知识库导出，支持导出文档添加frontmatter以适配hugo博客
- **Primary Language**: JavaScript
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2023-07-18
- **Last Updated**: 2023-07-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

这是一个使用token导出语雀所有文档为markdown的node.js脚本，由于现在token使用需要超级会员才能创建，（以前创建的仍然可以用，本人就是），没有token 建议看下下面这个无需token即可导出的工具：

[GitHub - renyunkang/yuque-exporter: A tool for exporting Yuque documents as markdown.](https://github.com/renyunkang/yuque-exporter)

# 使用须知

使用前请确保已安装node.js，版本尽量保证在`16.20`以上（本人版本），之前的版本没有细测，不能百分百保证可以运行。

编辑根目录下的config.json文件，改为自己的配置项

```json
{
 "token":"",
 "login":"antusheng-2wzx0",
 "repo":"blog",
 "contentOutputDir":"D:/liu/gitfiles/test/content",
 "cacheDir": "./cache",
 "isDownloadAll": false,
 "addFrontmatter": true,
  "frontmatter": {
    "toc": true,
    "arr": "\n- item1\n- item2\n"
  },
  "frontmatterSplit": ";；，,"
}
```

- token 你的语雀token
- login 账户名称
- repo 仓库slug
- contentOutputDir 文档输出目录，请确保该路径存在，脚本没有进行判断是否存在并创建目录，不存在将无法写入文档
- cacheDir 缓存输出路径，要求同上
- isDownloadAll ，true表示下载所有知识库文档，false表示下载repo对应的知识库
- addFrontmatter 如果需要导出给导出的文档添加frontmatter，则设置为true，注意一旦设置为true则只能导出repo指定的知识库的文档，不是用作如hugo，hexo这类博客的话，请忽视该选项并设置为false
- frontmatter 可以配置在这里配置一些默认的frontmatter，注意只支持简单类型的value，如需要某个值为数组，请将其转换为正确的yaml字符串
- "frontmatterSplit 语雀文档开头自定义的frontmatter，当键是tags或者categories这类数组类型的值，其中的字符将作为分别符，如示例中`;；，,`中任一个作为数组的分隔符，并且目前也只能识别tags，categories

网页版语雀打开自己某个知识库的一篇文档，如：

https://www.yuque.com/antusheng-2wzx0/blog/cfksxn7pxs6v0mud

yuque.com/后面依次分别为 login，repo，和文章slug。

运行：`node index.mjs`

其他能运行mjs文件的均可以，如vscode的code runner

性能方面，本人832篇文档，约34万字，第一次导出时间不超过3分钟。



# 注意事项

- 脚本只能扁平化导出文档，文档顺序不能由语雀接口返回决定
- 目录配置请确保目录已经存在
- 支持全部知识库导出和单个知识库导出，全部导出时，请配置isDownloadAll为true，单个导出时配置为false，并且记得配置repo
- 为提升写入速度，采取依据语雀上的更新时间决定是否对文档进行写入，本地会保留更新时间的缓存，语雀上文档的更新时间与缓存的更新时间不一致时，才会重新写这个文档，如需手动重新写入，请删除缓存文件
- 文档的文件命名采取如下格式：`语雀上的文档标题-repo-slug`由于windows文件命名规范的限制，文档标题中的非法字符如：`<>:"\/\\|?*`会被替换掉为_
- addFrontmatter为true时，会根据语雀文档数据自动添加以下frontmatter：

```yaml
title: 语雀文档的标题
date: 语雀文档的发布时间，如2022-11-14T16:09:27.593Z
lastmod: 语雀文档的创建时间，2023-07-23T06:29:23.000Z
slug: 该文档的语雀slug，如tutr23bce4h2ynsq
cover: 语雀默认的封面，为文章的第一个图片
```

- frontmatter选项只做了默认的字符串拼接处理，会将里面的键值对解析为字符串`key: value  `并用换行连接起来，如果需要特殊的类型，请处理成正确的符合yaml语法的字符串，addFrontmatter为false时，该选项无效

- 对于博客中常见的tags，categories等，可以在语雀文档最前面添加类似如下格式的内容：

```
tags: 'hugo';个人博客
categories: '杂项';博客搭建
slug: 可以覆盖默认的slug
cover: 'https://cdn.jsdelivr.net/gh/Sentisfate/wanhuatong@main/img/QQ截图20221114231828.png'
---
```

开头不用---，此外value可以不用引号引起，对于数组类的，建议用`;`分隔，当然可以自定义frontmatterSplit选项，但在语雀中请不要写错。一个语雀中的示例大致如下：

![image-20230723185724019](https://cdn.jsdelivr.net/gh/Sentisfate/wanhuatong@main/img/image-20230723185724019.png)

由于语雀语法---加换行会被转换为水平线，注意只会识别第一个水平线前面的字符，如果没有或者前面的内容明显不是yaml语法格式的字符串，则不会进行解析。

# 额外的话

个人比较喜欢语雀的编辑器，并且语雀的文档管理也非常舒适，跨平台也很友好，但是付费分享真的让人无法接受（我的东西分享出去还要我花钱，没要钱就不错了doge），因此打算自建hugo博客，用语雀来搞云端笔记存储，hugo版的语雀导出很少，有些还用不了（个人原因不会用哈哈），因此自己写了一个导出脚本，用于后续博客文档的更新。

目前实现了同步功能，内容基本上没有问题，除了语雀特色的功能在markdown上无法显示，其余均可。实现了兼容博客需要的md格式类型如配置front-matter等。

后续开发计划是将图片链接本地话以及配置图床

实力有限，代码很烂，还望海涵。