项目技术文档——django-markupfield

1. 安装指南

推荐使用 pip 来安装 django-markupfield。由于该库不需要添加到 INSTALLED_APPS 中，只需确保其位于 PYTHONPATH 上即可。如果需要使用带标题的标记，可以将 markupfield 添加到 INSTALLED_APPS 中，或者将相应的翻译添加到项目的翻译中。

使用以下命令进行安装：

pip install django-markupfield

2. 项目使用说明

django-markupfield 是一个为 Django 定制的 MarkupField 实现。本质上，MarkupField 是一个带有相关标记类型的 TextField。该字段还假设磁盘空间比 CPU 周期更便宜，因此会缓存其渲染后的值。

在模型定义中使用 MarkupField 非常简单。以下是一个示例：

from django.db import models
from markupfield.fields import MarkupField

class Article(models.Model):
    title = models.CharField(max_length=100)
    slug = models.SlugField(max_length=100)
    body = MarkupField()

创建 Article 对象时，可以使用在 MARKUP_FIELD_TYPES 中定义的任何标记类型：

Article.objects.create(title='some article', slug='some-article',
                       body='*fancy*', body_markup_type='markdown')

你可能会注意到，虽然你没有声明 body_markup_type 字段，但 MarkupField 实际上创建了两个额外的字段：body_markup_type 和 _body_rendered。这些字段始终根据声明的 MarkupField 的名称命名。

3. 项目API使用文档

MarkupField 接受几个参数，其中 default_markup_type 和 markup_type 参数可以指定，但不能同时指定。

• default_markup_type：设置字段默认使用的标记类型。即使这样，仍然可以编辑标记类型属性，它将默认显示在 ModelForms 中。
• markup_type：设置字段将始终使用的标记类型，editable=False 将设置在隐藏字段上，因此它不会在 ModelForms 中显示。
• markup_choices：用于替代 MARKUP_FIELD_TYPES 的替换列表，基于每个字段的基础。
• escape_html：一个标志（默认为 False），表示输入应被视为不可信，并且将通过 Django 的 escape 过滤器运行。

以下是一些使用示例：

• 默认使用 markdown，但允许用户选择：

  MarkupField(default_markup_type='markdown')
  

• 使用 ReST 并在表单上不提供选择：

  MarkupField(markup_type='restructuredtext')
  

• 使用自定义渲染器集：

  CUSTOM_RENDERERS = (
      ('markdown', markdown.markdown),
      ('wiki', my_wiki_render_func)
  )
  MarkupField(markup_choices=CUSTOM_RENDERERS)
  

请注意，在使用 markdown 时，确保使用 markdown.markdown 而不是 markdown.Markdown 类，因为类在某些情况下需要一个明确的 reset 才能正确运行。

4. 项目安装方式

项目安装方式与安装指南相同，使用 pip 命令即可完成安装：

pip install django-markupfield