syncfusion-dotnet-markdown

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Markdown Document Processing

Markdown文档处理

Overview

概述

Create, edit, and convert Markdown (.md) files using the Syncfusion Markdown Library. This skill supports two operational modes — generating C# code for the user's project or executing tasks directly through a CSX script.

使用Syncfusion Markdown库创建、编辑和转换Markdown（.md）文件。本技能支持两种操作模式——为用户项目生成C#代码，或直接通过CSX脚本执行任务。

Key Capabilities

核心功能

Create & Edit: paragraphs, headings, lists, tables, images, hyperlinks, code blocks, blockquotes, task lists
Parse & Modify: load from files/streams, iterate and update blocks and inlines
Serialization: convert Markdown document models back to plain Markdown text and write to files
Advanced Features: custom parsing events, image loading handlers, nested lists, task list support

创建与编辑： 段落、标题、列表、表格、图片、超链接、代码块、块引用、任务列表
解析与修改： 从文件/流加载，遍历并更新块级和内联元素
序列化： 将Markdown文档模型转换回纯Markdown文本并写入文件
高级特性： 自定义解析事件、图片加载处理器、嵌套列表、任务列表支持

Prerequisites

前提条件

.NET SDK 8+ and

dotnet-script

dotnet tool install -g dotnet-script

Syncfusion License: https://www.syncfusion.com/products/communitylicense

.NET SDK 8+ 和

dotnet-script

：

dotnet tool install -g dotnet-script

Syncfusion许可证：https://www.syncfusion.com/products/communitylicense

Quick Start Examples

快速开始示例

Example 1: Generate Code (Mode 1)

示例1：生成代码（模式1）

User: "Show me how to create a Markdown document with a table"

Result: C# code snippet displayed (no files created)

用户： "展示如何创建带表格的Markdown文档"

结果： 显示C#代码片段（不创建文件）

Example 2: Execute Task (Mode 2)

示例2：执行任务（模式2）

User: "Create a Markdown file at output/report.md"

Result: Physical file created at specified path (via temporary CSX script)

用户： "在output/report.md路径创建Markdown文件"

结果： 在指定路径创建物理文件（通过临时CSX脚本）

Two Modes — Choose Based on User Intent

两种模式——根据用户意图选择

Before choosing a mode, infer what the user wants to accomplish:

选择模式前，请先推断用户的目标：

Mode 1: Generate C# Code for the User's Project (default)

模式1：为用户项目生成C#代码（默认）

Use this mode when the user wants to view, write, review, refactor, or modify C# code related to Markdown processing.

Trigger keywords: "show me how", "how to", "how can I", "how do I", "provide code", "provide an example", "give an example", "demonstrate", "code snippet", "sample code", "example", "sample", "give me", "show me", "Program.cs", "example code", "generate code for", "codesnippet"

Workflow:

当用户希望查看、编写、审阅、重构或修改与Markdown处理相关的C#代码时，使用此模式。

触发关键词： "show me how", "how to", "how can I", "how do I", "provide code", "provide an example", "give an example", "demonstrate", "code snippet", "sample code", "example", "sample", "give me", "show me", "Program.cs", "example code", "generate code for", "codesnippet"

工作流程：

Step 1 — Detect the Application Type and Suggest the Correct NuGet Package(s)

步骤1 — 检测应用类型并推荐正确的NuGet包

Inspect the workspace project files (
```
.csproj
```
,
```
web.config
```
,
```
App.config
```
,
```
Startup.cs
```
,
```
Program.cs
```
, etc.) and use the detection signals table in
```
references/nuget-packages.md
```
to identify the application type.
Look up the correct package(s) from
```
references/nuget-packages.md
```
based on the detected app type and tell the user to install them before generating any code.

检查工作区项目文件（
```
.csproj
```
、
```
web.config
```
、
```
App.config
```
、
```
Startup.cs
```
、
```
Program.cs
```
等），使用
```
references/nuget-packages.md
```
中的检测信号表识别应用类型。
根据检测到的应用类型，从
```
references/nuget-packages.md
```
中查找正确的包，并告知用户在生成代码之前安装这些包。

