动态交互文档变得更加简便。

介绍

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 文件可能具有 frontmatter 头（使用 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）。

文档

目前只有这个 README 和 examples/ 目录中的一些示例。

路线图

这个项目主要是一个概念验证。目前尚未计划（但未来可能会）。我可能不会积极开发它，但至少可以保证会解决问题并讨论功能请求（也许会实施？）。

以下是我脑海中可能不错的一些想法：

• 使网站布局可定制： 目前，我只是使用 Bulma (opens new window) 生成一个页面作为 CSS 框架，一切都与其紧密耦合（对于 PoC 来说很好，但对于成品来说并不理想）。
• 缓存 Markdown 渲染： 每次调用都会从头重新渲染所有内容。这对性能可能不是最佳选择。

欢迎任何其他想法和拉取请求！请查看 CONTRIBUTING (opens new window) 文件。

许可证

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