Obsidian 导出

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

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

请注意，obsidian-export 并非官方认可由 Obsidian 团队支持。它支持大部分但并非全部的 Obsidian Markdown 风格。

安装

预构建的二进制文件

为 Windows、Linux 和 Mac 操作系统提供针对 x86-64 处理器的二进制发布。它们作为在 .github/workflows/release.yml 中定义的发布工作流程的一部分使用 GitHub 运行者构建。

生成的二进制文件可以从 https://github.com/zoni/obsidian-export/releases 下载。

从源代码构建

当您的平台没有提供二进制发布，或者您不信任预构建的二进制文件时，可以通过以下步骤使用 obsidian-export 进行源代码编译，相对较为简单。这是通过 Rust 的官方包管理器 Cargo 完成的。

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字符串。

使用非UTF8编码可能导致文本替换错误和无法找到链接笔记等问题。尽管未来可能会有所改变，但短期内没有计划更改此行为。

高级用法

前导内容

默认情况下，前导内容将“原样”复制。

一些静态网站生成器对前导内容比较挑剔，并要求其存在。有些生成器在Markdown文件没有前导内容但以列表项或水平线开头时会遇到问题。在这些情况下，可以使用--frontmatter=always来插入一个空的前导内容条目。

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

忽略文件

默认情况下，隐藏文件、在.export-ignore中列出的模式以及git忽略的任何文件（如果您的保险库是git仓库的一部分）将不包括在导出中。

如果需要，可以使用--hidden、--ignore-file和--no-git来调整这些选项。（有关更多信息，请参阅--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导出的笔记不能直接使用，因为Hugo无法正确解析这些链接。

Markdown Render Hooks（仅支持默认的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 库的文档。

许可证

Obsidian-export 同时使用 Apache 2.0 和 MIT 许可证。

除非您明确声明，否则根据 Apache-2.0 许可证的定义，您有意提交给本项目的任何贡献都应按上述方式双重许可，不附加任何额外的条款或条件。

变更日志

v21.9.0 (2021-09-12)

此版本切换到 日历版本控制方案。有关此决定的详细信息，请参阅 switching obsidian-export to CalVer。

新增

• 支持在嵌入式笔记上运行后处理器。[Nick Groenen]

  这引入了对在另一个笔记中嵌入的笔记结果上运行的 postprocessor 的支持。这与现有的 postprocessor（保持不变）不同，后者在所有嵌入处理并合并到最终笔记后才运行。

  这些“嵌入后处理器”可以通过新的 Exporter::add_embed_postprocessor 方法设置。

• 添加 start_at 选项以导出部分库。[Nick Groenen]

  这引入了新的 CLI 参数 --start-at 和相应的 start_at() 方法，允许仅导出库中的给定子目录。

  有关何时以及如何使用此功能的详细信息，请参阅更新的 README 文件。