markdown

package
v1.6.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Dec 26, 2025 License: MIT Imports: 16 Imported by: 0

README

WordZero Markdown转换包

pkg/markdown 包提供了 Markdown 和 Word 文档之间的双向转换功能。

功能特性

Markdown → Word 转换
  • 基于 goldmark 解析引擎
  • 支持 GitHub Flavored Markdown (GFM)
  • 支持标题、格式化文本、列表、表格、图片、链接等
  • 可配置的转换选项
Word → Markdown 转换 (新增)
  • 支持将 Word 文档反向导出为 Markdown
  • 保持文档结构和格式
  • 支持图片导出
  • 多种导出配置选项

基本使用

Word 到 Markdown 转换
package main

import (
    "fmt"
    "github.com/ZeroHawkeye/wordZero/pkg/markdown"
)

func main() {
    // 创建导出器
    exporter := markdown.NewExporter(markdown.DefaultExportOptions())
    
    // 导出Word文档为Markdown
    err := exporter.ExportToFile("document.docx", "output.md", nil)
    if err != nil {
        fmt.Printf("导出失败: %v\n", err)
        return
    }
    
    fmt.Println("Word文档已成功转换为Markdown!")
}
Markdown 到 Word 转换
package main

import (
    "fmt"
    "github.com/ZeroHawkeye/wordZero/pkg/markdown"
)

func main() {
    // 创建转换器
    converter := markdown.NewConverter(markdown.DefaultOptions())
    
    // 转换Markdown为Word文档
    err := converter.ConvertFile("input.md", "output.docx", nil)
    if err != nil {
        fmt.Printf("转换失败: %v\n", err)
        return
    }
    
    fmt.Println("Markdown已成功转换为Word文档!")
}
双向转换器
package main

import (
    "fmt"
    "github.com/ZeroHawkeye/wordZero/pkg/markdown"
)

func main() {
    // 创建双向转换器
    converter := markdown.NewBidirectionalConverter(
        markdown.DefaultOptions(),      // Markdown→Word选项
        markdown.DefaultExportOptions(), // Word→Markdown选项
    )
    
    // 自动检测文件类型并转换
    err := converter.AutoConvert("input.docx", "output.md")
    if err != nil {
        fmt.Printf("转换失败: %v\n", err)
        return
    }
    
    fmt.Println("文档转换完成!")
}

高级配置

Word 到 Markdown 导出选项
options := &markdown.ExportOptions{
    UseGFMTables:      true,  // 使用GitHub风味Markdown表格
    ExtractImages:     true,  // 导出图片文件
    ImageOutputDir:    "images/", // 图片输出目录
    PreserveFootnotes: true,  // 保留脚注
    UseSetext:         true,  // 使用Setext样式标题
    IncludeMetadata:   true,  // 包含文档元数据
    ProgressCallback: func(current, total int) {
        fmt.Printf("进度: %d/%d\n", current, total)
    },
}

exporter := markdown.NewExporter(options)
Markdown 到 Word 转换选项
options := &markdown.ConvertOptions{
    EnableGFM:         true,     // 启用GitHub风味Markdown
    EnableFootnotes:   true,     // 启用脚注支持
    EnableTables:      true,     // 启用表格支持
    EnableMath:        true,     // 启用数学公式支持(LaTeX语法)
    DefaultFontFamily: "Calibri", // 默认字体
    DefaultFontSize:   11.0,     // 默认字号
    GenerateTOC:       true,     // 生成目录
    TOCMaxLevel:       3,        // 目录最大级别
}

converter := markdown.NewConverter(options)

支持的转换映射

Word → Markdown
Word元素 Markdown语法 说明
Heading1-6 # 标题 标题级别对应
粗体 **粗体** 文本格式
斜体 *斜体* 文本格式
删除线 ~~删除线~~ 文本格式
代码 `代码` 行内代码
代码块 代码块 代码块
超链接 [链接](url) 链接转换
图片 ![图片](src) 图片引用
表格 | 表格 | GFM表格
列表 - 项目 列表项
Markdown → Word
Markdown语法 Word元素 实现方式
# 标题 Heading1样式 AddHeadingParagraph()
**粗体** 粗体格式 RunProperties.Bold
*斜体* 斜体格式 RunProperties.Italic
`代码` 代码样式 等宽字体
[链接](url) 超链接 AddHyperlink()
![图片](src) 图片 AddImageFromFile()
| 表格 | Word表格 AddTable()
- 列表 项目符号列表 AddBulletList()
$公式$ 数学公式 Cambria Math字体
$$公式$$ 块级数学公式 居中显示

