description: Formatting rules for artifact markdown, covering .md deliverables, reports, and content exported to PDF or Word.
builders: file
kinds: markdown, pdf, document

Markdown formatting for artifact files / 工件文件的 Markdown 格式

These rules apply to artifact markdown: .md deliverables, reports, and any artifact content
that may be exported to PDF or Word.

这些规则适用于工件 Markdown：.md 交付物、报告，以及任何可能导出为 PDF 或 Word 的工件内容。

Tables:

• Cap cell content at ~25 characters. If a cell needs more, abbreviate or move details to a footnote below the table.
  单元格内容控制在约 25 个字符以内。如果需要更多内容，进行缩写，或把细节移到表格下方的脚注中。
• No full sentences in cells. Use short phrases, keywords, or values only.
  单元格中不写完整句子。只使用短语、关键词或数值。
• No URLs in table cells. Put links in a "Sources" section or footnotes below.
  表格单元格中不放 URL。把链接放在下方的 "Sources"（来源）小节或脚注中。
• 3-4 columns max. If you need more, split into multiple tables or use a definition list.
  最多 3-4 列。如果需要更多列，拆分成多个表格或改用定义列表。
• Right-align numeric columns with ---: for scannability.
  数值列用 ---: 右对齐，便于扫读。

Lists:

• One blank line between top-level bullets when each item has a sub-description or is longer than a few words.
  当每个顶级列表项带有子描述或长度超过几个词时，项与项之间空一行。
• No blank line between sub-bullets; keep them tight under their parent.
  子列表项之间不空行；让它们紧贴各自的父项。
• Bold the lead phrase, then follow with the description: **Thing**: explanation here.
  加粗引导短语，后接描述：**Thing**: explanation here。
• Max 2 levels of nesting. If you need a third level, restructure into sections with headers.
  最多嵌套 2 层。如果需要第三层，改用带标题的小节结构。

Emojis:

• No emojis in exportable documents (.md files intended for PDF/Word conversion). They render as boxes or missing glyphs in most PDF engines.
  可导出的文档（用于转换为 PDF/Word 的 .md 文件）中不使用表情符号。在大多数 PDF 引擎中，它们会渲染成方框或缺字。
• Use text markers instead: **Note:** for callouts, --> for flow, plain * bullets, --- for dividers.
  改用文本标记：提示用 **Note:**，流程用 -->，列表用普通 *，分隔线用 ---。
• Section headers in .md files: use plain text (## Design), not emoji-prefixed (## 🎨 Design).
  .md 文件中的小节标题用纯文本（## Design），不要加表情符号前缀（## 🎨 Design）。

General:

• Use --- horizontal rules between major sections for visual breathing room.
  在主要小节之间使用 --- 水平分隔线，留出视觉呼吸空间。
• Use > [!NOTE] / > [!WARNING] / > [!TIP] for callouts on GitHub. For portable output, use **Note:** bold prefixes.
  在 GitHub 上使用 > [!NOTE] / > [!WARNING] / > [!TIP] 作为提示框。为保证可移植性，使用 **Note:** 粗体前缀。
• Sentence case for headings (## Key findings), not title case unless it's a proper title.
  标题使用句首大写格式（## Key findings），除非是正式名称，否则不用标题式大小写。

【评论】禁用表情符号源于 PDF 渲染的字体兼容性问题（缺字方框），属于工程性排版约束而非内容规范。