Skip to content

gitstq/markflow

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

1 Commit
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

简体中文 | 繁體中文 | English

Python 3.8+ MIT License Version 1.0.0 Zero Dependencies Cross Platform


简体中文

MarkFlow — 轻量级可编程 Markdown 排版引擎

🎉 项目简介

MarkFlow 是一个纯 Python 实现的轻量级可编程 Markdown 排版引擎,零外部依赖,仅需 Python 3.8+ 即可运行。

解决的痛点

  • Markdown 太静态:原生 Markdown 不支持变量、条件、循环等动态能力,每次修改内容都需要手动重复编辑
  • 模板引擎太笨重:Jinja2、Liquid 等模板引擎功能强大但依赖复杂,与 Markdown 的融合体验不佳
  • 中文排版不够优雅:现有工具对 CJK(中日韩)文字的排版优化不足,标点挤压、间距处理等细节缺失
  • 插件生态匮乏:Markdown 扩展语法(如提示框、徽章、进度条等)缺乏统一的轻量解决方案

设计灵感

MarkFlow 的设计灵感来源于 Quarkdown —— 一个用 Swift 编写的可编程 Markdown 引擎。我们希望将同样强大的可编程排版能力带给 Python 社区,同时针对中文排版场景做深度优化。


✨ 核心特性

  • 🔄 变量插值:使用 {{ variable }} 语法在文档中插入动态变量
  • 🔀 条件渲染:通过 {% if condition %}...{% else %}...{% endif %} 控制内容显示
  • 🔁 循环控制:使用 {% for item in items %}...{% endfor %} 遍历列表,支持 loop.indexloop.firstloop.last
  • 函数调用:通过 {% call func args %} 调用函数,内置 30+ 实用函数
  • 🔗 过滤器管道{{ variable | filter1 | filter2 }} 链式处理数据
  • 📄 模板引用{% include "file.md" %} 实现模板复用与模块化
  • 📋 Frontmatter 支持:YAML 格式的文档元数据管理
  • 🧩 插件系统:内置 20+ 插件(提示框、徽章、进度条、折叠面板、按钮、数学公式、流程图、图标、脚注等)
  • 🈶 CJK 排版优化:自动标点挤压、合理间距处理,让中文排版更优雅
  • 📤 多格式输出:支持 HTML(完整文档)、HTML 片段、Slides(演示文稿)三种输出格式
  • 👀 实时预览:内置开发服务器,文件变更自动刷新
  • 📑 目录生成:自动生成文档目录(TOC)
  • 🔒 安全沙箱:表达式安全求值,防止恶意代码执行
  • 📝 原始块{% raw %}...{% endraw %} 保留原始内容不做解析

🚀 快速开始

环境要求

  • Python 3.8 或更高版本
  • pip 包管理器

安装

pip install markflow

构建文档

markflow build document.md -o output.html

实时预览

markflow serve document.md --port 8080

初始化项目

markflow init --name my-project

📖 详细使用指南

变量插值

在 Frontmatter 中定义变量,然后在文档中使用 {{ }} 引用:

---
title: MarkFlow 使用指南
version: 1.0.0
author: 张三
---

# {{ title }}

版本:{{ version }},作者:{{ author }}

条件渲染

根据条件动态显示内容:

{% if show_toc %}
## 📑 目录

本文档包含完整的目录结构。
{% endif %}

{% if env == "production" %}
> ⚠️ 当前为生产环境,请谨慎操作。
{% else %}
> 💡 当前为开发环境。
{% endif %}

循环控制

遍历列表数据生成重复内容:

---
features:
  - 变量插值
  - 条件渲染
  - 循环控制
  - 函数调用
---

## 功能列表

{% for feature in features %}
- **{{ loop.index }}.** {{ feature }}
{% endfor %}

{% for item in items %}
{% if loop.first %}📌 {% endif %}{{ item }}{% if loop.last %} ✅{% endif %}
{% endfor %}

函数调用

内置 30+ 实用函数,覆盖文本处理、日期格式化、数学计算等场景:

当前日期:{% call now %}
当前时间戳:{% call timestamp %}
大写转换:{% call upper "hello world" %}
随机数:{% call random_int 1 100 %}