Step 2 — Generate Code from Reference Files Only

步骤2 — 仅从参考文件生成代码

Do NOT invent, guess, or suggest any API, method, property, class, or namespace not explicitly present in the reference files.

Read the relevant
```
references/*.md
```
file(s) for the requested feature
Build C# code strictly from the APIs and snippets found in those files
Select the correct snippet variant based on the app type detected in Step 1:
- Windows-specific apps (WinForms, WPF, .NET Framework Console, ASP.NET MVC4/5, UWP) → use Windows-specific snippets
- Cross-platform apps (ASP.NET Core, .NET Core/.NET 5+ Console, Blazor, MAUI, Xamarin) → use cross-platform /
```
.Net.Core
```
  snippets
Do not create or run any
```
.csx
```
script

不得发明、猜测或建议任何未在参考文件中明确提及的API、方法、属性、类或命名空间。

读取与所需功能相关的
```
references/*.md
```
文件
严格基于这些文件中的API和代码片段构建C#代码
根据步骤1中检测到的应用类型选择正确的代码片段变体：
- Windows专属应用（WinForms、WPF、.NET Framework控制台、ASP.NET MVC4/5、UWP）→ 使用Windows专属代码片段
- 跨平台应用（ASP.NET Core、.NET Core/.NET 5+控制台、Blazor、MAUI、Xamarin）→ 使用跨平台/
```
.Net.Core
```
  代码片段
不得创建或运行任何
```
.csx
```
脚本

Mode 2: Execute via CSX Script (does not modify project files)

模式2：通过CSX脚本执行（不修改项目文件）

Use this mode only when the user explicitly requests execution, file generation, or a fully produced output (such as a completed md file).

Trigger keywords: "create a markdown document", "make a markdown file", "generate markdown", "parse markdown", "convert markdown to HTML", "open", "edit", "modify", "change" a

.md

