MarkFlow

轻量级 Markdown 智能排版与发布引擎
Lightweight Markdown Intelligent Typesetting & Publishing Engine

简体中文

项目介绍

MarkFlow 是一款纯 Python 实现、零外部依赖的 Markdown 智能排版与发布引擎。无论你是技术博主、开源维护者，还是日常撰写文档的开发者，MarkFlow 都能帮你一键美化排版、自动检查规范、快速转换格式、生成目录与统计报告，让 Markdown 写作体验更加流畅高效。

核心特性

功能	命令	说明
排版美化	`markflow beautify`	标题规范化、列表缩进修正、空行合并、中英文空格、全角半角标点统一
Lint 检查	`markflow lint`	8 项静态检查规则，支持 `--json` 输出
格式转换	`markflow convert`	Markdown 转 HTML / 纯文本
模板管理	`markflow template`	5 个内置模板，支持变量替换
统计分析	`markflow stats`	中英文字数、标题结构、元素统计、阅读时间估算
目录生成	`markflow toc`	提取标题生成锚点目录，支持插入文件

快速开始

环境要求

Python 3.7+
无其他依赖

安装

# 克隆项目
git clone https://github.com/gitstq/markflow.git
cd markflow

# 方式一：直接运行（无需安装）
python -m markflow --version

# 方式二：安装后使用
pip install .
markflow --version

三分钟上手

# 1. 美化你的 Markdown 文件
python -m markflow beautify README.md

# 2. 检查文档规范
python -m markflow lint README.md

# 3. 转换为 HTML
python -m markflow convert README.md --format html -o output.html

# 4. 查看文档统计
python -m markflow stats README.md

# 5. 生成并插入目录
python -m markflow toc README.md --insert

详细使用指南

1. `markflow beautify` - 排版美化

对 Markdown 文件进行智能排版美化，涵盖以下规则：

标题层级规范化：自动修正跳跃的标题级别（如 # 直接到 ### 会被调整为 ##）
列表缩进修正：统一使用 2 空格缩进
连续空行合并：多个连续空行合并为一个
中英文之间自动添加空格：中文English 变为 中文 English
全角/半角标点统一：中文语境下半角标点自动转为全角

# 美化文件（直接覆盖原文件）
python -m markflow beautify input.md

# 美化并输出到新文件
python -m markflow beautify input.md -o output.md

# 仅检查模式（不修改文件，仅显示差异）
python -m markflow beautify input.md --check

2. `markflow lint` - Lint 检查

内置 8 项检查规则，帮助你发现文档中的潜在问题：

规则编号	检查项	级别	说明
H001	标题层级跳跃	Warning	标题级别不应跳级
L001/L002	行过长	Error/Warning	超过 200/120 字符
C001	未闭合代码块	Error	代码块缺少结束标记
C002	代码块未标注语言	Warning	建议添加语言标识符
B001	连续空行	Warning	多个连续空行
I001	列表缩进不一致	Warning	同层级缩进不统一
K001/K002/K003	链接格式	Error/Warning	空链接、多余空格、引用缺失
H002	HTML 标签未闭合	Error	HTML 标签未正确关闭

# 执行 Lint 检查
python -m markflow lint document.md

# 以 JSON 格式输出（便于 CI/CD 集成）
python -m markflow lint document.md --json

# 静默模式（仅在有问题时输出）
python -m markflow lint document.md --quiet

3. `markflow convert` - 格式转换

将 Markdown 文件转换为 HTML 或纯文本格式。

# 转换为完整 HTML 文档
python -m markflow convert input.md --format html -o output.html

# 转换为 HTML 片段（不含文档结构）
python -m markflow convert input.md --format html --fragment

# 自定义 HTML 标题
python -m markflow convert input.md --format html --title "我的文档"

# 使用自定义 CSS
python -m markflow convert input.md --format html --css custom.css -o output.html

# 转换为纯文本
python -m markflow convert input.md --format text -o output.txt

4. `markflow template` - 模板管理

内置 5 个精心设计的文档模板，支持变量替换，快速创建标准文档。