批量转换

// 批量Markdown转Word
converter := markdown.NewConverter(markdown.DefaultOptions())
inputs := []string{"doc1.md", "doc2.md", "doc3.md"}
err := converter.BatchConvert(inputs, "output/", nil)

// 批量Word转Markdown
exporter := markdown.NewExporter(markdown.DefaultExportOptions())
inputs := []string{"doc1.docx", "doc2.docx", "doc3.docx"}
err := exporter.BatchExport(inputs, "markdown/", nil)

错误处理

options := &markdown.ExportOptions{
    StrictMode: true,  // 严格模式
    IgnoreErrors: false, // 不忽略错误
    ErrorCallback: func(err error) {
        fmt.Printf("转换错误: %v\n", err)
    },
}

兼容性说明

  • 该包与现有的 pkg/document 包完全兼容
  • 不修改任何现有API
  • 可以与现有代码无缝集成
  • 支持所有现有的Word文档操作功能

注意事项

  1. Word到Markdown转换会丢失某些Word特有的格式信息
  2. 复杂的表格布局可能需要手动调整
  3. 图片需要单独处理导出
  4. 某些Word样式在Markdown中没有直接对应
  5. 数学公式转换使用Unicode字符和Cambria Math字体,支持常见的LaTeX语法

数学公式支持

行内公式

使用单个美元符号包裹:$E = mc^2$

块级公式

使用双美元符号包裹:

$$
x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}
$$
支持的LaTeX语法
  • 希腊字母:\alpha, \beta, \gamma, \pi, \sigma
  • 运算符:\times, \div, \pm, \leq, \geq, \neq
  • 上下标:x^2, x_i, x^{n+1}, x_{i,j}
  • 分数:\frac{a}{b}
  • 根号:\sqrt{x}, \sqrt[3]{x}
  • 特殊符号:\infty, \sum, \int, \partial, \nabla
  • 箭头:\rightarrow, \leftarrow, \Rightarrow

未来计划

  • 数学公式支持
  • Mermaid图表转换
  • 更好的列表嵌套支持
  • 自定义样式映射
  • 命令行工具

Documentation

Overview

Package markdown 提供Markdown到Word文档的转换功能

Package markdown 提供Markdown到Word文档的转换功能

Index

Constants

This section is empty.

Variables

View Source
var (
	// ErrUnsupportedMarkdown 不支持的Markdown语法
	ErrUnsupportedMarkdown = errors.New("unsupported markdown syntax")

	// ErrInvalidImagePath 无效的图片路径
	ErrInvalidImagePath = errors.New("invalid image path")

	// ErrFileNotFound 文件未找到
	ErrFileNotFound = errors.New("file not found")

	// ErrInvalidMarkdown 无效的Markdown内容
	ErrInvalidMarkdown = errors.New("invalid markdown content")

	// ErrConversionFailed 转换失败
	ErrConversionFailed = errors.New("conversion failed")

	// ErrUnsupportedWordElement 不支持的Word元素
	ErrUnsupportedWordElement = errors.New("unsupported word element")

	// ErrExportFailed 导出失败
	ErrExportFailed = errors.New("export failed")

	// ErrInvalidDocument 无效的Word文档
	ErrInvalidDocument = errors.New("invalid word document")
)

Functions

func LaTeXToOMMLString added in v1.5.0

func LaTeXToOMMLString(latex string, isBlock bool) (string, error)

LaTeXToOMMLString 将LaTeX公式转换为OMML XML字符串

Types

type BidirectionalConverter

type BidirectionalConverter struct {
	// contains filtered or unexported fields
}

