refine-markdown-to-mkdocs
Transforms raw, scattered reading notes into structured, high-density knowledge modules. Unlike the Formatter, this Skill IS ALLOWED to delete, merge, add (minor), or rewrite content flexibily for clarity and brevity.
Core Principle: Domain-Adaptive Structuring, Category-Specific Logic, Controlled Fidelity and High-Density Output.
Workflow
Step 1: Read & Detect category or content type
Read the input file. Identify the source material (Book Title, Author, Nation, Chapter, Genre, Style).
You MUST classify it into the following categories (quick reference):
- 1. Philosophy theory, thoughts
- Plays (tragedy, comedy, stage play etc)
- Novels
- Poetry (epic, sonnet,lyric, narrative, satirical etc.)
- Literary Theory and Criticism (poem/novel/prose/play etc. theories)
- Prose
- History and history notes
- Art Theory and collections
- Biography (philosophers, celebrities, leaders etc.)
- Programming and Computer Science (Artificial Intelligence, Deep Learning, Large Language Models etc.)
- Mathematical models and theory (Operations Research, Linear Algebra, Calculus, Algorithms etc)
- Integration of materials without a clear focus
- Others (notes that don't belong to any of the above)
Sure about category:
Pause and ask the user for confirmation to continue, present:
CODEBLOCK0
INLINECODE0 for yes and N for no. If N, If not, enumrate the full categories to user with numebr in front and ask user to pick one. Note your recommended one with (recommended).
Not sure or ambigous about category:
Pause and ask the user: "Mutliple categories covered. What genre or category do you believe it belongs to?" Generate 2~3 different categories candidates, present to user:
CODEBLOCK1
The category you present and user select MUST be in the given categories. If not, enumrate the full categories to user with numebr in front and ask user to pick one. Note your recommended one with INLINECODE6
Step 2: Semantic Clustering (Analysis)
Based on category chosen in Step.1, view the classification rules of the specific category in references/notes_classify.md. The category-specific Primary Focus and High/Medium/Low Value Classification Rules are the guidelines you follow.
For example, category Novels follows:
CODEBLOCK2
After your analysis and cluster, save your plans in the Output Plan File: INLINECODE8
Structure:
CODEBLOCK3
Pause for User Confirmation:
Show the plan. Ask: "Proceed with this refinement structure? (Yes/No/Edit)"
Step 3: Content Reconstruction (The Core)
Generate the refined content based on the approved plan.
Writing Rules:
- 1. One Block, One Idea: Each semantic cluster becomes one Admonition block.
- Summary First: Every Admonition must start with a 1-sentence summary (bolded or as title).
- Merge Smoothly: When combining snippets, rewrite transitions so it reads like a coherent paragraph, not a list of quotes.
- Preserve Voice: If it's literature, keep the emotional tone. If non-fiction, keep the logical precision, if philosophy, follow strict logic, etc.
- No Hallucination: Do not add new knowledge not found in the notes. Only clarify existing knowledge.
Apply formatting guided by the Step 2 analysis to make markdown text prettier. Encouraged to use different styles to make text prettier. The goal is making the content scannable and the key points impossible to miss.
Formatting toolkit:
| Element | When to use | Format |
|---|
| Headings | Natural topic boundaries, section breaks | INLINECODE9 , ### hierarchy |
| Bold |
Key conclusions, important terms, core takeaways |
**bold** |
| Unordered lists | Parallel items, feature lists, examples |
- item |
| Ordered lists | Sequential steps, ranked items, procedures |
1. item |
| Highlights | Critical details, important comparisons for quick and short attention |
==text== |
| Color highlight | Colored emphasis where standard bold are insufficient |
<span style="color:red;font-weight:bold">text</span> |
| Tables | Comparisons, structured data, option matrices | Markdown table |
| Code | Commands, file paths, technical terms, variable names | `
inline
or fenced blocks |
| Blockquotes | Notable quotes, important warnings, cited text | > blockquotes
|
| Admonition | More notable quotes, definition, examples, conclusion | Follow **Admonition Syntax Rules** below. |
| Separators | Major topic transitions | ---
|
For Unordered lists, Ordered lists (e.g., - TEXT
and 1. TEXT
), there MUST be one empty line before the very beginning and one empty line after the end.
- Correct Format:
CODEBLOCK4
- Incorrect Format (DO NOT DO THIS):
CODEBLOCK5
For Admonition you created, strictly follows **Admonition Syntax Rules** below.
**Admonition Syntax Rules**
Strict Enforcement. When using MkDocs-style admonitions (e.g., !!! note
, !!! example
, !!! warning
), you must follow these indentation rules strictly. Markdown parsers require content inside blocks to be indented.
- Correct Format:
CODEBLOCK6
- Incorrect Format (DO NOT DO THIS):
CODEBLOCK7
Syntax rules:
1. **Indentation**: All content belonging to the admonition must be indented **4 spaces** relative to the !!!`.
- 2. Paragraph Breaks: Blank lines inside the block must also be indented (or simply ensure the next paragraph starts with 4 spaces).
- Nested Lists/Code: If using lists or code inside an admonition, indent them 8 spaces total.
- Consistency: Do not mix tabs and spaces. Use 4 spaces consistently.
CODEBLOCK8
Refinement Complete
Stats:
- - Original Snippets: X
- Refined Blocks: Y
- Deletion Rate: Z%
Major Mergers:
- - [Theme A]: Merged 5 snippets into 1 block
- [Theme B]: Merged 3 snippets into 1 block
Deleted Content (Summary):
- - Removed 10+ repetitive observations about [Character X]
- Removed incomplete thoughts regarding [Topic Y]
Files:
- - Plan: {filename}-plan.md
- Refined: {filename}-refined.md
CODEBLOCK9
refine-markdown-to-mkdocs
将原始、零散的阅读笔记转化为结构化、高密度的知识模块。与格式化工具不同，此技能允许灵活地删除、合并、添加（少量）或重写内容，以确保清晰和简洁。
核心原则：领域自适应结构化、类别特定逻辑、受控保真度与高密度输出。
工作流程
第一步：读取并检测类别或内容类型
读取输入文件。识别源材料（书名、作者、国籍、章节、体裁、风格）。
你必须将其归类到以下类别中（快速参考）：
- 1. 哲学理论、思想
- 戏剧（悲剧、喜剧、舞台剧等）
- 小说
- 诗歌（史诗、十四行诗、抒情诗、叙事诗、讽刺诗等）
- 文学理论与批评（诗歌/小说/散文/戏剧等理论）
- 散文
- 历史与历史笔记
- 艺术理论与收藏
- 传记（哲学家、名人、领袖等）
- 编程与计算机科学（人工智能、深度学习、大语言模型等）
- 数学模型与理论（运筹学、线性代数、微积分、算法等）
- 无明确焦点的材料整合
- 其他（不属于以上任何类别的笔记）
确定类别：
暂停并向用户确认是否继续，呈现：
markdown
检测到一个类别。
确认，或选择自定义类别：(Y/N)
Y 表示“是”，N 表示“否”。如果为 N，则向用户列出完整类别（前面带数字），并让用户选择一个。用 (推荐) 标注你推荐的类别。
不确定或类别模糊：
暂停并向用户询问：“涉及多个类别。您认为它属于哪种体裁或类别？” 生成 2~3 个不同的候选类别，呈现给用户：
选择一个体裁：
- 1. [类别A] - (推荐)
- [类别B] - (类别说明)
- [类别C] - (类别说明)
输入数字，或输入自定义类别：
你呈现以及用户选择的类别必须在给定的类别列表中。如果不是，则向用户列出完整类别（前面带数字），并让用户选择一个。用 (推荐) 标注你推荐的类别。
第二步：语义聚类（分析）
基于第一步中选择的类别，查看 references/notes_classify.md 中该特定类别的分类规则。类别特定的主要关注点以及高/中/低价值分类规则是你遵循的指南。
例如，小说类别遵循：
markdown
主要关注点： 叙事声音、人物塑造、主题深度、文体手法。
分类规则：
- 1. 高价值： 人物弧光（心理演变）、叙事视角转换、象征意象、作者风格印记、评论界反响。 -> 保留并润色
- 中价值： 情节要点、场景细节、次要人物简介、事件时间线。 -> 合并并总结
- 低价值： 次要情节细节、冗余总结、缺乏文本依据的主观情感宣泄。 -> 删除（在报告中记录）
分析和聚类后，将你的计划保存到输出计划文件：{文件名}-plan.md
结构：
markdown
优化计划
聚类 1：[主题名称]
- - 来源片段：[行号或引用]
- 操作：合并为 1/2/3 个 Admonition 块
- 草稿摘要：[一句话]
聚类 2：[主题名称]
...
删除列表
暂停等待用户确认：
展示计划。询问：“是否按此优化结构继续？(是/否/编辑)”
第三步：内容重构（核心）
基于已批准的计划生成优化后的内容。
写作规则：
- 1. 一块一意：每个语义聚类对应一个 Admonition 块。
- 摘要先行：每个 Admonition 必须以1 句话摘要（加粗或作为标题）开头。
- 平滑合并：合并片段时，重写过渡语句，使其读起来像连贯的段落，而非引用列表。
- 保留风格：如果是文学作品，保留情感基调；如果是非虚构作品，保留逻辑严谨性；如果是哲学内容，遵循严格逻辑，依此类推。
- 禁止幻觉：不要添加笔记中未出现的新知识。仅澄清已有知识。
应用第二步分析指导的格式，使 Markdown 文本更美观。鼓励使用不同风格使文本更美观。目标是使内容易于浏览，关键点一目了然。
格式工具箱：
| 元素 | 使用时机 | 格式 |
|---|
| 标题 | 自然主题边界、章节分隔 | ##、### 层级 |
| 加粗 |
关键结论、重要术语、核心要点 |
加粗 |
| 无序列表 | 并列项、功能列表、示例 | - 项目 |
| 有序列表 | 顺序步骤、排名项、流程 | 1. 项目 |
| 高亮 | 关键细节、重要比较（快速简短注意） | ==文本== |
| 颜色高亮 | 标准加粗不足以强调时使用的彩色强调 |
文本 |
| 表格 | 比较、结构化数据、选项矩阵 | Markdown 表格 |
| 代码 | 命令、文件路径、技术术语、变量名 | 行内 或围栏块 |
| 块引用 | 值得注意的引用、重要警告、引文 | > 块引用 |
| Admonition | 更值得注意的引用、定义、示例、结论 | 遵循下面的
Admonition 语法规则。 |
| 分隔线 | 主要主题转换 | --- |
对于无序列表、有序列表（例如 - 文本 和 1. 文本），开头前必须有一个空行，结尾后也必须有一个空行。
markdown
这是前面的文本。
- - 这是项目符号 1；(正确，前面有 1 个空行)
- 这是项目符号 2；
这是后面的行（正确）。
这是前面的文本。
- - 这是项目符号 1；(错误！前面必须有 1 个空行)
- 这是项目符号 2；
这是后面的行（错误！项目符号后面没有空行）。
对于你创建的 Admonition，严格遵循下面的 Admonition 语法规则。
Admonition 语法规则
严格执行。使用 MkDocs 风格的 Admonition（例如 !!! note、!!! example、!!! warning）时，必须严格遵循以下缩进规则。Markdown 解析器要求块内的内容进行缩进。
markdown
!!! note 标题文本
这是内容。必须以 4 个空格开头，并且上面一行是空行。
这是第二段。它也需要 4 个空格的缩进。
- 列表项也遵循此规则。结尾行下方应有一个无缩进的空行。
- 列表项也遵循此规则。
这是 Admonition 外部的行（正确）。
markdown
!!! note 标题文本
此内容没有缩进。（错误 - 违反缩进规则）
!!! note 标题文本
第一段没问题。
第二段没有缩进。（错误 - 破坏了块结构）
语法规则：
- 1. 缩进：所有属于 Admonition 的内容必须相对于 !!! 缩进 4 个空格。
- 段落分隔：块内的空行也必须缩进（或者确保下一段以 4 个空格开头）。
- 嵌套列表/代码：如果在 Admonition 内使用列表或代码，则总共缩进 8 个空格。
- 一致性：不要混用制表符和空格。始终使用 4 个空格。
第四步：保存与备份
保存为 {文件名}-refined.md。
如果存在已优化的文件，则进行备份（逻辑与格式化工具相同）。
第五步：完成报告
专门报告内容变更：
优化完成
统计信息：
主要合并：
- - [主题A]：将 5 个片段合并为 1 个块
- [主题B]：将 3 个片段合并为 1 个块
已删除内容（摘要）：
