# markdown-generator **Repository Path**: nikai/markdown-generator ## Basic Information - **Project Name**: markdown-generator - **Description**: markdown-generator - **Primary Language**: Java - **License**: Apache-2.0 - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-08-12 - **Last Updated**: 2026-08-12 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # Markdown Generator 一个强大的 Java 库，用于通过优雅的流式 API 生成结构化的 Markdown 文档。 ## 简介 Markdown Generator 提供了一套完整的 API，让 Java 开发者能够以编程方式构建复杂的 Markdown 文档。该库采用 Builder 模式，支持链式调用，可以轻松创建标题、列表、表格、代码块、进度条等各种 Markdown 元素。 ## 主要特性 - **流式 API**：采用 Builder 模式，支持优雅的链式调用 - **完整元素支持**：支持标题、文本格式化、列表、表格、代码块、引用、链接、图片等 - **高级功能**：支持进度条、脚注、前言（Front Matter）、折叠内容 - **表格处理**：支持 CSV 转换、列对齐、行列裁剪 - **灵活定制**：可自定义分隔符、进度条样式、对齐方式等 ## 安装 ### 构建方法 ```shell mvn clean javadoc:jar source:jar install -DskipTests -Ddoclint=none -U mvn clean javadoc:jar source:jar deploy -DskipTests -Ddoclint=none -U ``` ```shell mvn clean javadoc:jar install -DskipTests -Ddoclint=none -U mvn clean javadoc:jar deploy -DskipTests -Ddoclint=none -U ``` ### Maven ```xml com.qoder markdown-generator 1.0.0 ``` ### Gradle ```groovy implementation 'com.qoder:markdown-generator:1.0.0' ``` ## 快速开始 ```java import com.qoder.md.generator.Markdown; import static com.qoder.md.generator.MarkdownElements.*; public class Example { public static void main(String[] args) { Markdown md = new Markdown(); md.append(h1("项目文档")) .append(paragraph("这是一个使用 Markdown Generator 创建的文档示例。")) .append(h2("功能特性")) .append(rule()) .append(bold("流式 API："), "支持链式调用")) .append(italic("优雅简洁："), "代码可读性强")) .append(newLine()) .append(h2("代码示例")) .append(codeBlock("System.out.println(\"Hello Markdown!\");", "java")) .append(newLine()) .append(h2("进度展示")) .append(progress(75.0)) .append(progressWithLabel(60.0)); System.out.println(md.toString()); } } ``` ## 核心类说明 ### MarkdownElements 静态工厂类，提供创建各种 Markdown 元素的快捷方法： ```java // 标题 Heading h1("一级标题"); Heading h2("二级标题"); Heading h3("三级标题"); // 文本格式化 BoldText bold("粗体文本"); ItalicText italic("斜体文本"); BoldItalicText boldItalic("粗斜体文本"); StrikeThroughText strikeThrough("删除线文本"); MarkedText marked("标记文本"); // 列表 UnorderedList list = unorderedList("项目1", "项目2", "项目3"); TaskList tasks = taskList(task("完成任务", true), task("未完成任务", false)); // 表格 Table table = new Table.Builder() .addRow("姓名", "年龄", "城市") .addRow("张三", "25", "北京") .addRow("李四", "30", "上海") .withAlignment(ALIGN_LEFT, ALIGN_CENTER, ALIGN_RIGHT) .build(); // 进度条 ProgressBar progress = progress(75.0); // [======....] 75% ProgressBar progressWithLabel = progressWithLabel(60.0); // [||||||....] 60% Complete // 代码 Code code = code("inline code"); CodeBlock codeBlock = codeBlock("public void main() {}", "java"); // 链接和图片 Link link = link("访问网站", "https://example.com"); Image image = image("描述", "image.png"); // 前言和脚注 FrontMatter frontMatter = frontMatter() .option("title", "文档标题") .option("author", "作者名"); Footnote footnote = footnote("1", "这是一个脚注内容"); // 折叠内容 CollapsedSection collapsed = collapsedSection("点击查看详情", "这里是折叠的详细内容。"); ``` ### MarkdownBuilder 核心构建器类，支持创建和嵌套各种 Markdown 元素： ```java MarkdownBuilder builder = new MarkdownBuilder<>(); builder.append(h1("文档标题")) .newParagraph() .text("这是一段文本") .bold("加粗文本") .italic("斜体文本") .newLine() .heading("二级标题", 2) .link("链接文本", "https://example.com") .image("图片描述", "image.png") .rule() .unorderedList("列表项1", "列表项2", "列表项3") .taskList(task("任务1", true), task("任务2", false)) .progress(50.0); ``` ### Markdown 最终输出类，将所有元素序列化为 Markdown 字符串： ```java Markdown md = new Markdown(); md.append(element1) .append(element2) .append(element3); String markdown = md.toText(); // 或 md.toString() ``` ### Table 和 TableRow 强大的表格支持： ```java // 使用 Builder 创建表格 Table table = new Table.Builder() .addRow("产品", "价格", "库存") .addRow("苹果", "5.00", "100") .addRow("香蕉", "3.00", "200") .withAlignments(ALIGN_LEFT, ALIGN_CENTER, ALIGN_RIGHT) .withRowLimit(100) .build(); // CSV 转换 String csv = table.toCsv(); // 表格裁剪 Table trimmed = table.trim(10); // 只保留前10行 // 直接创建行 TableRow row = new TableRow<>("列1", "列2", "列3"); ``` ### ProgressBar 进度条支持，可自定义样式： ```java ProgressBar progress = new ProgressBar(75.0, ProgressBar.LENGTH_NORMAL); progress.setOpeningChar('['); progress.setClosingChar(']'); progress.setFillChar('|'); progress.setEmptyChar('-'); progress.setAppendValue(true); progress.setAppendPercentage(true); ``` ### 引用块 ```java QuoteBuilder quoteBuilder = new QuoteBuilder(); quoteBuilder.append("这是一个引用内容") .bold("引用中的加粗文本") .italic("引用中的斜体文本"); // 或使用静态方法 Quote quote = quote("简单引用内容"); Quote nestedQuote = quote("外层引用", quote("内层引用内容")); ``` ### 代码块 ```java CodeBlockBuilder codeBlockBuilder = new CodeBlockBuilder("java"); codeBlockBuilder.append("public class Example {") .append(" public static void main(String[] args) {") .append(" System.out.println(\"Hello\");") .append(" }") .append("}"); // 或使用静态方法 CodeBlock block = codeBlock("console.log('Hello');", "javascript"); CodeBlock shellBlock = shell("ls -la", "bash"); ``` ## 最佳实践 1. **使用静态导入**：充分利用 `MarkdownElements` 的静态方法来简化代码 2. **链式调用**：尽量使用链式调用来构建文档结构 3. **合理使用换行**：使用 `newLine()` 和 `newParagraph()` 保持格式清晰 4. **表格布局**：使用 `minimumColumnWidth` 和对齐功能优化表格显示 5. **错误处理**：关注 `MarkdownSerializationException` 异常 ## 依赖说明 - JDK 8+ - 无外部依赖 ## 许可证 本项目遵循开源许可证协议。 ## 贡献 欢迎提交 Issue 和 Pull Request。 ## 联系 如有问题或建议，请通过 Gitee 仓库提交。