From ef2db26b7309f929282ebd46acf82dc5a87614f8 Mon Sep 17 00:00:00 2001
From: 魏曹先生 <1992414357@qq.com>
Date: Tue, 10 Feb 2026 05:05:41 +0800
Subject: Rewrite README with new structure and examples

---
 README.md       | 173 +++++++++++++++++++++++++++++++++++---------------------
 README_zh_CN.md | 171 ++++++++++++++++++++++++++++++++++---------------------
 2 files changed, 216 insertions(+), 128 deletions(-)

diff --git a/README.md b/README.md
index 00aba64..00dbecd 100644
--- a/README.md
+++ b/README.md
@@ -2,109 +2,152 @@
 
 > Write your story with Markdown!
 
-> [!WARNING]
-> This article is translated from `README_zh_CN.md`
+## Some Ramblings
+
+This is a personal learning project of mine. To quickly achieve the desired effect, the project experimentally uses **Vibe Coding**.
+
+## Introduction
+
+MarkDialog is a **paradigm for writing textual narratives**. It defines how to use **Markdown** to describe dialogue for text adventure games.
+
+It allows you to:
+
+- Use **level-six headings** to represent characters.
+- Use **headings** to represent paragraphs.
+- Use **hyperlinks** to represent jumps.
+- Use **code blocks** to control speed, visuals, and interact with game content.
 
 > [!NOTE]
-> This is a project I tinkered with in my spare time, and many aspects are still rough around the edges.
+> If you want to learn about MarkDialog syntax, click here.
 >
