Obsidian Export

Obsidian Export 是一个 CLI 程序和 Rust 库，用于将 Obsidian 保险库导出为常规 Markdown。

• 递归导出 Obsidian Markdown 文件到 CommonMark。
• 支持 [[note]] 风格的引用以及 ![[note]] 文件包含。
• 支持 gitignore 风格的排除模式（默认：.export-ignore）。
• 当保险库位于 Git 仓库中时，自动排除 Git 忽略的文件。
• 在所有主流平台上运行：Windows、Mac、Linux、BSDs。

请注意，obsidian-export 并非官方得到 Obsidian 团队的认可。它支持大多数但并非所有 Obsidian 的 Markdown 风味。

安装

预构建的二进制文件

所有主流平台都提供了预编译的二进制文件，可在 https://github.com/zoni/obsidian-export/releases 获取

除了提供的安装脚本外，这些发布版本也适用于 使用 cargo-binstall 安装。

从源码构建

当您的平台不可用二进制发布版，或者您不信任预构建的二进制文件时，可以使用 obsidian-export 从源码编译，相对容易。这通过 Cargo，Rust 的官方包管理器，以下步骤完成：

1. 从 https://rust-lang.net.cn/tools/install 安装 Rust 工具链
2. 运行： cargo install obsidian-export

预计您在安装Rust工具链时已正确配置了PATH变量，具体请参考https://rust-lang.net.cn/tools/install上的《配置PATH环境变量》。

从早期版本升级

如果您下载了预构建的二进制文件，请下载最新版本以替换旧版本。

如果您是从源代码构建的，请再次运行cargo install obsidian-export进行升级。

基本用法

obsidian-export的主要界面是obsidian-export CLI命令。作为一个文本界面，必须在终端或Windows PowerShell中运行。

假设您对命令行界面有基本的了解，并且如果您使用cargo安装，您已正确设置了PATH。运行obsidian-export --version应该打印出一个版本号，而不是某种错误。

如果您下载了预构建的二进制文件，并且没有将其放在PATH引用的位置（例如，您将其放在Downloads中），则需要提供二进制的完整路径。

例如，在Mac/Linux上为~/Downloads/obsidian-export --version，在Windows（PowerShell）上为~\Downloads\obsidian-export --version。

导出笔记

在它的最基本形式中，obsidian-export只需要两个强制性的参数，源和目标

obsidian-export /path/to/my-obsidian-vault /path/to/exported-notes/

这将把my-obsidian-vault中的所有文件导出到exported-notes，除了那些在.export-ignore或.gitignore中列出的。

请注意，目标目录必须存在，因此您可能需要首先创建一个新空目录。

如果您提供了一个已存在的目录，该目录下的文件可能会被覆盖。

也可以导出单个文件

# Export as some-note.md to /tmp/export/
obsidian-export my-obsidian-vault/some-note.md /tmp/export/
# Export as exported-note.md in /tmp/
obsidian-export my-obsidian-vault/some-note.md /tmp/exported-note.md

请注意，在这个模式下，obsidian-export将some-note.md视为您的保险库中存在的唯一文件，因此其他笔记的引用将不会解决。这是按设计如此。

如果您想在解决对保险库中其他区域的链接或嵌入时导出单个笔记，那么您应该指定保险库的根目录作为源，并通过--start-at传递您想要导出的文件，如下一节所述。

导出部分保险库

使用--start-at参数，您可以仅导出保险库的一部分。给定以下保险库结构

my-obsidian-vault
├── Notes/
├── Books/
└── People/

这将仅将Books目录中的笔记导出到exported-notes。

obsidian-export my-obsidian-vault --start-at my-obsidian-vault/Books exported-notes

在这个模式下，所有在源（第一个参数）下的笔记都被视为保险库的一部分，因此这些文件的所有引用都将保持完整，即使它们不是导出的笔记。

字符编码

目前，所有笔记文本以及文件名都假定使用UTF-8字符编码。所有文本和文件处理都执行有损转换为Unicode字符串。

使用非UTF-8编码可能会导致文本替换错误和无法找到链接笔记等问题。虽然这可能在将来改变，但短期内没有计划更改这种行为。

高级用法

前端元数据

默认情况下，前端元数据“原样”复制。

一些静态网站生成器对前端元数据比较挑剔，需要它存在。有些在Markdown文件没有前端元数据但以列表项或水平线开始时会出错。在这些情况下，可以使用--frontmatter=always来插入一个空的元数据条目。

要完全从导出的笔记中删除任何前端元数据，请使用--frontmatter=never。

