测试

# 0 什么是内容块

内容块定义

“#内容块#”指的是一块内容，每块这样的内容通过一个全局唯一的 ID 进行标识。ID 是程序自动生成的，形如： 202008250000-a1b2c3d，由时间和 7 位随机字符组成。

内容块类型

最常见的内容块就是我们所熟悉的段落（Paragraph）。在中文传统排版中，段落通常是通过段首缩进（空两格）来表示，随着互联网的发展，逐渐影响了段落的表示。现在使用较多的方式是增加段落之间的行距，或者使用空行来分隔段落。

实际使用时，仅仅靠段落排版是不够的，往往还需要用到标题（Heading）、列表（List）、表格（Table）、块引用（Blockquote）等来丰富我们的排版。这些排版样式除了视觉上的不同，更重要的是它们在一定程度上表达了内容的语义。比如在看到无序列表时，我们可以知道每个列表项是不分先后的平级关系，而在看到有序列表时则相反。

所以，内容块存在”很多类型”⁹，不同的排版格式会形成不同的内容块。#内容块/类型#

组合内容块

一篇文档是一些内容块的组合，内容块是基本单位。这就好比乐高积木，可以使用不同的基本模块进行组合。#注意#：文档本身也是一种内容块，更准确地说，文档块、列表块、引述块这三种内容块是容器块，他们可以包含其他任意类型的内容块。#内容块/组合#

至此，我们已经能够用内容块来描述所有的内容了，这样就能通过统一的用法来”链接内容块”¹⁰了。逻辑上没有页面（Page）概念，减少使用中不必要的负担，让用户将注意力集中在内容块上。

命名和备注

我们可以为每个内容块命名、添加别名和备注。命名和别名主要用于反链”提及”¹¹搜索，备注用于记录一些不便在内容区中出现的信息。

在 设置 - 编辑器 中打开显示书签、命名、别名标识选项后，被命名的内容块在编辑器中会被加上外框显示。如果对文档块进行命名和备注，则当鼠标悬浮文档树文档上时将浮出该文档的相关命名和备注信息。

可使用”嵌入内容块”¹²对命名和备注进行搜索汇总，比如列出备注中包含 简短 关键字的内容块：

我们可以为每个内容块命名、添加别名和备注。命名和别名主要用于反链((20210106201736-oyu11fw “提及”))搜索，备注用于记录一些不便在内容区中出现的信息。 ↩

# 3 在内容块中遨游

链接

文档内容中的链接分为两种：

• 标准 URL 超链接，使用浏览器打开，用于互联网资源访问
• 通过 ((id)) 建立的内容块链接，用于在思源内部进行双链

缩放聚焦

• 在块标上右键下拉菜单中选择进入后，编辑器会聚焦到该内容块上
• 通过编辑器顶部的面包屑导航能够在上下文中进行跳转

关系图

关系图分为文档级和全局。文档的关系图是以当前文档块展开，并呈现所有和该文档有关联的（正向链接和反向链接）内容块；全局关系图是所有笔记本中所有的块和链接关系。

按住 Ctrl 单击节点：跳转到该节点。

反向链接

反向链接是文档级的，列出当前文档中内容块被引用和被提及所在的块。

链接

• 鼠标悬浮引用块前面的标识会弹出预览浮窗
• 单击反链列表中的引用块进行跳转

提及

提及使用当前文档中内容块名称和别名作为关键字进行搜索，搜索结果为包含这些关键字的内容块。可以通过链接按钮将提及转换为链接：提及处会使用 ((id "内容块名称")) 进行替换。 ↩

# 窗口和页签

思源支持多窗口和多页签，这样可以方便地进行文档编辑和查看。

页签上支持上下和左右分屏，打开的所有页签是实时同步内容的。比如对于相同一份文档进行多开页签，在其中一个页签中编辑保存后，其他页签也会自动同步最新内容，在享受多开的便利时避免脏数据覆盖。

除了文档保存是同步的，保存后产生的关联渲染也是同步的，文档相关的内容块预览以及关系图都是实时刷新，这样能在最小限度上排除干扰，让我们将注意力集中在笔记内容上。

除了分屏操作，页签也支持拖拽，这样我们能够随心所欲地布置整个界面，在自己最舒服的布局下记录笔记和整理知识。