模板	标识符	说明
技术博客	`blog`	包含标题、摘要、正文和标签
README	`readme`	项目文档模板
CHANGELOG	`changelog`	遵循 Keep a Changelog 格式
周报	`weekly`	工作周报模板
API 文档	`api_doc`	接口文档模板

# 查看所有可用模板
python -m markflow template list

# 从模板创建文件
python -m markflow template create blog -o my-blog.md

# 带变量替换
python -m markflow template create readme -o README.md \
  --title "我的项目" \
  --author "gitstq" \
  --version "1.0.0" \
  --description "项目描述"

支持的模板变量：{{title}}、{{author}}、{{version}}、{{description}}、{{project_name}}、{{date}}、{{datetime}}

5. `markflow stats` - 统计分析

全面分析 Markdown 文档的各项指标。

# 查看统计报告
python -m markflow stats document.md

# 以 JSON 格式输出
python -m markflow stats document.md --json

输出内容包括：

基础统计：总字符数、中文字符数、英文单词数、行数、段落数
标题结构：各级标题数量及标题列表
元素统计：代码块、链接、图片、表格、列表、引用块数量
阅读时间：基于中文 300 字/分钟、英文 200 词/分钟估算

6. `markflow toc` - 目录生成

从 Markdown 文件中提取标题，生成带锚点链接的目录。

# 生成目录（输出到终端）
python -m markflow toc document.md

# 将目录插入到文件中
python -m markflow toc document.md --insert

# 指定最大标题级别（仅显示 H2-H3）
python -m markflow toc document.md --max-level 3

# 在指定标题后插入目录
python -m markflow toc document.md --insert --after "项目介绍"

设计思路与迭代规划

设计理念

零依赖哲学：纯 Python 标准库实现，无需安装任何第三方包，开箱即用
CLI 优先：所有功能通过命令行暴露，方便集成到编辑器、CI/CD 和各类自动化流程
渐进式体验：每个子命令独立可用，可按需组合使用
中文友好：内置中英文混排规则、全角半角标点统一、中文阅读时间估算

未来规划

插件系统：支持自定义 Lint 规则和美化规则
配置文件：通过 .markflowrc 配置项目级规则
编辑器集成：提供 VS Code / Vim / Emacs 插件
更多输出格式：支持 PDF、DOCX 导出
Watch 模式：文件变更时自动执行 beautify 和 lint
GitHub Action：提供官方 CI/CD 集成方案

安装与部署

从源码安装

git clone https://github.com/gitstq/markflow.git
cd markflow
pip install .

使用 pip 直接安装

pip install markflow

验证安装

markflow --version
# 输出: MarkFlow v1.0.0

贡献指南

欢迎任何形式的贡献！无论是提交 Bug、建议新功能，还是直接提交 Pull Request。

参与步骤

Fork 本仓库
创建特性分支：git checkout -b feature/your-feature
提交更改：git commit -m "feat: add your feature"
推送分支：git push origin feature/your-feature
提交 Pull Request

开发环境

# 克隆仓库
git clone https://github.com/gitstq/markflow.git
cd markflow

# 直接运行（开发模式）
python -m markflow <command> [options]

# 运行测试
python -m pytest tests/

开源协议

本项目基于 MIT License 开源。

MIT License

Copyright (c) 2024 MarkFlow

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction...

繁體中文

專案介紹

MarkFlow 是一款純 Python 實作、零外部依賴的 Markdown 智慧排版與發布引擎。無論你是技術部落客、開源專案維護者，還是日常撰寫文件的開發者，MarkFlow 都能幫你一鍵美化排版、自動檢查規範、快速轉換格式、生成目錄與統計報告，讓 Markdown 寫作體驗更加流暢高效。

核心特性

功能	指令	說明
排版美化	`markflow beautify`	標題規範化、列表縮排修正、空行合併、中英文空格、全形半形標點統一
Lint 檢查	`markflow lint`	8 項靜態檢查規則，支援 `--json` 輸出
格式轉換	`markflow convert`	Markdown 轉 HTML / 純文字
模板管理	`markflow template`	5 個內建模板，支援變數替換
統計分析	`markflow stats`	中英文字數、標題結構、元素統計、閱讀時間估算
目錄生成	`markflow toc`	提取標題生成錨點目錄，支援插入檔案

