Wagtail Footnotes

为您的Wagtail项目添加脚注功能。

⚡ 快速开始

将 wagtail_footnotes 添加到 INSTALLED_APPS

# settings.py

INSTALLED_APPS = [
    # ...
    "wagtail_footnotes",
    # ...
]

将脚注的 urls.py 添加到您项目的 urls.py

# urls.py
# ...
from wagtail_footnotes import urls as footnotes_urls


urlpatterns = [
    # ...
    path("footnotes/", include(footnotes_urls)),
    # ...
]

注意：URL必须定义为上述内容，因为当前它在JavaScript中是硬编码的。

更新您的页面模型以显示脚注面板

from wagtail.models import Page
from wagtail.admin.panels import InlinePanel


class InformationPage(Page):
    # ...
    content_panels = [
        # ...
        InlinePanel("footnotes", label="Footnotes"),
    ]

创建并运行迁移

python manage.py makemigrations
python manage.py migrate

在页面模板中显示脚注

更新您的页面模板以包含 {% include "wagtail_footnotes/includes/footnotes.html" %}。您可以从此模板复制，然后包含您自己的自定义版本。

在 RichTextField 中使用脚注

更新您想要添加脚注功能的任何 RichTextField。将 "footnotes" 添加到每个想要此功能的 RichTextField 的 features 参数中。例如

class InformationPage(Page):
    body = RichTextField(
        features=[
            "h1",
            "h2",
            "h3",
            "h4",
            "footnotes",  # Make sure this line is part of the features
        ],
    )

查看Wagtail文档 了解您可能想要配置的功能列表，因为我们正在覆盖默认设置。

在 StreamField 中使用脚注

为了在 RichTextBlock 中提供脚注功能，您需要将 RichTextBlock 更改为 wagtail_footnotes.blocks.RichTextBlockWithFootnotes。例如

from wagtail_footnotes.blocks import RichTextBlockWithFootnotes
# ...

class MyPage(Page):
    body = StreamField(
        [
            # ...
            ("paragraph", RichTextBlockWithFootnotes()),  # Using RichTextBlockWithFootnotes
            # ...
        ],
    )

将脚注作为全局默认设置添加

您可能希望所有富文本编辑器都显示脚注。但请记住，为了启用脚注功能，您需要在所有页面模型上添加脚注 InlinePanel。

# settings.py
# ...
WAGTAILADMIN_RICH_TEXT_EDITORS = {
    "default": {
        "WIDGET": "wagtail.admin.rich_text.DraftailRichTextArea",
        "OPTIONS": {"features": ["bold", "italic", "h3", "h4", "ol", "ul", "link", "footnotes"]},
    }
}

⚙️ 设置

• WAGTAIL_FOOTNOTES_TEXT_FEATURES

  • 默认值：["bold", "italic", "link"]
  • 使用此选项更新允许在脚注文本中使用的富文本功能列表。

• WAGTAIL_FOOTNOTES_REFERENCE_TEMPLATE

  • 默认值："wagtail_footnotes/includes/footnote_reference.html"
  • 使用此选项设置一个渲染脚注引用的模板。该模板在其上下文中接收脚注 index。

🌍 国际化

Wagtail Footnotes 可以进行翻译。请注意，在多语言设置中，脚注的URL设置需要在 i18n_patterns() 调用中使用 prefix_default_language=False

# urls.py

urlpatterns += i18n_patterns(
    path("footnotes/", include(footnotes_urls)),
    # ...
    path("", include(wagtail_urls)),
    prefix_default_language=False,
)

或在其外部

# urls.py

urlpattherns += [
    path("footnotes/", include(footnotes_urls)),
]
urlpatterns += i18n_patterns(
    # ...
    path("", include(wagtail_urls)),
)

💡 常见问题

• 我点击编辑器中的 Fn 按钮后它停止工作
  • 这可能是由于JS中的URL与脚注视图的URL不匹配。请检查 wagtail_footnotes/static/footnotes/js/footnotes.js 中的URL是否与您设置的URL匹配。
• 渲染页面时出现 NoneType 错误。
  • 请确保您正在模板中使用 {% include_block page.field_name %} 渲染字段。

贡献

欢迎所有贡献！

安装

要更改此项目，首先克隆此存储库

git clone git@github.com:torchbox/wagtail-footnotes.git
cd wagtail-footnotes

使用您首选的虚拟环境激活后，安装测试依赖项

python -m pip install -e '.[testing]' -U

pre-commit

请注意，此项目使用 pre-commit。要本地设置

# set up your virtual environment of choice
$ python -m pip install pre-commit
# initialize pre-commit
$ pre-commit install
# Optional, run all checks once for this, then the checks will run only on the changed files
$ pre-commit run --all-files

如何运行测试

要运行所有环境中的所有测试

tox

要运行特定环境的测试

tox -e python3.12-django5.0-wagtail6.0

要在特定环境中运行单个测试方法

tox -e python3.12-django5.0-wagtail6.0 -- tests.test.test_blocks.TestBlocks.test_block_with_features