BidirectionalConverter 双向转换器

func NewBidirectionalConverter

func NewBidirectionalConverter(mdOpts *ConvertOptions, exportOpts *ExportOptions) *BidirectionalConverter

NewBidirectionalConverter 创建双向转换器

func (*BidirectionalConverter) AutoConvert

func (bc *BidirectionalConverter) AutoConvert(inputPath, outputPath string) error

AutoConvert 自动检测文件类型并转换

type ConversionError

type ConversionError struct {
	Type    string // 错误类型
	Message string // 错误消息
	Line    int    // 错误行号(如果适用)
	Column  int    // 错误列号(如果适用)
	Cause   error  // 原始错误
}

ConversionError 转换错误,包含详细信息

func NewConversionError

func NewConversionError(errorType, message string, line, column int, cause error) *ConversionError

NewConversionError 创建新的转换错误

func (*ConversionError) Error

func (e *ConversionError) Error() string

Error 实现error接口

func (*ConversionError) Unwrap

func (e *ConversionError) Unwrap() error

Unwrap 返回原始错误,支持errors.Unwrap

type ConvertOptions

type ConvertOptions struct {
	// 基础配置
	EnableGFM       bool // 启用GitHub Flavored Markdown
	EnableFootnotes bool // 启用脚注支持
	EnableTables    bool // 启用表格支持
	EnableTaskList  bool // 启用任务列表
	EnableMath      bool // 启用数学公式支持(LaTeX语法)

	// 样式配置
	StyleMapping      map[string]string // 自定义样式映射
	DefaultFontFamily string            // 默认字体
	DefaultFontSize   float64           // 默认字号

	// 图片处理
	ImageBasePath string  // 图片基础路径
	EmbedImages   bool    // 是否嵌入图片
	MaxImageWidth float64 // 最大图片宽度(英寸)

	// 链接处理
	PreserveLinkStyle  bool // 保留链接样式
	ConvertToBookmarks bool // 内部链接转书签

	// 文档设置
	GenerateTOC  bool                   // 生成目录
	TOCMaxLevel  int                    // 目录最大级别
	PageSettings *document.PageSettings // 页面设置(使用现有结构)

	// 错误处理
	StrictMode    bool        // 严格模式
	IgnoreErrors  bool        // 忽略转换错误
	ErrorCallback func(error) // 错误回调

	// 进度报告
	ProgressCallback func(int, int) // 进度回调
}

ConvertOptions 转换选项配置

func DefaultOptions

func DefaultOptions() *ConvertOptions

DefaultOptions 返回默认的转换配置

func HighQualityOptions

func HighQualityOptions() *ConvertOptions

HighQualityOptions 返回高质量转换配置

type Converter

type Converter struct {
	// contains filtered or unexported fields
}

Converter 默认转换器实现

func NewConverter

func NewConverter(opts *ConvertOptions) *Converter

NewConverter 创建新的转换器实例

func (*Converter) BatchConvert

func (c *Converter) BatchConvert(inputs []string, outputDir string, options *ConvertOptions) error

BatchConvert 批量转换文件

func (*Converter) ConvertBytes

func (c *Converter) ConvertBytes(content []byte, opts *ConvertOptions) (*document.Document, error)

ConvertBytes 转换字节数据为Word文档

func (*Converter) ConvertFile

func (c *Converter) ConvertFile(mdPath, docxPath string, options *ConvertOptions) error

ConvertFile 转换文件

func (*Converter) ConvertString

func (c *Converter) ConvertString(content string, opts *ConvertOptions) (*document.Document, error)

ConvertString 转换字符串内容为Word文档

type ExportError

type ExportError struct {
	Type    string // 错误类型
	Message string // 错误消息
	Cause   error  // 原始错误
}

ExportError 导出错误,包含详细信息

func NewExportError

func NewExportError(errorType, message string, cause error) *ExportError

NewExportError 创建新的导出错误

func (*ExportError) Error

func (e *ExportError) Error() string

Error 实现error接口

func (*ExportError) Unwrap

func (e *ExportError) Unwrap() error

Unwrap 返回原始错误,支持errors.Unwrap