快速開始

環境要求

Python 3.7+
無其他依賴

安裝

# 複製專案
git clone https://github.com/gitstq/markflow.git
cd markflow

# 方式一：直接執行（無需安裝）
python -m markflow --version

# 方式二：安裝後使用
pip install .
markflow --version

三分鐘上手

# 1. 美化你的 Markdown 檔案
python -m markflow beautify README.md

# 2. 檢查文件規範
python -m markflow lint README.md

# 3. 轉換為 HTML
python -m markflow convert README.md --format html -o output.html

# 4. 查看文件統計
python -m markflow stats README.md

# 5. 生成並插入目錄
python -m markflow toc README.md --insert

詳細使用指南

1. `markflow beautify` - 排版美化

對 Markdown 檔案進行智慧排版美化，涵蓋以下規則：

標題層級規範化：自動修正跳躍的標題級別（如 # 直接到 ### 會被調整為 ##）
列表縮排修正：統一使用 2 空格縮排
連續空行合併：多個連續空行合併為一個
中英文之間自動添加空格：中文English 變為 中文 English
全形/半形標點統一：中文語境下半形標點自動轉為全形

# 美化檔案（直接覆蓋原檔案）
python -m markflow beautify input.md

# 美化並輸出到新檔案
python -m markflow beautify input.md -o output.md

# 僅檢查模式（不修改檔案，僅顯示差異）
python -m markflow beautify input.md --check

2. `markflow lint` - Lint 檢查

內建 8 項檢查規則，幫助你發現文件中的潛在問題：

規則編號	檢查項	級別	說明
H001	標題層級跳躍	Warning	標題級別不應跳級
L001/L002	行過長	Error/Warning	超過 200/120 字元
C001	未閉合程式碼區塊	Error	程式碼區塊缺少結束標記
C002	程式碼區塊未標註語言	Warning	建議添加語言標識符
B001	連續空行	Warning	多個連續空行
I001	列表縮排不一致	Warning	同層級縮排不統一
K001/K002/K003	連結格式	Error/Warning	空連結、多餘空格、引用缺失
H002	HTML 標籤未閉合	Error	HTML 標籤未正確關閉

# 執行 Lint 檢查
python -m markflow lint document.md

# 以 JSON 格式輸出（便於 CI/CD 整合）
python -m markflow lint document.md --json

# 靜默模式（僅在有問題時輸出）
python -m markflow lint document.md --quiet

3. `markflow convert` - 格式轉換

將 Markdown 檔案轉換為 HTML 或純文字格式。

# 轉換為完整 HTML 文件
python -m markflow convert input.md --format html -o output.html

# 轉換為 HTML 片段（不含文件結構）
python -m markflow convert input.md --format html --fragment

# 自訂 HTML 標題
python -m markflow convert input.md --format html --title "我的文件"

# 使用自訂 CSS
python -m markflow convert input.md --format html --css custom.css -o output.html

# 轉換為純文字
python -m markflow convert input.md --format text -o output.txt

4. `markflow template` - 模板管理

內建 5 個精心設計的文件模板，支援變數替換，快速建立標準文件。

模板	標識符	說明
技術部落格	`blog`	包含標題、摘要、正文和標籤
README	`readme`	專案文件模板
CHANGELOG	`changelog`	遵循 Keep a Changelog 格式
週報	`weekly`	工作週報模板
API 文件	`api_doc`	介面文件模板

# 查看所有可用模板
python -m markflow template list

# 從模板建立檔案
python -m markflow template create blog -o my-blog.md

# 帶變數替換
python -m markflow template create readme -o README.md \
  --title "我的專案" \
  --author "gitstq" \
  --version "1.0.0" \
  --description "專案描述"

支援的模板變數：{{title}}、{{author}}、{{version}}、{{description}}、{{project_name}}、{{date}}、{{datetime}}

5. `markflow stats` - 統計分析

全面分析 Markdown 文件的各項指標。