过滤器管道

通过管道符 | 链式处理变量:

{{ title | upper | trim }}
{{ description | truncate 50 }}
{{ price | round 2 }}
{{ tags | join ", " }}

插件系统

20+ 内置插件,丰富 Markdown 表达能力:

提示框(Alerts):

:::tip 提示
这是一个提示信息。
:::

:::warning 警告
这是一个警告信息。
:::

:::danger 危险
这是一个危险操作警告。
:::

徽章(Badges):

![版本](badge:v1.0.0:blue)
![状态](badge:稳定:green)

进度条(Progress):

:::progress 75
项目完成度
:::

折叠面板(Details):

:::details 点击展开
这里是折叠的详细内容。
:::

按钮(Buttons):

:::button[获取 started](https://github.com/gitstq/markflow)

数学公式(Math):

$$
E = mc^2
$$

流程图(Flowchart):

:::flowchart
graph TD
    A[开始] --> B{判断}
    B -->|是| C[执行]
    B -->|否| D[结束]
:::

图标(Icons):

:icon-github: :icon-heart: :icon-star:

脚注(Footnotes):

这是一段带脚注的文字[^1][^1]: 这是脚注内容。

Frontmatter

在文档开头使用 YAML 格式定义元数据:

---
title: 项目文档
date: 2026-05-02
author: 张三
tags: [markdown, 排版, 工具]
draft: false
config:
  theme: light
  toc: true
---

# {{ title }}

Slides 演示文稿

将 Markdown 转换为演示文稿:

markflow build slides.md -o slides.html --format slides
---
title: 产品介绍
format: slides
---

# 第一页:产品概述

这是第一页的内容。

---

# 第二页:核心功能

- 功能一
- 功能二
- 功能三

---

# 第三页:谢谢

感谢观看!

💡 设计理念与路线图

设计理念

  • 纯 Python 实现:不依赖任何第三方库,降低安装和部署复杂度
  • 零依赖策略:从安装到运行,不需要额外的系统库或 Python 包
  • CJK 排版优先:针对中文、日文、韩文排版场景做深度优化
  • 渐进式增强:基础功能开箱即用,高级功能按需启用
  • 安全第一:内置沙箱机制,防止模板注入攻击

路线图

  • 更多输出格式支持(PDF、DOCX)
  • 主题系统与自定义样式
  • 插件市场与社区生态
  • VS Code 编辑器扩展
  • Web 在线编辑器
  • 更多内置函数与过滤器

📦 构建与部署

构建 HTML

# 构建完整 HTML 文档
markflow build document.md -o output.html

# 仅输出 HTML 片段(不含 head/body)
markflow build document.md -o output.html --format body

构建演示文稿

markflow build slides.md -o slides.html --format slides

监听模式(Watch)

# 监听文件变化,自动重新构建
markflow build document.md -o output.html --watch

CI/CD 集成

# GitHub Actions 示例
name: Deploy Docs
on:
  push:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"
      - run: pip install markflow
      - run: markflow build docs/index.md -o index.html
      - uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./

🤝 参与贡献

我们欢迎任何形式的贡献!无论是提交 Bug、改进文档还是开发新功能。

提交 Pull Request

  1. Fork 本仓库
  2. 创建特性分支:git checkout -b feature/my-feature
  3. 提交更改:git commit -m "feat: 添加新功能描述"
  4. 推送分支:git push origin feature/my-feature
  5. 提交 Pull Request

PR 格式规范

提交信息请遵循 Conventional Commits 规范:

<type>(<scope>): <description>

[optional body]

[optional footer]

类型(type):feat | fix | docs | style | refactor | test | chore

提交 Issue

提交 Issue 时请包含以下信息:

  • 问题描述:清晰描述遇到的问题
  • 复现步骤:列出复现问题的最小步骤
  • 期望行为:描述期望的正确行为
  • 环境信息:操作系统、Python 版本、MarkFlow 版本
  • 最小示例:如果能提供,附上最小可复现代码

📄 许可证

本项目基于 MIT License 开源。

MIT License

Copyright (c) 2026 MarkFlow Contributors

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, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

Built with ❤️ by the MarkFlow team


繁體中文

MarkFlow — 輕量級可程式化 Markdown 排版引擎

🎉 專案簡介

MarkFlow 是一個純 Python 實作的輕量級可程式化 Markdown 排版引擎,零外部依賴,僅需 Python 3.8+ 即可執行。

解決的痛點

  • Markdown 太靜態:原生 Markdown 不支援變數、條件、迴圈等動態能力,每次修改內容都需要手動重複編輯
  • 模板引擎太笨重:Jinja2、Liquid 等模板引擎功能強大但依賴複雜,與 Markdown 的融合體驗不佳
  • 中文排版不夠優雅:現有工具對 CJK(中日韓)文字的排版最佳化不足,標點擠壓、間距處理等細節缺失
  • 插件生態匱乏:Markdown 擴充語法(如提示框、徽章、進度條等)缺乏統一的輕量解決方案

設計靈感

MarkFlow 的設計靈感來源於 Quarkdown —— 一個用 Swift 編寫的可程式化 Markdown 引擎。我們希望將同樣強大的可程式化排版能力帶給 Python 社群,同時針對中文排版場景做深度最佳化。


✨ 核心特性

  • 🔄 變數插值:使用 {{ variable }} 語法在文件中插入動態變數
  • 🔀 條件渲染:透過 {% if condition %}...{% else %}...{% endif %} 控制內容顯示
  • 🔁 迴圈控制:使用 {% for item in items %}...{% endfor %} 遍歷列表,支援 loop.indexloop.firstloop.last
  • 函式呼叫:透過 {% call func args %} 呼叫函式,內建 30+ 實用函式
  • 🔗 過濾器管道{{ variable | filter1 | filter2 }} 鏈式處理資料
  • 📄 模板引用{% include "file.md" %} 實現模板複用與模組化
  • 📋 Frontmatter 支援:YAML 格式的文件元資料管理
  • 🧩 插件系統:內建 20+ 插件(提示框、徽章、進度條、折疊面板、按鈕、數學公式、流程圖、圖示、腳註等)
  • 🈶 CJK 排版最佳化:自動標點擠壓、合理間距處理,讓中文排版更優雅
  • 📤 多格式輸出:支援 HTML(完整文件)、HTML 片段、Slides(簡報)三種輸出格式
  • 👀 即時預覽:內建開發伺服器,檔案變更自動重新整理
  • 📑 目錄生成:自動生成文件目錄(TOC)
  • 🔒 安全沙箱:表達式安全求值,防止惡意程式碼執行
  • 📝 原始區塊{% raw %}...{% endraw %} 保留原始內容不做解析

🚀 快速開始

環境需求

  • Python 3.8 或更高版本
  • pip 套件管理器

安裝

pip install markflow

建置文件

markflow build document.md -o output.html

即時預覽

markflow serve document.md --port 8080

初始化專案

markflow init --name my-project

📖 詳細使用指南

變數插值

在 Frontmatter 中定義變數,然後在文件中使用 {{ }} 引用:

---
title: MarkFlow 使用指南
version: 1.0.0
author: 張三
---

# {{ title }}

版本:{{ version }},作者:{{ author }}

條件渲染

根據條件動態顯示內容:

{% if show_toc %}
## 📑 目錄

本文件包含完整的目錄結構。
{% endif %}

{% if env == "production" %}
> ⚠️ 目前為正式環境,請謹慎操作。
{% else %}
> 💡 目前為開發環境。
{% endif %}

迴圈控制

遍歷列表資料生成重複內容:

---
features:
  - 變數插值
  - 條件渲染
  - 迴圈控制
  - 函式呼叫
---

## 功能列表

{% for feature in features %}
- **{{ loop.index }}.** {{ feature }}
{% endfor %}

{% for item in items %}
{% if loop.first %}📌 {% endif %}{{ item }}{% if loop.last %} ✅{% endif %}
{% endfor %}

函式呼叫

內建 30+ 實用函式,涵蓋文字處理、日期格式化、數學計算等場景:

目前日期:{% call now %}
目前時間戳記:{% call timestamp %}
大寫轉換:{% call upper "hello world" %}
亂數:{% call random_int 1 100 %}

過濾器管道

透過管道符 | 鏈式處理變數:

{{ title | upper | trim }}
{{ description | truncate 50 }}
{{ price | round 2 }}
{{ tags | join ", " }}

插件系統

20+ 內建插件,豐富 Markdown 表達能力:

提示框(Alerts):

:::tip 提示
這是一個提示資訊。
:::

:::warning 警告
這是一個警告資訊。
:::

:::danger 危險
這是一個危險操作警告。
:::

徽章(Badges):

![版本](badge:v1.0.0:blue)
![狀態](badge:穩定:green)

進度條(Progress):

:::progress 75
專案完成度
:::

折疊面板(Details):

:::details 點擊展開
這裡是折疊的詳細內容。
:::

按鈕(Buttons):

:::button[開始使用](https://github.com/gitstq/markflow)

數學公式(Math):

$$
E = mc^2
$$

流程圖(Flowchart):

:::flowchart
graph TD
    A[開始] --> B{判斷}
    B -->|是| C[執行]
    B -->|否| D[結束]
:::

圖示(Icons):

:icon-github: :icon-heart: :icon-star:

腳註(Footnotes):

這是一段帶腳註的文字[^1][^1]: 這是腳註內容。

Frontmatter

在文件開頭使用 YAML 格式定義元資料:

---
title: 專案文件
date: 2026-05-02
author: 張三
tags: [markdown, 排版, 工具]
draft: false
config:
  theme: light
  toc: true
---

# {{ title }}

Slides 簡報

將 Markdown 轉換為簡報:

markflow build slides.md -o slides.html --format slides
---
title: 產品介紹
format: slides
---

# 第一頁:產品概述

這是第一頁的內容。

---

# 第二頁:核心功能

- 功能一
- 功能二
- 功能三

---

# 第三頁:謝謝

感謝觀看!

💡 設計理念與路線圖

設計理念

  • 純 Python 實作:不依賴任何第三方函式庫,降低安裝和部署複雜度
  • 零依賴策略:從安裝到執行,不需要額外的系統函式庫或 Python 套件
  • CJK 排版優先:針對中文、日文、韓文排版場景做深度最佳化
  • 漸進式增強:基礎功能開箱即用,進階功能按需啟用
  • 安全第一:內建沙箱機制,防止模板注入攻擊

路線圖

  • 更多輸出格式支援(PDF、DOCX)
  • 主題系統與自訂樣式
  • 插件市場與社群生態
  • VS Code 編輯器擴充功能
  • Web 線上編輯器
  • 更多內建函式與過濾器

📦 建置與部署

建置 HTML

# 建置完整 HTML 文件
markflow build document.md -o output.html

# 僅輸出 HTML 片段(不含 head/body)
markflow build document.md -o output.html --format body

建置簡報

markflow build slides.md -o slides.html --format slides

監聽模式(Watch)

# 監聽檔案變化,自動重新建置
markflow build document.md -o output.html --watch

CI/CD 整合

# GitHub Actions 範例
name: Deploy Docs
on:
  push:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"
      - run: pip install markflow
      - run: markflow build docs/index.md -o index.html
      - uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./

🤝 參與貢獻

我們歡迎任何形式的貢獻!無論是提交 Bug、改進文件還是開發新功能。

提交 Pull Request

  1. Fork 本儲存庫
  2. 建立特性分支:git checkout -b feature/my-feature
  3. 提交變更:git commit -m "feat: 新增新功能描述"
  4. 推送分支:git push origin feature/my-feature
  5. 提交 Pull Request

PR 格式規範

提交資訊請遵循 Conventional Commits 規範:

<type>(<scope>): <description>

[optional body]

[optional footer]

類型(type):feat | fix | docs | style | refactor | test | chore

提交 Issue

提交 Issue 時請包含以下資訊:

  • 問題描述:清晰描述遇到的問題
  • 重現步驟:列出重現問題的最小步驟
  • 期望行為:描述期望的正確行為
  • 環境資訊:作業系統、Python 版本、MarkFlow 版本
  • 最小範例:如果可以提供,附上最小可重現程式碼

📄 授權條款

本專案基於 MIT License 開源。

MIT License

Copyright (c) 2026 MarkFlow Contributors

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, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

Built with ❤️ by the MarkFlow team


English

MarkFlow — Lightweight Programmable Markdown Typesetting Engine

🎉 Introduction

MarkFlow is a lightweight programmable Markdown typesetting engine built in pure Python with zero external dependencies. It requires only Python 3.8+ to run.

Pain Points Solved

  • Markdown is too static: Native Markdown lacks dynamic capabilities like variables, conditions, and loops. Every content update requires manual repetitive editing.
  • Template engines are too heavy: Jinja2, Liquid, and similar template engines are powerful but come with complex dependencies and a poor integration experience with Markdown.
  • CJK typography is overlooked: Existing tools lack proper optimization for CJK (Chinese, Japanese, Korean) typesetting, missing details like punctuation compression and spacing.
  • Plugin ecosystems are sparse: Extended Markdown syntax (alerts, badges, progress bars, etc.) lacks a unified lightweight solution.

Design Inspiration

MarkFlow draws inspiration from Quarkdown — a programmable Markdown engine written in Swift. We aim to bring the same powerful programmable typesetting capabilities to the Python community, with deep optimization for CJK typography scenarios.


✨ Core Features

  • 🔄 Variable interpolation: Insert dynamic variables using {{ variable }} syntax
  • 🔀 Conditional rendering: Control content display with {% if condition %}...{% else %}...{% endif %}
  • 🔁 Loop control: Iterate over lists with {% for item in items %}...{% endfor %}, supporting loop.index, loop.first, loop.last
  • Function calls: Invoke functions via {% call func args %} with 30+ built-in functions
  • 🔗 Filter pipeline: Chain data transformations with {{ variable | filter1 | filter2 }}
  • 📄 Template includes: Reuse templates with {% include "file.md" %}
  • 📋 Frontmatter support: YAML-based document metadata management
  • 🧩 Plugin system: 20+ built-in plugins (alerts, badges, progress bars, details, buttons, math, flowcharts, icons, footnotes, etc.)
  • 🈶 CJK typography optimization: Automatic punctuation compression and proper spacing for elegant CJK typesetting
  • 📤 Multiple output formats: HTML (full document), HTML body, and Slides (presentation)
  • 👀 Live preview server: Built-in dev server with auto-reload on file changes
  • 📑 Table of contents generation: Automatic TOC generation
  • 🔒 Safe expression evaluator: Sandboxed expression evaluation to prevent malicious code execution
  • 📝 Raw blocks: Preserve raw content with {% raw %}...{% endraw %}

🚀 Quick Start

Requirements

  • Python 3.8 or later
  • pip package manager

Installation

pip install markflow

Build Document

markflow build document.md -o output.html

Live Preview

markflow serve document.md --port 8080

Initialize Project

markflow init --name my-project

📖 Detailed Usage Guide

Variable Interpolation

Define variables in Frontmatter and reference them with {{ }} in your document:

---
title: MarkFlow User Guide
version: 1.0.0
author: John Doe
---

# {{ title }}

Version: {{ version }}, Author: {{ author }}

Conditional Rendering

Dynamically show or hide content based on conditions:

{% if show_toc %}
## 📑 Table of Contents

This document includes a complete table of contents.
{% endif %}

{% if env == "production" %}
> ⚠️ This is a production environment. Proceed with caution.
{% else %}
> 💡 This is a development environment.
{% endif %}

Loop Control

Iterate over list data to generate repeated content:

---
features:
  - Variable interpolation
  - Conditional rendering
  - Loop control
  - Function calls
---

## Feature List

{% for feature in features %}
- **{{ loop.index }}.** {{ feature }}
{% endfor %}

{% for item in items %}
{% if loop.first %}📌 {% endif %}{{ item }}{% if loop.last %} ✅{% endif %}
{% endfor %}

Function Calls

30+ built-in functions covering text processing, date formatting, math calculations, and more:

Current date: {% call now %}
Current timestamp: {% call timestamp %}
Uppercase: {% call upper "hello world" %}
Random number: {% call random_int 1 100 %}

Filter Pipeline

Chain data transformations using the pipe | operator:

{{ title | upper | trim }}
{{ description | truncate 50 }}
{{ price | round 2 }}
{{ tags | join ", " }}

Plugin System

20+ built-in plugins to extend Markdown's expressive power:

Alerts:

:::tip Tip
This is a tip message.
:::

:::warning Warning
This is a warning message.
:::

:::danger Danger
This is a danger alert.
:::

Badges:

![Version](badge:v1.0.0:blue)
![Status](badge:stable:green)

Progress Bars:

:::progress 75
Project completion
:::

Details (Collapsible):

:::details Click to expand
Here is the collapsed detailed content.
:::

Buttons:

:::button[Get Started](https://github.com/gitstq/markflow)

Math:

$$
E = mc^2
$$

Flowcharts:

:::flowchart
graph TD
    A[Start] --> B{Decision}
    B -->|Yes| C[Execute]
    B -->|No| D[End]
:::

Icons:

:icon-github: :icon-heart: :icon-star:

Footnotes:

This is text with a footnote[^1].

[^1]: This is the footnote content.

Frontmatter

Define metadata at the top of your document using YAML format:

---
title: Project Documentation
date: 2026-05-02
author: John Doe
tags: [markdown, typesetting, tool]
draft: false
config:
  theme: light
  toc: true
---

# {{ title }}

Slides (Presentations)

Convert Markdown into presentations:

markflow build slides.md -o slides.html --format slides
---
title: Product Overview
format: slides
---

# Slide 1: Product Overview

This is the content of the first slide.

---

# Slide 2: Core Features

- Feature One
- Feature Two
- Feature Three

---

# Slide 3: Thank You

Thanks for watching!

💡 Design Philosophy & Roadmap

Design Philosophy

  • Pure Python: No third-party libraries, minimizing installation and deployment complexity
  • Zero dependencies: From installation to execution, no additional system libraries or Python packages are needed
  • CJK-first typography: Deep optimization for Chinese, Japanese, and Korean typesetting scenarios
  • Progressive enhancement: Basic features work out of the box; advanced features are enabled on demand
  • Security first: Built-in sandbox mechanism to prevent template injection attacks

Roadmap

  • Additional output formats (PDF, DOCX)
  • Theme system with custom styles
  • Plugin marketplace and community ecosystem
  • VS Code editor extension
  • Web-based online editor
  • More built-in functions and filters

📦 Build & Deploy Guide

Build HTML

# Build a full HTML document
markflow build document.md -o output.html

# Output only the HTML body (without head/body tags)
markflow build document.md -o output.html --format body

Build Slides

markflow build slides.md -o slides.html --format slides

Watch Mode

# Watch for file changes and rebuild automatically
markflow build document.md -o output.html --watch

CI/CD Integration

# GitHub Actions Example
name: Deploy Docs
on:
  push:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"
      - run: pip install markflow
      - run: markflow build docs/index.md -o index.html
      - uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./

🤝 Contributing

We welcome contributions of all kinds! Whether it's reporting bugs, improving documentation, or developing new features.

Submitting a Pull Request

  1. Fork this repository
  2. Create a feature branch: git checkout -b feature/my-feature
  3. Commit your changes: git commit -m "feat: add new feature description"
  4. Push the branch: git push origin feature/my-feature
  5. Submit a Pull Request

PR Format Convention

Please follow the Conventional Commits specification for commit messages:

<type>(<scope>): <description>

[optional body]

[optional footer]

Types: feat | fix | docs | style | refactor | test | chore

Submitting an Issue

When submitting an issue, please include the following information:

  • Problem description: Clearly describe the issue you encountered
  • Steps to reproduce: List the minimal steps to reproduce the problem
  • Expected behavior: Describe the expected correct behavior
  • Environment info: Operating system, Python version, MarkFlow version
  • Minimal example: If possible, provide a minimal reproducible code snippet

📄 License

This project is open-sourced under the MIT License.

MIT License

Copyright (c) 2026 MarkFlow Contributors

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, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

Built with ❤️ by the MarkFlow team

About

✨ Lightweight Programmable Markdown Typesetting Engine - Add variables, functions, conditions, and loops to Markdown. Zero dependencies, plugin system, CJK support, slides output.

Resources

License

Contributing

Stars

Watchers

Forks

Releases

No releases published

Packages

 
 
 

Contributors

Languages