如果你正在使用的设备屏幕较小，可以考虑”通过浏览器使用”¹³，这样就能通过浏览器实例进行界面切换。 ↩

# 3 常见问题与解答

思源是如何存储数据的？

数据保存在工作空间文件夹下（默认位于用户家目录 Documents/SiYuan，可在 设置 - 关于 中进行修改），在工作空间 data 文件夹下：

• assets 用于保存所有插入的资源文件
• templates 用于保存”模板片段”¹⁴
• widgets 用于保存挂件
• emojis 用于保存 Emoji 图片
• 其余文件夹就是用户自己创建的笔记本文件夹，笔记本文件夹下 .sy 后缀的文件用于保存文档数据，数据格式为 JSON

删除文档有什么#注意#事项吗？

文档被删除后不会出现在操作系统回收站中，而是直接删除，删除时思源会生成”编辑历史”¹⁵。

如何才能只换行不新起段落？

请使用 Shift+Enter。

如何在中文段首缩进？

请使用全角空格，这样内容自动折行以后才能对齐。

移动标题时如何带下方块一起移动？

将标题折叠以后再移动。

如何跨页多选内容块？

在开始的地方单击，滚动页面以后在结束的地方按住 Shift 单击。

如何调整表格行列？

表格块的块标菜单中有操作入口。

幻灯片演示如何翻页？

在文档排版中需要使用 --- 来分隔每页内容，具体用法请参考”幻灯片演示”¹⁶。

如何使用第三方同步盘进行数据同步？

• 请仅同步 工作空间/data/，切勿同步整个工作空间
• 思源运行期间请暂停第三方同步，否则可能会出现数据损坏，细节请参考这里
• Android 端数据文件夹路径为 内部存储设备/Android/data/org.b3log.siyuan/files/siyuan/data/，该路径是应用私有路径，其他程序无法读取，只能手动复制
• 第三方同步和思源同步存在冲突，切勿同时使用
• 思源同步的使用方式请参考”数据同步”¹⁷

如何删除不再需要的云端资源文件？

#TODO#

计划支持插件吗？

思源支持”通过浏览器使用”¹³，可以通过浏览器插件来扩展功能。我们很期待其他开发者为思源编写浏览器插件。随着”内核 API”¹⁸ 的逐步提供，后续我们会引入插件机制。

使用需要付费吗？

本地功能完全免费使用，云端服务需要年付订阅。

如果你在非中国大陆地区需要创建账号和支付订阅，请发送邮件给我们（845765@qq.com），我们将为你手动创建账号和创建 PayPal 邮件支付订单，谢谢。 ↩

# 1 隐私条款和使用授权

隐私条款

• 所有数据都保存在用户自己完全控制的设备上
• 不会收集任何使用数据

用户授权协议

本授权协议适用且仅适用于思源笔记（以下简称为“本软件”），云南链滴科技有限公司对本授权协议拥有最终解释权。

你一旦确认本协议并开始使用本软件，即被视为完全理解并接受本协议的各项条款。电子文本形式的授权协议如同双方书面签署的协议一样，具有完全的和等同的法律效力。

在享有条款授予的权力的同时，受到相关的约束和限制。协议许可范围以外的行为，将直接违反本授权协议并构成侵权，我们有权随时终止授权，责令停止损害，并保留追究相关责任的权力。

协议许可的权利

1. 你可以在协议规定的约束和限制范围内使用本软件
2. 你拥有使用本软件所撰写的内容的所有权，并独立承担与这些内容的相关法律义务

协议规定的约束和限制

1. 未经官方许可，禁止在本软件的整体或任何部分基础上发展派生版本、修改版本或第三方版本用于重新分发
2. 如果你未能遵守本协议的条款，你的授权将被终止，所被许可的权利将被收回，并承担相应法律责任

有限担保和免责声明

本软件及所附带的文件是作为不提供任何明确的或隐含的赔偿或担保的形式提供的。 ↩

### 上架主题集市

上架前请确认你的主题仓库根路径下至少包含这三个文件（仓库示例）：

• theme.css
• theme.json（请确保 JSON 格式正确）
• preview.png（请压缩图片大小在 128 KB 以内）

确认无误以后请通过对社区集市仓库发起 pull request，修改 themes.json 文件。该文件是所有社区主题仓库的索引，格式为：