忽略文件

以下文件默认不导出

• 隐藏文件（可以使用--hidden调整）
• 匹配.export-ignore中列出的模式的文件（可以使用--ignore-file调整）
• 被git忽略的任何文件（可以使用--no-git调整）
• 使用--skip-tags foo --skip-tags bar将跳过任何其前端元数据中有标签foo或bar的文件
• 使用--only-tags foo --only-tags bar将跳过任何其前端元数据中没有标签foo或bar的文件

（有关更多信息，请参阅--help）。

链接到忽略笔记的笔记将被取消链接（它们只包含链接文本）。忽略笔记的嵌入将被完全跳过。

忽略文件语法

.export-ignore文件的语法与gitignore文件相同。以下是一个示例

# Ignore the directory private that is located at the top of the export tree
/private
# Ignore any file or directory called `test`
test
# Ignore any PDF file
*.pdf
# ..but include special.pdf
!special.pdf

有关更全面的文档和示例，请参阅gitignore手册页。

递归嵌入

当两个笔记互相嵌入时，可能会出现“递归嵌入”。例如，当Note A.md包含![[Note B]]但Note B.md也包含![[Note A]]时，就会发生这种情况。

默认情况下，这将触发错误并显示导致递归的笔记链。

可以通过指定--no-recursive-embeds来更改此行为。使用此模式，如果在处理原始笔记时再次遇到笔记，则插入到笔记中的链接而不是再次嵌入它，以打破循环。

与Hugo的相对链接

Hugo静态网站生成器不支持对文件的相对链接。相反，它期望您使用ref和relref简码链接到其他页面。

因此，使用obsidian-export从Obsidian导出的笔记默认情况下无法正常工作，因为Hugo无法正确解析这些链接。

Markdown 渲染钩子（仅支持使用默认的 goldmark 渲染器）允许您绕过此问题，经过一些一次性设置后，使导出的笔记与 Hugo 一起工作。

创建文件 layouts/_default/_markup/render-link.html，内容如下：

{{- $url := urls.Parse .Destination -}}
{{- $scheme := $url.Scheme -}}

<a href="
  {{- if eq $scheme "" -}}
    {{- if strings.HasSuffix $url.Path ".md" -}}
      {{- relref .Page .Destination | safeURL -}}
    {{- else -}}
      {{- .Destination | safeURL -}}
    {{- end -}}
  {{- else -}}
    {{- .Destination | safeURL -}}
  {{- end -}}"
  {{- with .Title }} title="{{ . | safeHTML }}"{{- end -}}>
  {{- .Text | safeHTML -}}
</a>

{{- /* whitespace stripped here to avoid trailing newline in rendered result caused by file EOL */ -}}

以及 layouts/_default/_markup/render-image.html 用于图片。

{{- $url := urls.Parse .Destination -}}
{{- $scheme := $url.Scheme -}}

<img src="
  {{- if eq $scheme "" -}}
    {{- if strings.HasSuffix $url.Path ".md" -}}
      {{- relref .Page .Destination | safeURL -}}
    {{- else -}}
      {{- printf "/%s%s" .Page.File.Dir .Destination | safeURL -}}
    {{- end -}}
  {{- else -}}
    {{- .Destination | safeURL -}}
  {{- end -}}"
  {{- with .Title }} title="{{ . | safeHTML }}"{{- end -}}
  {{- with .Text }} alt="{{ . | safeHTML }}"
  {{- end -}}
/>

{{- /* whitespace stripped here to avoid trailing newline in rendered result caused by file EOL */ -}}

安装了这些钩子后，笔记和文件附件的链接现在应该可以正确工作。

注意：如果您使用的是带有自身渲染钩子的主题，您可能需要做一些额外的工作，或者自定义上面的片段，以避免与主题的钩子冲突。

库使用

obsidian-export CLI 命令公开的所有功能也可以通过 obsidian_export crate 作为 Rust 库访问。

要开始，请访问 obsidian_export 和 obsidian_export::Exporter 的库文档。

贡献

只要与项目的整体范围和愿景一致，我将很高兴接受错误修复和增强。有关更多信息，请参阅 CONTRIBUTING。

许可

Obsidian-export 是在 BSD-2-Clause Plus Patent License 下发布的开源软件。此许可证旨在提供：a）一个简单的许可协议；b）与 GNU 通用公共许可证（GPL）版本 2 兼容；c）还包括一个明确的专利授予。

请查阅 LICENSE 文件以获取许可证的完整文本。

变更日志

有关每个版本的发布列表和更改，请参阅 CHANGELOG。