README

此插件扩展了 Kirby 3 和 4，添加了一些基本、极简单且无偏见的脚注功能。

概述

此插件完全免费，并按照 MIT 许可证发布。然而，如果您将其用于商业项目并希望帮助我进行维护，请考虑进行自愿捐赠。

• 1. 安装
• 2. 基本用法
• 3. 高级用法
  • 3.1. 从多个字段收集笔记
  • 3.2. 与块一起使用
• 4. 前端定制
• 5. 选项
• 6. 方法
• 7. 许可证
• 8. 致谢

1. 安装

将此存储库下载并复制到 /site/plugins/footnotes

或者，您可以使用 composer 安装它：composer require sylvainjule/footnotes

2. 基本用法

在您的字段上使用脚注方法：$page->text()->footnotes() 或 $page->text()->ft()（无需在前后调用 ->kirbytext()，此方法会处理它）。

在您的 Kirbytext 字段中添加脚注很简单。只需在您的帖子中按如下方式内联键入它们

[^This is a footnote.]
[^ This is another.]

每个脚注都必须以一个撇号（^）开头，并将自动编号。脚注可以包含您想要的内容，包括链接或图片，但请注意，您不应在脚注内包含未转义的方括号 []。

如果您在笔记中添加方括号（例如，This is a truncated [...] quote），则必须转义属于笔记的闭合括号

[^ This is a truncated […\] quote]

例如，使用默认设置，此文本

This is a footnote.[^Right here!] Here is a test with a footnote that contains a link.[^ Yes, there is indeed (link: https://getkirby.com text: a link.)] And, well, just to be sure things are working I'm throwing a third footnote in here.[^ All good!]

将输出

3. 高级用法

3.1. 从多个字段收集笔记

如果您想在您的页面上收集来自多个字段的脚注，您可以在页面的末尾输出单个容器，而不是使用 footnotes() 方法，您可以使用 collectFootnotes() 方法。

此方法将返回带有脚注引用的文本，没有脚注容器，并将存储脚注容器以供以后使用。

例如

// somewhere in your template
echo $page->text1()->collectFootnotes();

// somewhere else in your template
echo $page->text2()->collectFootnotes();

// at the end of your template,
// echo the footnotes container with all collected footnotes
echo Footnotes::footnotes();

3.2. 与块一起使用

插件提供 collectFootnotes() 块方法，旨在收集在转换为块后找到的所有脚注（您需要在 toBlocks() 方法之后将其链接）。

// collect the footnotes and return the html with footnotes references
echo $page->blocks->toBlocks()->collectFootnotes();

// at the end of your template,
// echo the footnotes container with all collected footnotes
echo Footnotes::footnotes();

4. 前端定制

如上所示，插件完全无偏见。它不附带任何 CSS 或 JS 代码，但提供了调整其样式的标记以适应您的网站的标记。

以下是输出标记和类的参考，以便进行样式设置

<p>
    This is a footnote.<sup class="footnote"><a id="fnref-1" href="#fn-1">1</a></sup> Here is a test with a footnote that contains a link.<sup class="footnote"><a id="fnref-2" href="#fn-2">2</a></sup> And, well, just to be sure things are working I'm throwing a third footnote in here.<sup class="footnote"><a id="fnref-3" href="#fn-3">3</a></sup>
</p>
<div id="footnotes" class="footnotes-container">
    <ol class="footnotes-list">
        <li id="fn-1" value="1">
            Right here! <span class="footnotereverse"><a href="#fnref-1">↩</a></span>
        </li>
        <li id="fn-2" value="2">
            Yes, there is indeed <a href="https://getkirby.com">a link.</a><span class="footnotereverse"><a href="#fnref-2">↩</a></span>
        </li>
        <li id="fn-3" value="3">
            All good! <span class="footnotereverse"><a href="#fnref-3">↩</a></span>
        </li>
    </ol>
</div>

在您的样式表中

sup.footnote {}         /* Footnote reference within text */
.footnotes-container {} /* Footnotes container */
.footnotes-list {}      /* Footnotes ordered list */
.footnotes-list li {}   /* Footnote entry */
.footnotereverse {}     /* Footnote back link ↩ */

5. 选项

有一些选项

5.1. 包装器

出于语义目的，您可以手动设置用作脚注容器的 HTML 标签，例如 aside、footer 等。（默认是简单的 div）

'sylvainjule.footnotes.wrapper'  => 'div'

5.2. 返回

显示在脚注末尾的字符串，链接到文本中的引用。默认为 ↩ / ↩。

'sylvainjule.footnotes.back'  => '↩'

如果您不想显示任何返回链接，将该值设置为 false。

5.3. 链接

如果您不想脚注引用和脚注成为链接，例如，如果您将它们作为边注而不是脚注显示，请将此设置为false。默认值为true。

'sylvainjule.footnotes.links'  => false

如果设置为false，则不会将脚注的返回链接添加到脚注中，并且文本中脚注引用的语法会改变

<!-- from -->
<sup class="footnote">
    <a id="fnref-1" href="#fn-1">1</a>
</sup>

<!-- to -->
<sup id="fnref-1" class="footnote" data-ref="#fn-1">1</sup>

6. 方法

// returns the text with footnotes references and a bottom footnote container
echo $page->text()->footnotes();

// returns the text without footnotes references nor bottom footnotes container
echo $page->text()->removeFootnotes();

// returns the text with footnotes references but no bottom footnotes container
echo $page->text()->withoutFootnotes();

// returns only the footnotes container
echo $page->text()->onlyFootnotes();

// returns the text with footnotes references, no footnotes container, but stores the footnotes container for later use
echo $page->text1()->collectFootnotes();
echo $page->text2()->collectFootnotes();

// returns the footnotes container with all collected footnotes and clears the memory
echo Footnotes::footnotes();

7. 许可证

麻省理工学院（MIT）

8. 致谢

此插件是在@distantnative的K2版本基础上构建的。🙏