# 查看統計報告
python -m markflow stats document.md

# 以 JSON 格式輸出
python -m markflow stats document.md --json

輸出內容包括：

基礎統計：總字元數、中文字元數、英文單字數、行數、段落數
標題結構：各級標題數量及標題列表
元素統計：程式碼區塊、連結、圖片、表格、列表、引用區塊數量
閱讀時間：基於中文 300 字/分鐘、英文 200 詞/分鐘估算

6. `markflow toc` - 目錄生成

從 Markdown 檔案中提取標題，生成帶錨點連結的目錄。

# 生成目錄（輸出到終端）
python -m markflow toc document.md

# 將目錄插入到檔案中
python -m markflow toc document.md --insert

# 指定最大標題級別（僅顯示 H2-H3）
python -m markflow toc document.md --max-level 3

# 在指定標題後插入目錄
python -m markflow toc document.md --insert --after "專案介紹"

設計思路與迭代規劃

設計理念

零依賴哲學：純 Python 標準函式庫實作，無需安裝任何第三方套件，開箱即用
CLI 優先：所有功能透過命令列暴露，方便整合到編輯器、CI/CD 和各類自動化流程
漸進式體驗：每個子指令獨立可用，可按需組合使用
中文友善：內建中英文混排規則、全形半形標點統一、中文閱讀時間估算

未來規劃

外掛系統：支援自訂 Lint 規則和美化規則
設定檔：透過 .markflowrc 設定專案級規則
編輯器整合：提供 VS Code / Vim / Emacs 外掛
更多輸出格式：支援 PDF、DOCX 匯出
Watch 模式：檔案變更時自動執行 beautify 和 lint
GitHub Action：提供官方 CI/CD 整合方案

安裝與部署

從原始碼安裝

git clone https://github.com/gitstq/markflow.git
cd markflow
pip install .

使用 pip 直接安裝

pip install markflow

驗證安裝

markflow --version
# 輸出: MarkFlow v1.0.0

貢獻指南

歡迎任何形式的貢獻！無論是提交 Bug、建議新功能，還是直接提交 Pull Request。

參與步驟

Fork 本儲存庫
建立特性分支：git checkout -b feature/your-feature
提交變更：git commit -m "feat: add your feature"
推送分支：git push origin feature/your-feature
提交 Pull Request

開發環境

# 複製儲存庫
git clone https://github.com/gitstq/markflow.git
cd markflow

# 直接執行（開發模式）
python -m markflow <command> [options]

# 執行測試
python -m pytest tests/

開源協議

本專案基於 MIT License 開源。

MIT License

Copyright (c) 2024 MarkFlow

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction...

English

Introduction

MarkFlow is a pure Python, zero-dependency Markdown intelligent typesetting and publishing engine. Whether you're a tech blogger, open-source maintainer, or a developer who writes documentation daily, MarkFlow helps you beautify formatting, lint for issues, convert formats, generate tables of contents, and produce statistical reports -- all with a single command-line tool.

Core Features

Feature	Command	Description
Beautify	`markflow beautify`	Normalize headings, fix list indentation, merge blank lines, add CJK-Latin spacing, unify punctuation
Lint	`markflow lint`	8 static analysis rules with `--json` output support
Convert	`markflow convert`	Markdown to HTML / plain text
Template	`markflow template`	5 built-in templates with variable substitution
Stats	`markflow stats`	Character/word count, heading structure, element stats, reading time estimation
TOC	`markflow toc`	Extract headings to generate anchored table of contents

Quick Start

Requirements

Python 3.7+
No other dependencies

Installation

# Clone the repository
git clone https://github.com/gitstq/markflow.git
cd markflow

# Option 1: Run directly (no installation needed)
python -m markflow --version

# Option 2: Install and use
pip install .
markflow --version

Three-Minute Tour

# 1. Beautify your Markdown file
python -m markflow beautify README.md

# 2. Lint your document
python -m markflow lint README.md

# 3. Convert to HTML
python -m markflow convert README.md --format html -o output.html

# 4. View document statistics
python -m markflow stats README.md

