Streamlit中Markdown文本转换为可下载PDF报告的教程

新闻中心 NEWS CENTER

您当前位置：首页 > 新闻中心 > 网络学院

Streamlit中Markdown文本转换为可下载PDF报告的教程

2025-11-25

浏览次数：次

返回列表

Streamlit中Markdown文本转换为可下载PDF报告的教程

介绍如何在streamlit应用中将动态生成的markdown文本转换为可下载的pdf报告。文章详细阐述了通过将markdown首先转换为html，再利用`pdfkit`工具将其渲染为pdf的完整流程，并提供了集成到streamlit下载按钮的示例代码，解决了直接下载markdown导致文件损坏的问题。

在Streamlit应用开发中，有时我们需要将用户界面上展示的Markdown格式文本内容，例如报告、日志或动态生成的信息，提供为可下载的PDF文件。直接将Markdown字符串传递给st.download_button并指定文件类型为PDF，通常会导致生成的PDF文件损坏或无法打开，因为Streamlit的下载按钮只是简单地将字符串作为文件内容写入，而没有进行格式转换。

要正确实现Streamlit中Markdown文本到PDF的转换与下载，我们需要一个多步骤的方法：首先将Markdown转换为HTML，然后将HTML渲染为PDF，最后将生成的PDF文件提供给用户下载。

1. 准备工作：安装必要的库和工具

在开始之前，请确保您的开发环境中已安装以下Python库和外部工具：

Streamlit: 用于构建Web应用。
```
pip install streamlit
```
markdown2: 一个Python库，用于将Markdown文本快速转换为HTML。
```
pip install markdown2
```
pdfkit: 一个Python库，用于将HTML转换为PDF。它依赖于一个外部工具wkhtmltopdf。
```
pip install pdfkit
```
wkhtmltopdf: 一个命令行工具，能够将HTML（包括CSS和J*aScript）渲染成高质量的PDF文件。这是pdfkit正常工作的核心依赖。
- 安装方法:
  - Windows: 从wkhtmltopdf官网下载并安装对应的MSI文件。
  - macOS: 可以通过Homebrew安装：brew install wkhtmltopdf。
  - Linux: 可以通过包管理器安装，例如Debian/Ubuntu：sudo apt-get install wkhtmltopdf。

安装wkhtmltopdf后，请确保其可执行文件路径已添加到系统的PATH环境变量中，或者在代码中明确指定其路径。

2. 将Markdown文本转换为HTML

第一步是将您的Markdown文本转换为HTML格式。markdown2库可以轻松完成此任务。

假设您有以下Markdown文本：

import streamlit as st
import markdown2
import pdfkit
import os

st_md = '''
<b>比较MongoDB与其他NoSQL数据库</b><br><br><b>上传文件: </b>[]<br><br> 以下是MongoDB与一些其他主要NoSQL数据库的比较：

- MongoDB是一个文档数据库。它将数据存储在灵活的类似JSON的文档中，而不是像RDBMS那样存储在行和列中。其他文档数据库包括CouchDB和Amazon DocumentDB。

总而言之，MongoDB在文档存储的灵活性、二级索引和聚合等丰富功能以及通过水平分片实现的可伸缩性之间取得了平衡，这使其成为当今许多NoSQL数据库中的热门选择。<br><br><b>MongoDB与其他NoSQL数据库的优缺点</b><br><br><b>上传文件: </b>[]<br><br> 以下是MongoDB与其他NoSQL数据库相比的一些主要优缺点：

优点：

- 使用文档的灵活数据模型表示具有动态模式的对象。比需要预定义模式的列式数据库更灵活。

- 对任何属性进行索引，实现比键值存储更快的查询和检索。

缺点：

- ACID合规性和事务性低于传统的SQL数据库。

- 没有像SQL那样的声明式查询语言。查询语法对于某些用例可能很复杂。

综上所述，MongoDB提供了一个灵活的文档数据模型，具有丰富的功能，与简单的键值存储相比，可以实现更快的读取和更强的表达能力，但缺少数据库专家可能需要的一些功能。扩展和性能通常比传统的SQL数据库更容易。<br><br>
'''

# 将Markdown转换为HTML
html = markdown2.markdown(st_md)

markdown2.markdown()函数会将Markdown字符串转换为一个HTML字符串，其中包含了适当的HTML标签来渲染Markdown内容。

3. 将HTML转换为PDF文件

接下来，使用pdfkit库将上一步生成的HTML字符串转换为一个PDF文件。

世界教师节竖版广告海报设计下载

世界教师节竖版广告海报设计适用于教师节海报设计本作品提供世界教师节竖版广告海报设计的图片会员免费下载，格式为PSD，文件大小为920KB；请使用软件Photoshop进行编辑，作品中文字及图均可以通过软件修改和编辑；

0 查看详情世界教师节竖版广告海报设计下载

# 配置wkhtmltopdf的路径（如果不在系统PATH中）
# config = pdfkit.configuration(wkhtmltopdf='/usr/local/bin/wkhtmltopdf') # 示例路径

# 将HTML转换为PDF文件
# pdfkit.from_string(html, 'output.pdf', configuration=config) # 如果需要配置路径
pdfkit.from_string(html, 'output.pdf') # 如果wkhtmltopdf在系统PATH中