type ExportOptions

type ExportOptions struct {
	// 基础配置
	UseGFMTables       bool // 使用GFM表格语法
	PreserveFootnotes  bool // 保留脚注
	PreserveLineBreaks bool // 保留换行符
	WrapLongLines      bool // 自动换行长行
	MaxLineLength      int  // 最大行长度

	// 图片处理
	ExtractImages     bool   // 是否导出图片文件
	ImageOutputDir    string // 图片输出目录
	ImageNamePattern  string // 图片命名模式
	ImageRelativePath bool   // 使用相对路径引用图片

	// 链接处理
	PreserveBookmarks bool // 保留书签为锚点链接
	ConvertHyperlinks bool // 转换超链接

	// 代码块处理
	PreserveCodeStyle bool   // 保留代码样式
	DefaultCodeLang   string // 默认代码语言标识

	// 样式映射
	CustomStyleMap      map[string]string // 自定义样式映射
	IgnoreUnknownStyles bool              // 忽略未知样式

	// 内容处理
	PreserveTOC     bool // 保留目录
	IncludeMetadata bool // 包含文档元数据
	StripComments   bool // 移除注释

	// 格式化选项
	UseSetext        bool   // 使用Setext样式标题
	BulletListMarker string // 项目符号标记
	EmphasisMarker   string // 强调标记

	// 错误处理
	StrictMode    bool        // 严格模式
	IgnoreErrors  bool        // 忽略转换错误
	ErrorCallback func(error) // 错误回调

	// 进度报告
	ProgressCallback func(int, int) // 进度回调
}

ExportOptions 导出选项配置

func DefaultExportOptions

func DefaultExportOptions() *ExportOptions

DefaultExportOptions 返回默认的导出配置

func HighQualityExportOptions

func HighQualityExportOptions() *ExportOptions

HighQualityExportOptions 返回高质量导出配置

type Exporter

type Exporter struct {
	// contains filtered or unexported fields
}

Exporter Word到Markdown导出器实现

func NewExporter

func NewExporter(opts *ExportOptions) *Exporter

NewExporter 创建新的导出器实例

func (*Exporter) BatchExport

func (e *Exporter) BatchExport(inputs []string, outputDir string, options *ExportOptions) error

BatchExport 批量导出

func (*Exporter) ExportToBytes

func (e *Exporter) ExportToBytes(doc *document.Document, options *ExportOptions) ([]byte, error)

ExportToBytes 导出Word文档到Markdown字节数组

func (*Exporter) ExportToFile

func (e *Exporter) ExportToFile(docxPath, mdPath string, options *ExportOptions) error

ExportToFile 导出Word文档到Markdown文件

func (*Exporter) ExportToString

func (e *Exporter) ExportToString(doc *document.Document, options *ExportOptions) (string, error)

ExportToString 导出Word文档到Markdown字符串

type MarkdownConverter

type MarkdownConverter interface {
	// ConvertFile 转换单个文件
	ConvertFile(mdPath, docxPath string, options *ConvertOptions) error

	// ConvertBytes 转换字节数据
	ConvertBytes(mdContent []byte, options *ConvertOptions) (*document.Document, error)

	// ConvertString 转换字符串
	ConvertString(mdContent string, options *ConvertOptions) (*document.Document, error)

	// BatchConvert 批量转换
	BatchConvert(inputs []string, outputDir string, options *ConvertOptions) error
}

MarkdownConverter Markdown转换器接口

type MarkdownWriter

type MarkdownWriter struct {
	// contains filtered or unexported fields
}

MarkdownWriter Markdown格式输出器

func (*MarkdownWriter) Write

func (w *MarkdownWriter) Write() ([]byte, error)

Write 生成Markdown内容

type MathDeg added in v1.5.0

type MathDeg struct {
	XMLName xml.Name      `xml:"m:deg"`
	Content []interface{} `xml:"-"`
}

MathDeg 表示根指数

func (*MathDeg) MarshalXML added in v1.5.0

func (d *MathDeg) MarshalXML(e *xml.Encoder, start xml.StartElement) error

