动态交互文档更加简便。

DocEaser是一个非常简单的框架，用于呈现Markdown文档。其独特之处在于这些文档可以嵌入使用Python编写的HTMX组件，为您的文档增加交互性。

安装

$ pip install git+https://github.com/linkdd/doceaser

使用

运行服务器

为您的内容创建一个文件夹：

$ mkdir content/
$ mkdir content/_static
$ python -m doceaser.cli --root content/
Listening on http://localhost:8080/

该服务器基于可以投入生产使用的WSGI服务器waitress (opens new window)。

组织您的内容

静态文件放在content/_static/目录中，将在/_static/... URL中提供服务：

内容路径

URL

content/_static/screenshot.png

/_static/screenshot.png

HTMX组件放在content/目录中作为Python文件，并将在/_components/... URL中提供服务：

内容路径

URL

content/form.py

/_components/form

content/hello/world.py

/_components/hello/world

Markdown文件放在content/目录中，并将在/... URL中提供服务。特殊文件_index.md可用作索引部分：

内容路径

URL

content/about.md

/about

content/_index.md

/

content/about/_index.md

/about

content/about/legal.md

/about/legal

编写Markdown文件

Markdown文件可以具有前置标头（使用YAML、TOML或JSON）：

---
title: Hello world
---

# Hello World

title属性将用于<title/> HTML标记。

要嵌入HTMX组件，您可以使用此特殊语法（扩展自CommonMark (opens new window)规范）：

{< htmx:form >}

{< htmx:hello/world >}

这将呈现为以下HTML（带有一些额外的不相关细节）：

<div hx-get="/_components/form" hx-trigger="load"></div>

<div hx-get="/_components/hello/world" hx-trigger="load"></div>

编写HTMX组件

HTMX组件是content/目录中的Python文件。该文件可以实现一个用于处理请求的每个HTTP方法的函数。该函数接受一个werkzeug (opens new window) Request并返回一个_werkzeug_ Response：

from werkzeug.wrappers import Request, Response
from http import HTTPStatus

from lxml.html.builder import E as e
from lxml import html

import requests


def get(request):
    r = requests.get("https://httpbin.org/anything")
    body = e.pre(e.code(r.text))

    return Response(
        html.tostring(body),
        status=HTTPStatus.OK,
        content_type="text/html; charset=utf-8",
    )

注：

• 您可以使用任何您喜欢的方法来呈现HTML。在内部，DocEaser使用lxml，因此您也可以使用它。但这不是强制的。
• 您可能希望安装任何额外的Python依赖项（如上面示例中的requests）。

许可证

此软件根据MIT许可证 (opens new window)条款发布。