file, "without modifying my project", "run a csx script", or when the user provides a file path (e.g.,

output/report.md

Workflow:

仅当用户明确要求执行、生成文件或生成完整输出（如已完成的md文件）时，才使用此模式。

触发关键词： "create a markdown document", "make a markdown file", "generate markdown", "parse markdown", "convert markdown to HTML", "open", "edit", "modify", "change" a

.md

file, "without modifying my project", "run a csx script"，或当用户提供文件路径时（例如

output/report.md

）。

工作流程：

Step 1 — Create Temp CSX Script

步骤1 — 创建临时CSX脚本

Start with
```
references/template.csx
```
as the base

Create at:

{skill-root}/syncfusion-dotnet-markdown/scripts/temp-{uniqueId}.csx

(e.g.,

skill-root

.codestudio/skills

)

Use random GUID for unique filename (e.g.,
```
temp-a3f7b2c1.csx
```
); never create in workspace root

以
```
references/template.csx
```
为基础

创建路径：

{skill-root}/syncfusion-dotnet-markdown/scripts/temp-{uniqueId}.csx

（例如

skill-root

.codestudio/skills

）

使用随机GUID作为唯一文件名（例如
```
temp-a3f7b2c1.csx
```
）；绝不能在工作区根目录创建

Step 2 — Build Script from Reference Files

步骤2 — 基于参考文件构建脚本

Do NOT invent APIs/methods not in reference files
Read relevant
```
references/*.md
```
file(s) and extract code snippets
Replace all placeholders: file paths, document properties, data values, field names, etc.

不得发明参考文件中未包含的API/方法
读取相关的
```
references/*.md
```
文件并提取代码片段
替换所有占位符：文件路径、文档属性、数据值、字段名等

Step 3 — Execute Script

步骤3 — 执行脚本

Run:

dotnet script {skill-root}/syncfusion-dotnet-markdown/scripts/temp-{uniqueId}.csx

Verify successful execution and capture any errors

运行命令：

dotnet script {skill-root}/syncfusion-dotnet-markdown/scripts/temp-{uniqueId}.csx

验证执行是否成功，并捕获所有错误

Step 4 — Clean Up and Report

步骤4 — 清理并报告

Delete the temp
```
.csx
```
file after execution
Report SUCCESS/ERROR with output file path(s) and any error messages with fixes

执行完成后删除临时
```
.csx
```
文件
报告执行成功/失败，包含输出文件路径以及任何错误信息和修复方案

Code References

代码参考

All templates and snippets are in the

references/

folder:

File	Contents
template.csx	Base CSX script structure (Mode 2 only)
document-structure.md	Create/load/save markdown documents, DOM structure, block and inline elements
create-markdown.md	Create markdown documents from scratch, add paragraphs, headings, formatting
parse-markdown.md	Parse markdown from files/streams, process blocks, iterate content, modify parsed documents
text-formatting.md	Apply bold, italic, strikethrough, code span, subscript, superscript formatting
headings-styles.md	Apply heading styles (H1-H6), paragraph styles, blockquotes
lists.md	Create numbered and bulleted lists, nested lists (up to 8 levels), list formatting
tables.md	Create tables with column alignments (left, center, right), add rows and cells
hyperlinks.md	Add hyperlinks with display text, URLs, and screen tips
images.md	Insert images from URLs or bytes, alt text, image formats, base64 encoding
code-blocks.md	Create fenced and indented code blocks, language specification
blockquotes.md	Create blockquotes with nesting levels
task-lists.md	Create task lists with checked/unchecked checkboxes (GitHub-style)
advanced-features.md	Advanced markdown features, custom parsing, events

所有模板和代码片段都位于

references/

文件夹中：

文件	内容
template.csx	基础CSX脚本结构（仅模式2可用）
document-structure.md	创建/加载/保存Markdown文档、DOM结构、块级和内联元素
create-markdown.md	从头创建Markdown文档、添加段落、标题、格式
parse-markdown.md	从文件/流解析Markdown、处理块级元素、遍历内容、修改已解析的文档
text-formatting.md	应用加粗、斜体、删除线、代码跨度、下标、上标格式
headings-styles.md	应用标题样式（H1-H6）、段落样式、块引用
lists.md	创建编号列表和项目符号列表、嵌套列表（最多8级）、列表格式
tables.md	创建带列对齐（左对齐、居中、右对齐）的表格、添加行和单元格
hyperlinks.md	添加带显示文本、URL和屏幕提示的超链接
images.md	从URL或字节插入图片、替代文本、图片格式、Base64编码
code-blocks.md	创建围栏式和缩进式代码块、语言指定
blockquotes.md	创建带嵌套级别的块引用
task-lists.md	创建带勾选/未勾选复选框的任务列表（GitHub风格）
advanced-features.md	Markdown高级特性、自定义解析、事件

Rules

规则

Output files go in
```
./output/
```
directory
Temp
```
.csx
```
scripts must be created inside
```
{skill-root}/syncfusion-dotnet-markdown/scripts/
```
— never in the workspace root or customer
```
scripts/
```
folder
Use license key from
```
SyncfusionLicense.txt
```
at workspace root or env var
```
SYNCFUSION_LICENSE_KEY
```
Never use Python libraries (e.g., python-markdown)
Never leave temp
```
.csx
```
files after execution

输出文件存放在
```
./output/
```
目录
临时
```
.csx
```
脚本必须创建在
```
{skill-root}/syncfusion-dotnet-markdown/scripts/
```
目录下——绝不能放在工作区根目录或客户的
```
scripts/
```
文件夹中
使用工作区根目录
```
SyncfusionLicense.txt
```
中的许可证密钥，或环境变量
```
SYNCFUSION_LICENSE_KEY
```
不得使用Python库（如python-markdown）
执行完成后不得保留临时
```
.csx
```
文件