MarshalXML 自定义XML序列化

type MathDegHide added in v1.5.0

type MathDegHide struct {
	XMLName xml.Name `xml:"m:degHide"`
	Val     string   `xml:"m:val,attr"`
}

MathDegHide 表示是否隐藏根指数

type MathDelim added in v1.5.0

type MathDelim struct {
	XMLName xml.Name     `xml:"m:d"`
	DPr     *MathDelimPr `xml:"m:dPr,omitempty"`
	E       *MathE       `xml:"m:e"`
}

MathDelim 表示分隔符(括号等)

type MathDelimChar added in v1.5.0

type MathDelimChar struct {
	XMLName xml.Name `xml:"m:begChr"`
	Val     string   `xml:"m:val,attr"`
}

MathDelimChar 表示分隔符字符

type MathDelimPr added in v1.5.0

type MathDelimPr struct {
	XMLName xml.Name       `xml:"m:dPr"`
	BegChr  *MathDelimChar `xml:"m:begChr,omitempty"`
	EndChr  *MathDelimChar `xml:"m:endChr,omitempty"`
}

MathDelimPr 表示分隔符属性

type MathDen added in v1.5.0

type MathDen struct {
	XMLName xml.Name      `xml:"m:den"`
	Content []interface{} `xml:"-"`
}

MathDen 表示分母

func (*MathDen) MarshalXML added in v1.5.0

func (d *MathDen) MarshalXML(e *xml.Encoder, start xml.StartElement) error

MarshalXML 自定义XML序列化

type MathE added in v1.5.0

type MathE struct {
	XMLName xml.Name      `xml:"m:e"`
	Content []interface{} `xml:"-"`
}

MathE 表示基础元素

func (*MathE) MarshalXML added in v1.5.0

func (m *MathE) MarshalXML(e *xml.Encoder, start xml.StartElement) error

MarshalXML 自定义XML序列化

type MathFrac added in v1.5.0

type MathFrac struct {
	XMLName xml.Name    `xml:"m:f"`
	FracPr  *MathFracPr `xml:"m:fPr,omitempty"`
	Num     *MathNum    `xml:"m:num"`
	Den     *MathDen    `xml:"m:den"`
}

MathFrac 表示分数

type MathFracPr added in v1.5.0

type MathFracPr struct {
	XMLName xml.Name      `xml:"m:fPr"`
	Type    *MathFracType `xml:"m:type,omitempty"`
}

MathFracPr 表示分数属性

type MathFracType added in v1.5.0

type MathFracType struct {
	XMLName xml.Name `xml:"m:type"`
	Val     string   `xml:"m:val,attr"`
}

MathFracType 表示分数类型

type MathNum added in v1.5.0

type MathNum struct {
	XMLName xml.Name      `xml:"m:num"`
	Content []interface{} `xml:"-"`
}

MathNum 表示分子

func (*MathNum) MarshalXML added in v1.5.0

func (n *MathNum) MarshalXML(e *xml.Encoder, start xml.StartElement) error

MarshalXML 自定义XML序列化

type MathRad added in v1.5.0

type MathRad struct {
	XMLName xml.Name   `xml:"m:rad"`
	RadPr   *MathRadPr `xml:"m:radPr,omitempty"`
	Deg     *MathDeg   `xml:"m:deg,omitempty"`
	E       *MathE     `xml:"m:e"`
}

MathRad 表示根号

type MathRadPr added in v1.5.0

type MathRadPr struct {
	XMLName xml.Name     `xml:"m:radPr"`
	DegHide *MathDegHide `xml:"m:degHide,omitempty"`
}

MathRadPr 表示根号属性

type MathRun added in v1.5.0

type MathRun struct {
	XMLName xml.Name     `xml:"m:r"`
	Text    *MathText    `xml:"m:t,omitempty"`
	RunPr   *MathRunProp `xml:"m:rPr,omitempty"`
}

MathRun 表示数学运行元素

type MathRunProp added in v1.5.0

type MathRunProp struct {
	XMLName xml.Name `xml:"m:rPr"`
	Sty     *MathSty `xml:"m:sty,omitempty"`
}