1
2
3
4
5
{
  "repos": [
    "username/reponame@commithash"
  ]
}

其中 commithash 请填写你的主题仓库上最近一次发布版本的 Git 提交哈希值，请使用完整哈希值，不要使用 7 位短值。

更新

如果你开发的主题更新了版本，请记得：

• 更新你的主题配置 theme.json 中的 version 字段
• 再次对社区集市发起 Pull Request

↩

## 上架模板集市

上架前请确认你的模板仓库根路径下至少包含这两个文件（仓库示例）：

• template.json（请确保 JSON 格式正确）
• preview.png（请压缩图片大小在 128 KB 以内）

确认无误以后请通过对社区集市仓库发起 pull request，修改 templates.json 文件。该文件是所有社区模板仓库的索引，格式为：

1
2
3
4
5
{
  "repos": [
    "username/reponame@commithash"
  ]
}

其中 commithash 请填写你的模板仓库上最近一次发布版本的 Git 提交哈希值，请使用完整哈希值，不要使用 7 位短值。

更新

如果你开发的模板更新了版本，请记得：

• 更新你的模板配置 template.json 中的 version 字段
• 再次对社区集市发起 Pull Request

↩

### 上架图标集市

上架前请确认你的图标仓库根路径下至少包含这三个文件：

• icon.js
• icon.json（请确保 JSON 格式正确）
• preview.png（请压缩图片大小在 128 KB 以内）

确认无误以后请通过对社区集市仓库发起 pull request，修改 icons.json 文件。该文件是所有社区图标仓库的索引，格式为：

1
2
3
4
5
{
  "repos": [
    "username/reponame@commithash"
  ]
}

其中 commithash 请填写你的图标仓库上最近一次发布版本的 Git 提交哈希值，请使用完整哈希值，不要使用 7 位短值。

更新

如果你开发的图标更新了版本，请记得：

• 更新你的图标配置 icon.json 中的 version 字段
• 再次对社区集市发起 Pull Request

↩

# 1 内容块类型

内容块类型简述

鼠标悬浮在内容块上左侧会出现该内容块对应的图标。

标识	类型	“元类型”19
	段落块	叶子块
	标题块	叶子块
	数学公式块	叶子块
	代码块	叶子块
	表格块	叶子块
	无序列表块	容器块
	有序列表块	容器块
	任务列表块	容器块
	列表项块	容器块
	引述块	容器块
	超级块	容器块
	文档块	容器块

内容块类型详解

下面我们分别介绍一下这些内容块类型的细节。#内容块/类型#

段落块

这里是一个示例段落。

在一个段落后直接回车会形成新的段落。

标题块

以上就是标题块，支持一级到六级。

数学公式块

代码块

1
function hello() {}

表格块

表格中如需使用 | 请使用 \ 转义，即需要输入 \|。

无序列表块

• 列表项一
• 列表项二

无序列表块是一种”元类型”¹⁹。

如果需要在列表项中进行换行，请使用 Shift Enter。

有序列表块

1. 列表项一
2. 列表项二

有序列表块是一种”元类型”¹⁹。

任务列表块

• 待办一
• 待办二

任务列表块是一种”元类型”¹⁹。

列表项块

通过列表项块可以实现大纲式笔记的基本用法，列表项块是一种”元类型”¹⁹。

引述块

注意不是内容块引用，而是引述块（Blockquote）。

引述块是一种”元类型”¹⁹。

超级块

超级块是一种”元类型”¹⁹。可用于组合文档内连续的内容块，也用于支持横向排版。

文档块

整个文档是一个块，文档块是一种”元类型”¹⁹。

内容块元类型

内容块在逻辑上分为叶子块和容器块，叶子块不能包含其他块，容器块可以包含其他块：

• 列表块：只能包含列表项块
• 列表项块：可以包含任意非文档块
• 引述块：可以包含任意非文档块
• 超级块：可以包含任意非文档块
• 文档块：可以包含任意非文档块

↩

# 2 引用内容块

概述