-> I also experimentally used **Vibe Coding** in it, so you might encounter some unconventional code. Please bear with me.
+> [MarkDialog Example Article](#example-article)
 
-## Why MarkDialog?
+## Toolchain
 
-The starting point for this project was actually quite simple: I wanted to prototype an AVG visual novel and needed people around me to **be able to start writing the story immediately**.
+MarkDialog provides a compilation tool `mdialogc`, which can compile your **Markdown** files into an intermediate language for fast playback or execution on any frontend.
 
-But the reality is:
+```bash
+# Execution, will output YourMarkdown.dialog
+mdialogc -i YourMarkdown.md
+```
 
-- Graphical editors are too heavy.
-- Ink and Yarn Spinner are powerful, but both require learning.
-- Writing in JSON / XML / custom DSLs isn't "natural" enough.
+Currently supported frontends:
 
-What I really wanted was a format that people already know how to write, requires no learning, can be opened and written in immediately, and can be run right after writing.
+- [Rust](#rust-example)
 
-Then it suddenly hit me:
+## Other
 
-### Isn't Markdown exactly that?
+#### Example Article
 
-You can easily write it in **Typora**, **Obsidian**, **VS Code**, or even **Vim/NeoVim**.
+```markdown
+# Dialogue
 
-> What more could you ask for?
+###### Alice
 
-When this idea popped into my head, I got really excited.
+Good morning, Bob.
 
-And so, MarkDialog was born.
+Have you had breakfast?
 
+- [Of course I have!](#Bob-has-had-breakfast)
+- [Not yet.](#Bob-has-not-had-breakfast)
+- [I'm not hungry.](#Bob-is-not-hungry)
 
+## Bob-has-had-breakfast
 
-## What is MarkDialog?
+###### Bob
 
-It allows you to:
+I certainly **had breakfast**!
 
-- Use level-six headings to switch characters.
-- Use regular Markdown for dialogue lines.
-- Use lists for choices.
-- Use links for jumps.
-- Use code blocks for rich text controls like speed, color, and actions.
-- Use images to change backgrounds.
+###### Alice
 
-The Markdown you write is compiled into an IR (Intermediate Representation), which can then be parsed anywhere you want!
+*Oh.* I was hoping you'd join me.
 
-For example:
+###### Narrator
 
-- Inline it into a Rust project.
-- Import it into Unity / Unreal / Godot.
-- Convert it to JSON.
-- Convert it to anything.
+(Story ends)
 
+## Bob-has-not-had-breakfast
 
+###### Bob
 
-## MarkDialog Syntax?
+Not yet.
 
-Generally speaking, if you know how to write Markdown, you know how to write MarkDialog.
+###### Alice
 
-You can write:
+[Great! Want to go get breakfast together?](#Alice-asks-to-eat-breakfast-together)
 
-```
-# Title
-> Use blockquotes for comments
+## Bob-is-not-hungry
 
-###### Zhang San
-Use a level-six heading for **character names**.
+###### Bob
 
-Use unordered lists for choices
-- Good morning
-- Good afternoon
-- Good evening
+*I'm actually not hungry*?
 
-Ordered lists work too
-1. Good morning
-2. Good afternoon
-3. Good evening
+###### Alice
 
-> Use hyperlinks for jumps
-What's for lunch?
-- Pizza [](#Eat_Pizza)
-- Pasta [](#Eat_Pasta)
-- Nothing
-Or *eat nothing at all*!
+Never mind then, what a pity today. (*muttering quietly*)
 
-## Eat_Pizza
-Eat pizza
+###### Narrator
 
-## Eat_Pasta
-Eat pasta
+(Story ends)
 
-> Use images to switch backgrounds
-![](backgrounds/park)
+## Alice-asks-to-eat-breakfast-together
 
-> Use the following method to inline other files!
-[[branch.md]]
-```
+###### Bob
 
-It's that simple!
+Let me think...
 
+- Let's go!
+- No, I'm [not hungry](#Bob-is-not-hungry)
 
+###### Alice
 
-## Open Source License
+Great! Let's go!
 
-Haha, I'm using the MIT License. Feel free to play around with it!
+###### Narrator
+
+(And so Bob and Alice had breakfast together)
+
+(Story ends)
+```
+
+#### Rust Example
+
+```toml
+# Cargo.toml
+[package]
+name = "your_proj"
+version = "0.1.0"
+edition = "2024"
+
+[dependencies]
+markdialog = { git = "https://github.com/CatilGrass/MarkDialog" }
+```
+
+```rust
+// main.rs
+use markdialog::generate::{markdialog, step};
+
+markdialog!(my = "alice_and_bob.dialog");
+
+fn main() {
+    let my_step = my::get_step(step!("Bob-has-had-breakfast")).unwrap();
+    let sentence = my_step.sentences[0];
+    println!(
+        "{} said : \"{}\"",
+        sentence.character.unwrap_or_default(),
+        sentence
+            .content_tokens
+            .iter()
+            .map(|token| match token {
+                my::Token::Text(t) => t,
+                my::Token::BoldText(t) => t,
+                my::Token::ItalicText(t) => t,
+                my::Token::BoldItalicText(t) => t,
+                _ => "",
+            }
+            .to_string())
+            .collect::<Vec<String>>()
+            .join("")
+    )
+}
+```
diff --git a/README_zh_CN.md b/README_zh_CN.md
index c7210b2..8ab91ba 100644
--- a/README_zh_CN.md
+++ b/README_zh_CN.md
@@ -2,109 +2,154 @@
 
 > 用 Markdown 来书写您的剧情！
 
+## 一些碎碎语
+
+这是一个我个人用于学习的项目，为了快速实现我想要的效果，项目中实验性地使用了 **Vibe Coding**
+
+## 介绍
+
+MarkDialog 是 **书写文字剧情的范式**，它定义了如何用 **Markdown** 来描述文字冒险游戏的对话。
+
+它允许你：
+
+- 使用 **六级标题** 表示角色
+- 使用 **标题** 表示段落
+- 使用 **超链接** 表示跳转
+- 使用 **代码块** 来控制速度、画面，与游戏内容互动
+
 > [!NOTE]
-> 这是我闲暇时间折腾出来的项目，很多地方还没打磨好。
+> 如果你想了解 Markdialog 的语法，可以点击此处
 >
-> 另外我在里面实验性地使用了 **Vibe Coding**，所以你可能会看到一些不太正经的代码，请多包涵。
+> [Markdialog 示例文章](#示例文章)
 
-## 为什么会有 MarkDialog？
+## 工具链
 
-这个项目的起点其实很简单： 我想做一个 AVG 视觉小说的原型，需要让身边的人**能立刻上手写剧情**。
+MarkDialog 提供了编译工具 `mdialogc`，它可以将您的 **Markdown** 文件编译成中间语言，以快速地在任何前端播放或执行。
 
-但现实是：
+```bash
+# 执行，将会输出 YourMarkdown.dialog
+mdialogc -i YourMarkdown.md
+```
 
-- 图形化编辑器太重
-- Ink、Yarn Spinner 虽然强大，但都需要学习
-- JSON / XML / 自定义 DSL 写起来都不够 “自然”
+目前支持的前端：
 
-我真正想要的是一种大家已经会写、不需要学习、打开就能写、写完就能跑的格式。
+- [Rust](#Rust 示例)
 
-然后我突然想到：
+## 其他
 
-### Markdown 不就是这样的吗？
+#### 示例文章
 
-你可以在 **Typora**、**Obsidian**、**VS Code** 甚至 **Vim/NeoVim** 里轻松地编写他们
+```markdown
+# 对话
 
-> 还要什么自行车？
+###### 爱丽丝
 
-当这个念头冒出来的时候，我整个人都兴奋了。 
+早上好，鲍勃。
 
-于是，MarkDialog 就这样诞生了。
+你吃早饭了么？
 
+- [当然吃了！](#鲍勃吃过了早饭)
+- [并没。](#鲍勃还没吃早饭)
+- [我还不饿。](#鲍勃并不饿)
 
+## 鲍勃吃过了早饭
 
-## MarkDialog 是什么？
+###### 鲍勃
 
-它让你可以：
+我当然**吃了早饭**！
 
-- 用六级标题切换角色
-- 用普通 Markdown 写台词
-- 用列表写选项
-- 用链接写跳转
-- 用代码块写速度、颜色、动作等富文本控制
-- 用图片切换背景
+###### 爱丽丝
 
-你写的 Markdown 会被编译成一个 IR，然后解析到任何地方，只要你想！
+*哦。*我还想你跟我一起去吃呢。
 
-比如
+###### 旁白
 
-- 内联到 Rust 项目
-- 导入 Unity / Unreal / Godot
-- 转换为 Json
-- 转换为任何东西
+(剧情结束)
 
+## 鲍勃还没吃早饭
 
+###### 鲍勃
 
-## MarkDialog 的语法？
+并没吃。
 
-一般来讲，只要你会写 Markdown，你就会写 Markdialog
+###### 爱丽丝
 
-你可以：
+[好啊！一起去吃早饭么？](#爱丽丝询问是否一起吃早饭)
 
-```
-# 标题
-> 使用引用块表示注释
+## 鲍勃并不饿
 
-###### 张三
-使用六级标题表示**角色名称**
+###### 鲍勃
 
-使用无序列表表示选项
-- 早上好
-- 中午好
-- 晚上好
+*我其实不饿*？
 
-有序也行
-1. 早上好
-2. 中午好
-3. 晚上好
+###### 爱丽丝
 
-> 使用超链接表示跳转
-中午吃？
-- 披萨 [](#Eat_Pizza)
-- 意面 [](#Eat_Pasta)
-- 不吃
-或者 *什么都不吃*！
+那算了，今天太遗憾了。（*小声嘟囔*）
 
-## Eat_Pizza
-吃披萨
+###### 旁白
 
-## Eat_Pasta
-吃意面
+(剧情结束)
 
-> 使用图像来切换背景
-![](backgrounds/park)
+## 爱丽丝询问是否一起吃早饭
 
-> 使用如下方式来内联其他文件！
-[[branch.md]]
-```
+###### 鲍勃
 
-就是如此简单！
+让我想想。。。
 
+- 走吧！
+- 算了，我[并不饿](#鲍勃并不饿)
 
+###### 爱丽丝
 
+好啊！走吧！
 
+###### 旁白
 
-## 开源协议
+（于是鲍勃和爱丽丝一起吃了早饭）
 
-哈哈，我采用 MIT License，放心玩去吧！
+（剧情结束）
+```
+
+#### Rust 示例
+
+```toml
+# Cargo.toml
+[package]
+name = "your_proj"
+version = "0.1.0"
+edition = "2024"
+
+[dependencies]
+markdialog = { git = "https://github.com/CatilGrass/MarkDialog" }
+```
+
+```rust
+// main.rs
+use markdialog::generate::{markdialog, step};
+
+markdialog!(my = "alice_and_bob.dialog");
+
+fn main() {
+    let my_step = my::get_step(step!("鲍勃吃过了早饭")).unwrap();
+    let sentence = my_step.sentences[0];
+    println!(
+        "{} said : \"{}\"",
+        sentence.character.unwrap_or_default(),
+        sentence
+            .content_tokens
+            .iter()
+            .map(|token| match token {
+                my::Token::Text(t) => t,
+                my::Token::BoldText(t) => t,
+                my::Token::ItalicText(t) => t,
+                my::Token::BoldItalicText(t) => t,
+                _ => "",
+            }
+            .to_string())
+            .collect::<Vec<String>>()
+            .join("")
+    )
+}
+
+```
 
-- 
cgit