MathRunProp 表示数学运行属性

type MathSty added in v1.5.0

type MathSty struct {
	XMLName xml.Name `xml:"m:sty"`
	Val     string   `xml:"m:val,attr"`
}

MathSty 表示数学样式

type MathSub added in v1.5.0

type MathSub struct {
	XMLName xml.Name        `xml:"m:sSub"`
	E       *MathE          `xml:"m:e"`
	Sub     *MathSubElement `xml:"m:sub"`
}

MathSub 表示下标

type MathSubElement added in v1.5.0

type MathSubElement struct {
	XMLName xml.Name      `xml:"m:sub"`
	Content []interface{} `xml:"-"`
}

MathSubElement 表示下标元素

func (*MathSubElement) MarshalXML added in v1.5.0

func (s *MathSubElement) MarshalXML(e *xml.Encoder, start xml.StartElement) error

MarshalXML 自定义XML序列化

type MathSubSup added in v1.5.0

type MathSubSup struct {
	XMLName xml.Name        `xml:"m:sSubSup"`
	E       *MathE          `xml:"m:e"`
	Sub     *MathSubElement `xml:"m:sub"`
	Sup     *MathSupElement `xml:"m:sup"`
}

MathSubSup 表示上下标

type MathSup added in v1.5.0

type MathSup struct {
	XMLName xml.Name        `xml:"m:sSup"`
	E       *MathE          `xml:"m:e"`
	Sup     *MathSupElement `xml:"m:sup"`
}

MathSup 表示上标

type MathSupElement added in v1.5.0

type MathSupElement struct {
	XMLName xml.Name      `xml:"m:sup"`
	Content []interface{} `xml:"-"`
}

MathSupElement 表示上标元素

func (*MathSupElement) MarshalXML added in v1.5.0

func (s *MathSupElement) MarshalXML(e *xml.Encoder, start xml.StartElement) error

MarshalXML 自定义XML序列化

type MathText added in v1.5.0

type MathText struct {
	XMLName xml.Name `xml:"m:t"`
	Content string   `xml:",chardata"`
}

MathText 表示数学文本

type OfficeMath added in v1.5.0

type OfficeMath struct {
	XMLName xml.Name      `xml:"m:oMath"`
	Content []interface{} `xml:"-"` // 使用自定义序列化
}

OfficeMath 表示Office数学公式的根元素 对应OMML中的 m:oMath 元素

func LaTeXToOMML added in v1.5.0

func LaTeXToOMML(latex string) *OfficeMath

LaTeXToOMML 将LaTeX公式转换为OMML格式 这是一个简化版本的转换器,支持常用的LaTeX数学语法

func (*OfficeMath) MarshalXML added in v1.5.0

func (o *OfficeMath) MarshalXML(e *xml.Encoder, start xml.StartElement) error

MarshalXML 自定义XML序列化

type OfficeMathPara added in v1.5.0

type OfficeMathPara struct {
	XMLName xml.Name    `xml:"m:oMathPara"`
	Math    *OfficeMath `xml:"m:oMath"`
}

OfficeMathPara 表示Office数学公式段落 对应OMML中的 m:oMathPara 元素(用于块级公式)

type WordRenderer

type WordRenderer struct {
	// contains filtered or unexported fields
}

WordRenderer Word文档渲染器

func (*WordRenderer) Render

func (r *WordRenderer) Render(doc ast.Node) error

Render 渲染AST为Word文档

type WordToMarkdownExporter

type WordToMarkdownExporter interface {
	// ExportToFile 导出Word文档到Markdown文件
	ExportToFile(docxPath, mdPath string, options *ExportOptions) error

	// ExportToString 导出Word文档到Markdown字符串
	ExportToString(doc *document.Document, options *ExportOptions) (string, error)

	// ExportToBytes 导出Word文档到Markdown字节数组
	ExportToBytes(doc *document.Document, options *ExportOptions) ([]byte, error)

	// BatchExport 批量导出
	BatchExport(inputs []string, outputDir string, options *ExportOptions) error
}

WordToMarkdownExporter Word到Markdown导出器接口

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL