README

为 league/commonmark 提供的扩展，用于渲染 Obsidian 专有的元素。

要求

PHP 8.0.2+

安装

如果您想全局安装此库以使用它提供的转换脚本

composer global require elazar/league-commonmark-obsidian

如果您想在本地的代码库中本地安装此库

composer require elazar/league-commonmark-obsidian

使用方法

有三种方法可以使用此库。

转换脚本

转换脚本只需一个命令即可运行，但提供了一种非常基础的转换，没有自定义选项。它主要用作使用转换器的最小示例（请参见下一节），但可以像这样调用

composer global exec obsidian-to-html /path/to/vault /path/to/vault/Attachments /path/to/build

/path/to/vault 是要转换为 HTML 的 Obsidian 保险库根目录的路径
/path/to/vault/Attachments 是包含附件的 Obsidian 保险库子目录的路径
/path/to/build 是接收转换后的 HTML 的目录的路径

扩展

如果您想在您的代码中使用此扩展，可以按照以下方式操作。

$extension = new Elazar\LeagueCommonMarkObsidian\LeagueCommonMarkObsidianExtension(
    vaultPath: '/path/to/Vault',
    attachmentsPath: '/path/to/Vault/Attachments',
);

$environment = new League\CommonMark\Environment\Environment;
$environment->addExtension(new League\CommonMark\Extension\CommonMark\CommonMarkCoreExtension);
$environment->addExtension($extension);

$converter = new League\CommonMark\MarkdownConverter($environment);

// Set the absolute path of the file being converted so that
// links can be resolved relative to that file
$extension->setFromPath('/path/to/Vault/Folder/File.md');

echo $converter->convert('[[Internal Link]]');
// Assuming that "Internal Link.md" is contained in the root
// directory of the vault, the above line outputs:
// <a href="../Internal Link.html">Internal Link</a>

echo $converter->convert('![[Attachment.pdf]]');
// Assuming that "Attachment.pdf" is contained in the "Attachments"
// subdirectory within the vault directory, the above line
// outputs: <img src="../Attachments/Attachment.pdf" />

转换器

转换器是一个单类，可以在您的转换脚本或其他代码中使用。它需要编写一些 PHP 代码才能使用，但比库存转换脚本提供了更多自定义选项，例如在环境配置中包含更多扩展或格式化转换后的 HTML。

以下是一个示例，它添加了 Strikethrough 扩展和一个自定义格式化器，它将转换后的 HTML 包裹在额外的标记中。

$vaultPath = '/path/to/vault';
$attachmentsPath = $vaultPath. '/Attachments';
$buildPath = __DIR__ . '/build';

$formatter = new class implements Elazar\LeagueCommonMarkObsidian\Formatter\FormatterInterface {
    public function format(string $html, string $markdownFilePath): string {
        $title = str_replace('.md', '', basename($markdownFilePath));
        return <<<HTML
<!DOCTYPE html>
<html>
<head>
<title>$title</title>
</head>
<body>
<main>
$html
</main>
</body>
</html>
HTML;
    }
};

$extension = new Elazar\LeagueCommonMarkObsidian\LeagueCommonMarkObsidianExtension(
    $vaultPath,
    $attachmentsPath,
);

$environment = new League\CommonMark\Environment\Environment([]);
$environment->addExtension(new League\CommonMark\Extension\CommonMark\CommonMarkCoreExtension);
$environment->addExtension(new League\CommonMark\Extension\Strikethrough\StrikethroughExtension);
$environment->addExtension($extension);

$converter = new Elazar\LeagueCommonMarkObsidian\Converter;
$converter->convert($vaultPath, $attachmentsPath, $buildPath, $environment, $formatter);

内部结构

在某些情况下，了解此库的内部结构可能会有所帮助。

以下是一些示例用例

如果您想为此库做出贡献，了解您可能需要修改代码库的哪些部分来实现特定功能或修复特定错误会有所帮助。
如果您在此库中发现错误并想绕过它，可能可以通过覆盖库的特定组件来实现。
如果 Obsidian 添加了对新的附件文件类型的支持，并且您想在将其添加到库的核心之前为该库添加对此类型支持，您可能可以通过添加它使用的嵌入渲染器来实现。

扩展

LeagueCommonMarkObsidianExtension 的正常用例是它接收保险库路径和附件路径。如果没有这些，它可以接收本文件后续部分中详细说明的其他依赖项。

该扩展的主要功能是在环境中添加两个内联解析器：用于内部链接的InternalLinkParser，以及用于嵌入的EmbedParser。

内部链接解析器渲染一个原生支持的链接元素。嵌入解析器使用它自己的渲染器来渲染自定义的内联HTML元素，因为这些元素中至少有一部分不是由CommonMark原生支持的。

嵌入渲染器

EmbedRendererInterface 的 $embedRenderer 参数用于 LeagueCommonMarkObsidianExtension 渲染嵌入。

$embedRenderer 的默认值是一个 EmbedRenderer 的实例，它扩展了 CompositeEmbedRenderer 并组合了该库中包含的所有其他渲染器。它尝试依次使用这些渲染器来渲染给定的嵌入。

附件链接解析器

LinkResolverInterface 的 $attachmentLinkResolver 参数用于 LeagueCommonMarkObsidianExtension 解析嵌入的附件链接。

$attachmentLinkResolver 的默认值是一个 AttachmentLinkResolver 的实例，它使用库和附件路径解析相对于正在渲染为HTML的Markdown文件的附件链接和嵌入。

内部链接解析器

LinkResolverInterface 的 $internalLinkResolver 参数用于 LeagueCommonMarkObsidianExtension 解析内部链接。

$internalLinkResolver 的默认值是一个 InternalLinkResolver 的实例，它使用库路径解析相对于正在渲染为HTML的Markdown文件的内部链接。

贡献

无论您想如何贡献，请首先提交一个问题。

问题

请使用以下之一作为问题标题的前缀

错误报告（如果您发现认为是错误的行为）
功能请求（如果您想建议添加或更改库的功能）
帮助请求（对于您不确定的所有内容）

这样做可以与维护者进行讨论，以排除故障、确认错误或确定如何最好地实现建议的功能。

在您希望贡献代码的情况下，这次讨论可能有助于明确您的实现方法，并减少您在合并贡献时可能需要进行的潜在返工。

一旦问题得到解决，或者问题在30天内没有活动，帮助请求将被关闭。其他问题将保持开放状态，直到相关PR被合并或维护者正式决定不再采取进一步行动。

拉取请求（Pull Requests）

一旦在错误或功能实现方法上达成共识，请使用以bug/或feature/开头命名的分支提交PR，分别用于错误报告或功能请求。

请确保在PR描述中引用您提交的原始问题，以提供更改的上下文。

elazar / league-commonmark-obsidian

维护者

详细信息