输入 (( 后将触发内容块引用搜索，继续输入作为搜索关键字，在搜索结果中使用上下键选定后回车就可以完成内容块的引用了。

内容块引用的完整语法是： ((id "text"))，其中 id 形如： 202008250000-a1b2c3d，由时间和 7 位随机字符组成，内容块 id 是在创建内容块时就会自动生成的；后面的 text 是在引用处对该内容块的自定义锚文本。建立好内容块引用后，鼠标悬浮在锚文本上后将弹出预览浮层，展现被引用的内容块。#内容块/引用#

链接方向

• 正向链接（Forwardlink），即当前内容块使用了哪些其他内容块
• 反向链接（Backlink），即当前内容块被那些其他内容块使用了

正向链接包含在当前块的内容中，我们可以很直观的看到。反向链接需要在其他文档中搜索才能知道，而恰恰是这些信息对我们比较有价值。我们可以通过以下两种方式来帮助我们更好的掌握知识点或者发散思路：

• “关系图”²⁰：浏览内容块之间的正向和反向链接关系
• “反向链接”²¹：以文本列表的方式展现当前内容块的反向链接

↩

### 提及

提及使用当前文档中内容块名称和别名作为关键字进行搜索，搜索结果为包含这些关键字的内容块。可以通过链接按钮将提及转换为链接：提及处会使用 ((id "内容块名称")) 进行替换。 ↩

# 5 嵌入内容块

概述

嵌入内容块主要用于汇总所需内容块，通过 将 SQL 脚本包裹起来并独占一行：，数据库表请参考”这里”²²。#内容块/嵌入#

示例

• 查询内容中包含 内容块 的列表项：

  1
    
  

• 查询内容中同时包含 内容块 和 引用 段落块：

  1
    
  

• 查询内容中同时包含 内容块 和 嵌入 的标题块并按更新时间降序结果取前 2 条：

  1
    
  

案例一

查询同时包含 在思源中 和 核心概念 文本的段落块，并排除当前文档（否则当段落块也会包含到结果集中，因为当前段落同样包含了这两个文本，下面的案例类似）：

查询同时包含 在思源中 和 核心概念 文本的段落块，并排除当前文档（否则当段落块也会包含到结果集中，因为当前段落同样包含了这两个文本，下面的案例类似）：

在思源中，唯一重要的核心概念是((20200813004931-q4cu8na “内容块”))。通过排版格式即可形成内容块，这样我们就能在块级粒度上对思绪和知识进行整理，同时也能方便长文阅读和输出。

案例二

查询同时包含标签 #内容块/嵌入# 和 #内容块/引用# 的段落块：

嵌入内容块主要用于汇总所需内容块，通过 将 SQL 脚本包裹起来并独占一行：，数据库表请参考((20201117103851-l9cahuc “这里”))。#内容块/嵌入#

查询同时包含标签 #内容块/嵌入# 和 #内容块/引用# 的段落块：

内容块引用的完整语法是： ((id "text"))，其中 id 形如： 202008250000-a1b2c3d，由时间和 7 位随机字符组成，内容块 id 是在创建内容块时就会自动生成的；后面的 text 是在引用处对该内容块的自定义锚文本。建立好内容块引用后，鼠标悬浮在锚文本上后将弹出预览浮层，展现被引用的内容块。#内容块/引用#

案例三

有时候我们可能需要随机漫游显示内容块，以方便回顾。

querySpans：该函数用于查询数据库，返回值为 spans 列表，参数为 SQL 语句：.action{sql "SELECT * FROM spans LIMIT 7"}

• 动态加载，解决大文档卡顿

• https://github.com/gin-contrib/cors MIT License

案例四

查询未完成的任务列表项，这里需要使用 markdown 字段而不是 content 字段：

• 待办二

• 预约牙医

↩

# 在浏览器上使用

浏览器用法

思源桌面端是基于 Electron 打包的独立应用，但这并不唯一的使用方式。只要启动思源内核后，就能在浏览器上直接使用了，支持移动端浏览器。

• 桌面端网页版：使用体验几乎和 Electron 独立应用一致
• 移动端网页版：为移动端使用体验设计

访问 http://127.0.0.1:6806/ 后会自动根据浏览器版本切换桌面端或移动端。

如果需要在局域网内使用，将 127.0.0.1 换成局域网 IP 地址即可。除了本地局域网使用，这里提供两个自助方案实现公网使用：

• 通过“内网穿透”技术将本地内核服务发布在公网上（较为麻烦且不稳定，不推荐）
• 自行搭建思源服务端（推荐）

在着手前，请从了解思源笔记技术架构开始。

访问鉴权

在 设置 - 关于 中可配置浏览器访问鉴权密码，留空表示不启用鉴权。这在开放网络（比如办公场所和公网）会比较有用，只有鉴权通过后才能进入工作空间。 ↩ ↩²

# 模板片段

概述

模板片段用于在光标插入符位置快速插入之前设置好的文本内容，支持变量。模板片段使用 .md 后缀文件，存放在工作空间 data/templates 文件夹下。

目前请使用其他文本编辑器编写模板，后续思源将支持内置编辑。#TODO#

编写模板

模板使用的是 Go 编程语言的文本模板进行实现，如果你对此有了解的话，可以实现一些程序逻辑在里面，比如比较逻辑、迭代逻辑等。另外，为了避免语法冲突，模板语法使用 .action{action}（而不是 ``）。

我们通过开源项目 Sprig 内置了一些变量和函数来丰富模板。比如可通过 .action{now | date "2006-01-02 15:04:05​"} 来渲染当前时间，更多用法请参考 Sprig 帮助文档。

关于日期时间格式化有个细节需要#注意#：Go 编程语言的格式化比较特殊：不是使用 yyyy-MM-dd HH:mm:ss，而是使用 2006-01-02 15:04:05 这个固定时间格式（知乎讨论）。

除了 Sprig 内置的变量和函数，还支持如下变量和函数：

• title：该变量用于插入当前文档名。比如模板内容为 # .action{.title}，则调用后会以一级标题语法插入到当前文档内容中
• id：该变量用于插入当前文档 ID
• queryBlocks：该函数用于查询数据库，返回值为 blocks 列表，参数为 SQL 语句：.action{sql "SELECT * FROM blocks LIMIT 7"}
• querySpans：该函数用于查询数据库，返回值为 spans 列表，参数为 SQL 语句：.action{sql "SELECT * FROM spans LIMIT 7"}

queryBlocks 和 querySpans 支持类似 SQL 预编译语句的变参列表，方便传入参数：

1
2
.action{$today := now | date "20060102150405"}
.action{$blocks :=queryBlocks "SELECT * FROM blocks WHERE content LIKE '?' AND updated > '?' LIMIT ?" "%foo%" $today "3"}

调用模板

在光标插入符位置，通过 / 选择模板来触发模板搜索，找到需要插入的模板后回车即可。

一个示例

1
2
3
4
5
6
7
.action{$before := (div (now.Sub (toDate "2006-01-02" "2020-02-19")).Hours 24)}

.action{$after := (div ((toDate "2006-01-02" "2048-02-19").Sub now).Hours 24)}
今天是 `.action{now | date "2006-01-02"}`。

* 距离 `2020-02-19` 已经过去 `.action{$before}` 天
* 距离 `2048-02-19` 还剩 `.action{$after}` 天

$before 和 $after 定义了两个变量，分别记录当前日期距离 2020 年和 2048 年的天数。

上架模板集市

上架前请确认你的模板仓库根路径下至少包含这两个文件（仓库示例）：

• template.json（请确保 JSON 格式正确）
• preview.png（请压缩图片大小在 128 KB 以内）

确认无误以后请通过对社区集市仓库发起 pull request，修改 templates.json 文件。该文件是所有社区模板仓库的索引，格式为：

1
2
3
4
5
{
  "repos": [
    "username/reponame@commithash"
  ]
}

其中 commithash 请填写你的模板仓库上最近一次发布版本的 Git 提交哈希值，请使用完整哈希值，不要使用 7 位短值。

更新

如果你开发的模板更新了版本，请记得：

• 更新你的模板配置 template.json 中的 version 字段
• 再次对社区集市发起 Pull Request

↩

# 编辑历史

• 每隔 10 分钟会对这 10 分钟内更新过的文件生成历史。间隔时间可通过 设置 - 编辑器 - 生成历史间隔 进行调整
• 删除文档时每次都会生成历史。可通过 设置-文档树-删除文档时生成历史 打开或关闭该功能
• 历史数据保存在笔记本 .siyuan/history/ 文件夹下

浏览历史

在笔记本上右键菜单中选择历史，目前仅支持浏览最新的 32 次历史。

回滚

在历史界面左侧时间列表栏中，每一条历史记录后面都有一个回滚按钮，点击以后将弹出确认对话框，如果确认回滚的话将使用历史数据覆盖现有数据。 ↩

# 幻灯片演示

• 使用分隔线 --- 对文档进行分隔，分隔后的每一部分将作为幻灯片的一页
• 通过在文档树上右键文档下拉菜单打开幻灯片演示

↩

# 1 数据同步

概述

数据同步指的是在多个设备上保持 工作空间/data/ 文件夹数据一致，包括资源文件、模板、挂件以及笔记本数据。

使用方式

1. 打开 设置 - 云端，配置 端到端加密密码，该密码需要在所有设备上配置一次
2. 在 设置 - 云端 - 同步 中创建云端同步目录
3. 选择一个云端同步目录，选择以后该云端同步目录将用于当前工作空间数据同步，选定以后请勿随意切换，否则数据会被覆盖
4. 启用同步开关 设置 - 云端 - 同步 - 启用
5. 等待 1 分钟左右后同步就会开始工作（或者点击 立即同步）

以上操作请先在主力设备上进行，然后在其他设备上选择相同的云端同步目录，并打开同步开关即可。如果要切换、重命名或者删除云端同步目录，请先在所有设备上关闭同步开关后再操作。

忽略文件

如果需要在同步时忽略一些文件，请在文件系统上创建或编辑文本文件 ` 工作空间/data/.siyuan/syncignore`， 其中每一行使用 data 文件夹的相对路径进行配置，表示忽略文件或文件夹的路径，支持通配符。例如：

• 20210808180117-6v0mkxr/**/*： 忽略 data/20210808180117-6v0mkxr 文件夹及其包含的所有文件
• assets/*.pdf：忽略 data/assets/ 下的 PDF 文件
• **/foo/*.png：忽略任意层级下 foo/ 下的 PNG 文件
• foo/ba*.png：忽略 data/foo/ 下以 ba 开头的 PNG 文件

工作原理

每隔一段时间（取决于 设置 - 云端 - 同步 - 间隔），思源会自动比较一次云端和本地数据版本，根据版本进行相应操作：

• 如果版本相等则略过
• 如果云端版本大于本地版本，则将云端数据下载到本地并解密到 工作空间/data/ 文件夹下，本地被覆盖或者删除的文件会移动到 工作空间/.siyuan/history/ 文件夹下
• 如果云端版本小于本地，则扫描 /工作空间/data/ 变更，然后将变更加密复制到 工作空间/sync/ 文件夹下，最后进行上传并覆盖云端数据

#注意#

• 在不改变密码的情况下，数据是进行增量传输的
• 重命名或删除云端目录前，请在所有设备上关闭同步后再修改或删除
• 请勿同时使用第三方同步盘和思源同步，可能会导致数据损坏
• 符号链接不会被同步

↩

# 内核 API

请浏览 API 文档。 ↩

## 内容块元类型

内容块在逻辑上分为叶子块和容器块，叶子块不能包含其他块，容器块可以包含其他块：

• 列表块：只能包含列表项块
• 列表项块：可以包含任意非文档块
• 引述块：可以包含任意非文档块
• 超级块：可以包含任意非文档块
• 文档块：可以包含任意非文档块

↩ ↩² ↩³ ↩⁴ ↩⁵ ↩⁶ ↩⁷ ↩⁸

## 关系图

关系图分为文档级和全局。文档的关系图是以当前文档块展开，并呈现所有和该文档有关联的（正向链接和反向链接）内容块；全局关系图是所有笔记本中所有的块和链接关系。

按住 Ctrl 单击节点：跳转到该节点。 ↩

## 反向链接

反向链接是文档级的，列出当前文档中内容块被引用和被提及所在的块。

链接

• 鼠标悬浮引用块前面的标识会弹出预览浮窗
• 单击反链列表中的引用块进行跳转

提及

提及使用当前文档中内容块名称和别名作为关键字进行搜索，搜索结果为包含这些关键字的内容块。可以通过链接按钮将提及转换为链接：提及处会使用 ((id "内容块名称")) 进行替换。 ↩

## blocks 表

该表用于存储内容块数据。

↩