这会在您的项目目录下生成一个名为output.pdf的PDF文件。

重要提示: 如果wkhtmltopdf不在您的系统PATH中，pdfkit将无法找到它并报错。您需要通过pdfkit.configuration明确指定其完整路径，如注释中所示。

4. 在Streamlit中提供PDF下载

最后一步是将生成的PDF文件通过Streamlit的st.download_button提供给用户下载。为了确保下载正常，需要以二进制读取模式（"rb"）打开PDF文件，并将其内容传递给下载按钮。

# 读取生成的PDF文件内容
with open("output.pdf", "rb") as pdf_file:
    pdf_bytes = pdf_file.read()

# 在Streamlit中创建下载按钮
st.download_button(
    label="下载PDF报告",
    data=pdf_bytes,
    file_name="report.pdf",
    mime="application/pdf"
)

# 清理生成的临时PDF文件
os.remove("output.pdf")

mime="application/pdf"参数是可选的，但建议添加，它告诉浏览器下载的文件类型是PDF，有助于浏览器正确处理文件。

完整示例代码

将上述所有步骤整合到一个Streamlit应用中：

import streamlit as st
import markdown2
import pdfkit
import os

# 示例Markdown文本
st_md = '''
<b>比较MongoDB与其他NoSQL数据库</b><br><br><b>上传文件: </b>[]<br><br> 以下是MongoDB与一些其他主要NoSQL数据库的比较：

- MongoDB是一个文档数据库。它将数据存储在灵活的类似JSON的文档中，而不是像RDBMS那样存储在行和列中。其他文档数据库包括CouchDB和Amazon DocumentDB。

总而言之，MongoDB在文档存储的灵活性、二级索引和聚合等丰富功能以及通过水平分片实现的可伸缩性之间取得了平衡，这使其成为当今许多NoSQL数据库中的热门选择。<br><br><b>MongoDB与其他NoSQL数据库的优缺点</b><br><br><b>上传文件: </b>[]<br><br> 以下是MongoDB与其他NoSQL数据库相比的一些主要优缺点：

优点：

- 使用文档的灵活数据模型表示具有动态模式的对象。比需要预定义模式的列式数据库更灵活。

- 对任何属性进行索引，实现比键值存储更快的查询和检索。

缺点：

- ACID合规性和事务性低于传统的SQL数据库。

- 没有像SQL那样的声明式查询语言。查询语法对于某些用例可能很复杂。

综上所述，MongoDB提供了一个灵活的文档数据模型，具有丰富的功能，与简单的键值存储相比，可以实现更快的读取和更强的表达能力，但缺少数据库专家可能需要的一些功能。扩展和性能通常比传统的SQL数据库更容易。<br><br>
'''

st.title("Markdown文本转PDF下载示例")
st.markdown(st_md, unsafe_allow_html=True) # 在Streamlit中显示Markdown内容

if st.button("生成并下载PDF报告"):
    try:
        # 1. 将Markdown转换为HTML
        html_content = markdown2.markdown(st_md)

        # 2. 将HTML转换为PDF文件
        pdf_file_path = "generated_report.pdf"

        # 如果wkhtmltopdf不在PATH中，需要配置路径
        # config = pdfkit.configuration(wkhtmltopdf='/usr/local/bin/wkhtmltopdf')
        # pdfkit.from_string(html_content, pdf_file_path, configuration=config)

        pdfkit.from_string(html_content, pdf_file_path)

        # 3. 读取PDF文件内容并提供下载
        with open(pdf_file_path, "rb") as pdf_file:
            pdf_bytes = pdf_file.read()
            st.download_button(
                label="点击下载报告",
                data=pdf_bytes,
                file_name="report.pdf",
                mime="application/pdf"
            )

        st.success("PDF报告已生成并可下载！")

    except Exception as e:
        st.error(f"生成PDF时发生错误: {e}")
        st.warning("请确保已安装wkhtmltopdf，并已将其路径添加到系统PATH或在代码中配置。")
    finally:
        # 4. 清理生成的临时PDF文件
        if os.path.exists(pdf_file_path):
            os.remove(pdf_file_path)

运行此Streamlit应用 (streamlit run your_script_name.py)，您将看到Markdown内容显示在页面上，并且有一个按钮可以生成并下载对应的PDF文件。

注意事项与最佳实践

wkhtmltopdf的路径配置: 在部署Streamlit应用到不同的环境时（例如Docker容器、云平台），wkhtmltopdf的安装和路径配置尤为重要。务必确保其可执行文件在系统PATH中，或在pdfkit.configuration中明确指定。
临时文件清理: 每次生成PDF后，都会在服务器上留下一个文件。使用os.remove()在下载完成后清理这些临时文件是良好的实践，可以避免磁盘空间被不必要的文件占用。
错误处理: 在实际应用中，应包含try-except块来捕获pdfkit转换过程中可能发生的错误，例如wkhtmltopdf未找到、权限问题等，并向用户提供友好的反馈。
样式和布局: wkhtmltopdf支持通过CSS样式来控制PDF的布局和外观。您可以在Markdown转换为HTML后，在HTML字符串中嵌入
性能考虑: 对于非常大的Markdown文本，HTML到PDF的转换可能需要一些时间。在Streamlit中，如果操作耗时，可以考虑使用st.spinner来显示加载状态，提升用户体验。