# 5. Generate and insert a table of contents
python -m markflow toc README.md --insert

Detailed Usage Guide

1. `markflow beautify` - Beautify

Intelligently beautify your Markdown files with the following rules:

Heading level normalization: Automatically fix heading level skipping (e.g., # directly to ### is adjusted to ##)
List indentation fix: Standardize to 2-space indentation
Consecutive blank line merging: Multiple blank lines are merged into one
CJK-Latin auto-spacing: ChineseEnglish becomes Chinese English
Fullwidth/halfwidth punctuation unification: Halfwidth punctuation in CJK context is auto-converted to fullwidth

# Beautify file (overwrites the original)
python -m markflow beautify input.md

# Beautify and output to a new file
python -m markflow beautify input.md -o output.md

# Check-only mode (no modifications, shows diff)
python -m markflow beautify input.md --check

2. `markflow lint` - Lint

Built-in 8 lint rules to help you catch potential issues in your documents:

Rule ID	Check	Level	Description
H001	Heading level skip	Warning	Heading levels should not skip
L001/L002	Line too long	Error/Warning	Exceeds 200/120 characters
C001	Unclosed code block	Error	Code block missing closing fence
C002	Code block without language	Warning	Language identifier recommended
B001	Consecutive blank lines	Warning	Multiple consecutive blank lines
I001	Inconsistent list indentation	Warning	Same-level indentation mismatch
K001/K002/K003	Link format	Error/Warning	Empty link, extra spaces, missing reference
H002	Unclosed HTML tag	Error	HTML tag not properly closed

# Run lint checks
python -m markflow lint document.md

# Output in JSON format (for CI/CD integration)
python -m markflow lint document.md --json

# Quiet mode (only output when issues found)
python -m markflow lint document.md --quiet

3. `markflow convert` - Convert

Convert Markdown files to HTML or plain text format.

# Convert to a full HTML document
python -m markflow convert input.md --format html -o output.html

# Convert to an HTML fragment (without document structure)
python -m markflow convert input.md --format html --fragment

# Custom HTML title
python -m markflow convert input.md --format html --title "My Document"

# Use custom CSS
python -m markflow convert input.md --format html --css custom.css -o output.html

# Convert to plain text
python -m markflow convert input.md --format text -o output.txt

4. `markflow template` - Template Management

5 built-in document templates with variable substitution for quick document creation.

Template	Identifier	Description
Tech Blog	`blog`	Title, summary, body, and tags
README	`readme`	Project documentation template
CHANGELOG	`changelog`	Keep a Changelog format
Weekly Report	`weekly`	Work weekly report template
API Doc	`api_doc`	API documentation template

# List all available templates
python -m markflow template list

# Create a file from a template
python -m markflow template create blog -o my-blog.md

# With variable substitution
python -m markflow template create readme -o README.md \
  --title "My Project" \
  --author "gitstq" \
  --version "1.0.0" \
  --description "Project description"

Supported template variables: {{title}}, {{author}}, {{version}}, {{description}}, {{project_name}}, {{date}}, {{datetime}}

5. `markflow stats` - Statistics

Comprehensive analysis of your Markdown document metrics.

# View statistics report
python -m markflow stats document.md

# Output in JSON format
python -m markflow stats document.md --json

Output includes:

Basic stats: Total characters, CJK characters, English words, lines, paragraphs
Heading structure: Count by level and full heading list
Element stats: Code blocks, links, images, tables, lists, blockquotes
Reading time: Estimated based on 300 CJK chars/min and 200 English words/min

6. `markflow toc` - Table of Contents

Extract headings from a Markdown file and generate an anchored table of contents.

# Generate TOC (output to terminal)
python -m markflow toc document.md

# Insert TOC into the file
python -m markflow toc document.md --insert

# Specify maximum heading level (show only H2-H3)
python -m markflow toc document.md --max-level 3

# Insert TOC after a specific heading
python -m markflow toc document.md --insert --after "Introduction"

Design Philosophy & Roadmap

Design Principles

Zero dependencies: Built entirely with Python standard library -- no third-party packages required, ready to use out of the box
CLI-first: All features exposed via command line for easy integration with editors, CI/CD pipelines, and automation workflows
Progressive experience: Each subcommand works independently; combine them as needed
CJK-friendly: Built-in CJK-Latin spacing rules, fullwidth/halfwidth punctuation normalization, and CJK reading time estimation

Roadmap

Plugin system: Support custom lint and beautify rules
Configuration file: Project-level rules via .markflowrc
Editor integration: VS Code / Vim / Emacs plugins
More output formats: PDF and DOCX export
Watch mode: Auto-run beautify and lint on file changes
GitHub Action: Official CI/CD integration

Installation & Deployment

Install from Source

git clone https://github.com/gitstq/markflow.git
cd markflow
pip install .

Install via pip

pip install markflow

Verify Installation

markflow --version
# Output: MarkFlow v1.0.0

Contributing

Contributions of all kinds are welcome! Whether it's reporting bugs, suggesting features, or submitting Pull Requests.

How to Contribute

Fork this repository
Create a feature branch: git checkout -b feature/your-feature
Commit your changes: git commit -m "feat: add your feature"
Push the branch: git push origin feature/your-feature
Submit a Pull Request

Development Setup

# Clone the repository
git clone https://github.com/gitstq/markflow.git
cd markflow

# Run directly (development mode)
python -m markflow <command> [options]

# Run tests
python -m pytest tests/

License

This project is open-sourced under the MIT License.

MIT License

Copyright (c) 2024 MarkFlow

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction...

Made with ❤️ by gitstq | GitHub | MIT License

Name		Name	Last commit message	Last commit date
Latest commit History 1 Commit
markflow		markflow
templates		templates
tests		tests
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
pyproject.toml		pyproject.toml
setup.py		setup.py

Folders and files

Latest commit

History

Repository files navigation

MarkFlow

简体中文

项目介绍

核心特性

快速开始

环境要求

安装

三分钟上手

详细使用指南

1. markflow beautify - 排版美化

2. markflow lint - Lint 检查

3. markflow convert - 格式转换

4. markflow template - 模板管理

5. markflow stats - 统计分析

6. markflow toc - 目录生成

设计思路与迭代规划

设计理念

未来规划

安装与部署

从源码安装

使用 pip 直接安装

验证安装

贡献指南

参与步骤

开发环境

开源协议

繁體中文

專案介紹

核心特性

快速開始

環境要求

安裝

三分鐘上手

詳細使用指南

1. markflow beautify - 排版美化

2. markflow lint - Lint 檢查

3. markflow convert - 格式轉換

4. markflow template - 模板管理

5. markflow stats - 統計分析

6. markflow toc - 目錄生成

設計思路與迭代規劃

設計理念

未來規劃

安裝與部署

從原始碼安裝

使用 pip 直接安裝

驗證安裝

貢獻指南

參與步驟

開發環境

開源協議

English

Introduction

Core Features

Quick Start

Requirements

Installation

Three-Minute Tour

Detailed Usage Guide

1. markflow beautify - Beautify

2. markflow lint - Lint

3. markflow convert - Convert

4. markflow template - Template Management

5. markflow stats - Statistics

6. markflow toc - Table of Contents

Design Philosophy & Roadmap

Design Principles

Roadmap

Installation & Deployment

Install from Source

Install via pip

Verify Installation

Contributing

How to Contribute

Development Setup

License

1. `markflow beautify` - 排版美化

2. `markflow lint` - Lint 检查

3. `markflow convert` - 格式转换

4. `markflow template` - 模板管理

5. `markflow stats` - 统计分析

6. `markflow toc` - 目录生成

1. `markflow beautify` - 排版美化

2. `markflow lint` - Lint 檢查

3. `markflow convert` - 格式轉換

4. `markflow template` - 模板管理

5. `markflow stats` - 統計分析

6. `markflow toc` - 目錄生成

1. `markflow beautify` - Beautify

2. `markflow lint` - Lint

3. `markflow convert` - Convert

4. `markflow template` - Template Management

5. `markflow stats` - Statistics

6. `markflow toc` - Table of Contents

Packages