本文主要介绍如何利用Python中的MarkItDown库将多种文件高效转换为Markdown文本,以及如何使用Python-Markdown库将Markdown文本转换为HTML(超文本标记语言)文本。
Markdown是一种轻量级的标记语言,用于以简洁易读的方式编写文本内容,同时能够方便地转换为结构化的HTML文本或其他格式,常用于编写文档、博客、论坛帖子等。它与纯文本极为接近,几乎不带任何标记或格式,却仍能有效呈现文档的重要结构。Markdown的详细使用说明可参考:Markdown教程。
主流的大型语言模型(LLM),如OpenAI的GPT-4,天生便"精通"Markdown,并且常常在未被提示的情况下将其融入回应之中。此外,Markdown的规范还具有极高的编码效率,可谓一举多得。

因此,学习Markdown语言的使用,并通过Python实现Markdown文本与其他格式文本的相互转换,能够提高文档编写的效率和质量,满足不同场景下的文档处理需求。
目录
- [1 MarkItDown库](#1 MarkItDown库)
- [1.1 MarkItDown库介绍](#1.1 MarkItDown库介绍)
- [1.2 MarkItDown库使用示例](#1.2 MarkItDown库使用示例)
- [2 Python-Markdown库](#2 Python-Markdown库)
- [2.1 Python-Markdown库介绍](#2.1 Python-Markdown库介绍)
- [2.2 Python-Markdown库使用示例](#2.2 Python-Markdown库使用示例)
- [3 参考](#3 参考)
1 MarkItDown库
1.1 MarkItDown库介绍
MarkItDown库是一款轻量级的Python版Markdown格式解析与渲染工具,能够将多种文件格式高效转换为Markdown格式,从而满足大语言模型(LLMs)及相关文本分析流程的需求。它专注于以Markdown格式精准保留文档的关键结构与内容,包括标题、列表、表格、链接等元素。虽然其输出结果既美观又易于人类用户阅读,但其核心设计宗旨是为文本分析工具提供支持,因此对于那些需要高保真度转换以供人类阅读的文档,它可能并非最优选择。
目前,MarkItDown库支持以下文件类型的转换:
- PowerPoint(按从上到下、从左到右的顺序读取内容)
- Word
- Excel
- 图片(支持EXIF元数据提取和光学字符识别OCR)
- 音频(支持EXIF元数据提取和语音转录)
- HTML
- 基于文本的格式(如CSV、JSON、XML)
- ZIP文件(可遍历文件内的内容进行转换)
- YouTube网址
- 以及其他更多类型!
MarkItDown库的官方仓库见:markitdown,MarkItDown需要在Python3.10及以上版本运行,MarkItDown库安装代码如下:
pip install 'markitdown[all]~=0.1.0a1'
或者从源代码安装:
shell
git clone [email protected]:microsoft/markitdown.git
cd markitdown
pip install -e packages/markitdown[all]
Markitdown与其他同类型工具库的比较见:Markitdown对比分析。
1.2 MarkItDown库使用示例
MarkItDown库将不同文件转换为Markdown格式的方式非常简单。只需初始化工具类,然后调用类对象的convert方法对文件进行转换,并输出Markdown格式字符串即可。
示例 1
以下代码展示了如何生成示例Excel数据,并使用MarkItDown库将其转换为Markdown格式的字符串和文件:
python
import pandas as pd
import numpy as np
# 生成一些示例数据
np.random.seed(0)
data = {
'Name': ['Alice', 'Bob', 'Charlie', 'David', 'Eve', 'Frank'],
'Age': [25, 30, 35, 40, 45, 50],
'Gender': ['Female', 'Male', 'Male', 'Male', 'Female', 'Male'],
'Score1': np.random.randint(0, 100, 6),
'Score2': np.random.randint(0, 100, 6)
}
# 创建一个基本的DataFrame
df = pd.DataFrame(data)
# 添加多级索引
index = pd.MultiIndex.from_product([['Group A', 'Group B'],
['Subgroup 1', 'Subgroup 2', 'Subgroup 3']],
names=['Group', 'Subgroup'])
df.index = index
# 计算每行的总分和平均分
df['Total Score'] = df[['Score1', 'Score2']].sum(axis=1)
df['Average Score'] = df[['Score1', 'Score2']].mean(axis=1)
# 显示表格
# print(df)
# 保存表格为xlsx文件
df.to_excel('test.xlsx')
# 将excel转换为markdown文件
from markitdown import MarkItDown
# 通过传递enable_plugins=Fals参数,表明在进行转换时不启用插件功能
md = MarkItDown(enable_plugins=False)
# 调用md对象的convert方法,将test.xlsx文件进行转换
result = md.convert("test.xlsx")
# text_content为一个字符串
print(result.text_content)
# 返回结果为字典
print(result.__dict__)
# 将结果保存为Markdown文件
# 定义要保存的Markdown文件的文件名
output_file = "output.md"
# 以写入模式打开文件,如果文件不存在则创建
with open(output_file, 'w', encoding='utf-8') as file:
# 将转换后的文本内容写入文件
file.write(result.text_content)
示例 2
本示例展示了使用MarkItDown库将pdf文件转换为Markdown数据,并开启Azure Document Intelligence功能,也就是利用Microsoft文档智能辅助进行转换。注意,此过程不会转换PDF中的图片。
python
import random
import string
# pip install fpdf
from fpdf import FPDF
from PIL import Image, ImageDraw, ImageFont
# 生成随机文字
def generate_random_text(length):
letters = string.ascii_letters + string.digits + string.punctuation
return ''.join(random.choice(letters) for i in range(length))
# 生成随机图片
def generate_random_image(width, height):
# 创建一个随机颜色的图片
image = Image.new('RGB', (width, height), color=(
random.randint(0, 255),
random.randint(0, 255),
random.randint(0, 255)
))
draw = ImageDraw.Draw(image)
font = ImageFont.load_default()
# 在图片上添加随机文字
text = generate_random_text(20)
draw.text((10, 10), text, fill=(255, 255, 255), font=font)
image_path = 'random_image.png'
image.save(image_path)
return image_path
# 创建PDF并添加随机图片和文字
def create_pdf():
pdf = FPDF()
pdf.add_page()
# 添加随机文字到PDF顶部
top_text = generate_random_text(100)
pdf.set_font("Arial", size=12)
pdf.multi_cell(0, 10, txt=top_text)
# 生成随机图片
image_path = generate_random_image(300, 200)
# 添加图片到PDF
pdf.image(image_path, x=10, y=pdf.get_y(), w=100)
# 移动到图片下方
pdf.ln(210)
# 添加随机文字到PDF底部
bottom_text = generate_random_text(100)
pdf.multi_cell(0, 10, txt=bottom_text)
# 保存PDF
pdf.output("test.pdf")
# 创建PDF
create_pdf()
from markitdown import MarkItDown
# 将文档转换为markdown
# Azure文档智能:可以使用Microsoft文档智能进行转换
md = MarkItDown(docintel_endpoint="<document_intelligence_endpoint>")
# 不会转换PDF中的图片
result = md.convert("test.pdf")
print(result.text_content)
示例 3
本示例展示了借助MarkItDown库使用大语言模型生成图像描述。在初始化该工具类时,需提供大语言模型客户端(llm_client)和大语言模型名字(llm_model)。
python
from markitdown import MarkItDown
from openai import OpenAI
client = OpenAI()
md = MarkItDown(llm_client=client, llm_model="gpt-4o")
result = md.convert("example.jpg")
print(result.text_content)
2 Python-Markdown库
2.1 Python-Markdown库介绍
若需将Markdown格式转换为HTML或其他格式,可以使用Python中的Python-Markdown库。该库是Markdown格式转换为HTML的纯Python实现,它支持标准的Markdown语法,并提供了许多扩展以增强功能。
Python-Markdown库的官方仓库见:Python-Markdown,Python-Markdown库需要在Python3.7及以上版本运行,Python-Markdown库安装代码如下:
pip install markdown
2.2 Python-Markdown库使用示例
示例 1
本示例展示了如何基于Python-Markdown库将Markdown文本转换为HTML。需注意,Python-Markdown库采用的是原始Markdown语法,即当列表项由多个段落构成时,列表项中每个后续段落都必须以4个空格的缩进起始。
python
import markdown
print(f'Markdown Version: {markdown.__version__}')
# 定义Markdown文本
markdown_text = """
# 这是一个markdown标题
这是一段普通文字,后续为列表项需要换行或者4个空格。
- 列表项 1
- 列表项 2
[markdown超链接](https://www.example.com)
"""
# 将Markdown文本转换为 HTML
html_text = markdown.markdown(markdown_text)
# 打印转换后的HTML文本
print(html_text)
示例 2
本示例展示了基于Python-Markdown库从本地Markdown文件中读取内容,并将其转换为HTM格式:
python
import markdown
def create_example_markdown(file_path):
example_content = """
# markdown示例标题
这是一个示例的Markdown文件内容。
## 子标题
下面是一个无序列表:
- 列表项 1
- 列表项 2
这里还有一个有序列表:
1. 有序项 1
2. 有序项 2
"""
try:
with open(file_path, 'w', encoding='utf-8') as file:
file.write(example_content)
print("示例 Markdown 文件已创建。")
except Exception as e:
print(f"错误: 创建文件时发生未知错误: {e}")
def read_markdown_file(file_path):
try:
with open(file_path, 'r', encoding='utf-8') as file:
return file.read()
except FileNotFoundError:
print(f"错误: 文件 {file_path} 未找到。")
return None
except Exception as e:
print(f"错误: 读取文件时发生未知错误: {e}")
return None
# 创建本地示例markdown文件
file_path = 'example.md'
create_example_markdown(file_path)
markdown_text = read_markdown_file(file_path)
if markdown_text is not None:
html_text = markdown.markdown(markdown_text)
print(html_text)
示例 3
本示例展示了在使用Python-Markdown库将Markdown文本转换为HTML的过程中,如何运用自定义扩展函数来修改生成的HTML格式。例如为标题和列表项添加样式。
python
from markdown.treeprocessors import Treeprocessor
from markdown.extensions import Extension
class MarkdownStyleProcessor(Treeprocessor):
# 遍历html节点设置不同参数
def run(self, tree_root):
for element in tree_root.iter():
if element.tag == "h1":
element.set("class", "custom-h1")
element.set("style", "color: #007BFF; font-size: 2.5em; margin-bottom: 0.5em;")
elif element.tag == "h2":
element.set("class", "custom-h2")
element.set("style", "color: #00FF00; font-size: 1.1em; margin-bottom: 0.3em;")
class MarkdownStyleExtension(Extension):
# 该方法用于扩展Markdown对象
def extendMarkdown(self, markdown_obj):
# markdown_style定义处理的名字。10表示表示处理器的优先级,值越大越往后处理
markdown_obj.treeprocessors.register(MarkdownStyleProcessor(markdown_obj), "markdown_style", 10)
import markdown
try:
with open("example.md", "r", encoding="utf-8") as file:
markdown_content = file.read()
# 将Markdown内容转换为HTML,同时使用自定义的扩展
html_result = markdown.markdown(
markdown_content,
extensions=[MarkdownStyleExtension()]
)
print(html_result)
except Exception as e:
print(f"发生错误: {e}")
示例 4
Python-Markdown库集成了若干插件,用以支持不同类型Markdown语法的转换。这些插件的调用可通过转换函数的extensions参数进行设置。以下是可扩展的功能及调用参数:
扩展功能 | 调用参数 | 模块路径 |
---|---|---|
额外功能 | extra | markdown.extensions.extra |
缩写 | abbr | markdown.extensions.abbr |
属性列表 | attr_list | markdown.extensions.attr_list |
定义列表 | def_list | markdown.extensions.def_list |
围栏代码块 | fenced_code | markdown.extensions.fenced_code |
脚注 | footnotes | markdown.extensions.footnotes |
HTML中的Markdown | md_in_html | markdown.extensions.md_in_html |
表格 | tables | markdown.extensions.tables |
警告 | admonition | markdown.extensions.admonition |
代码高亮 | codehilite | markdown.extensions.codehilite |
遗留属性 | legacy_attrs | markdown.extensions.legacy_attrs |
遗留强调 | legacy_em | markdown.extensions.legacy_em |
元数据 | meta | markdown.extensions.meta |
新行转断行 | nl2br | markdown.extensions.nl2br |
合理列表 | sane_lists | markdown.extensions.sane_lists |
智能标点 | smarty | markdown.extensions.smarty |
目录 | toc | markdown.extensions.toc |
Wiki链接 | wikilinks | markdown.extensions.wikilinks |
以下代码展示了如何基于Python-Markdown库从文件中读取Markdown内容,并利用该库的扩展功能来增添额外特性,例如脚注、代码块和表格。
示例markdown文件如下:
markdown
# 示例
示例代码如下[^1]:
print("Hello World!")
示例表格如下[^2]:
|姓名|年龄|
|:-|-:|
|张三|16|
|李四|23|
[^1]: 示例代码
[^2]: 示例表格
转换代码如下:
python
import markdown
with open("example.md", "r", encoding="utf-8") as fd:
markdown_text = fd.read()
# 通过extensions参数设置转换格式
html_output = markdown.markdown(
markdown_text,
extensions=["tables", "footnotes", "fenced_code"]
)
print(html_output)