写作格式的价值，不在于语法多，而在于文件离开编辑器之后仍能完整表达。

基础排版与 GFM

一段文字可以同时包含粗体、斜体、删除线、inline code 和 外部链接。

• 第一层列表
  • 第二层列表
    • 第三层列表
• 列表之后仍然保持稳定的段落节奏

1. 写作
2. 本地预览
3. 发布与验证

• 标题、引用、列表和代码
• 表格、删除线与任务列表
• 数学公式与 Mermaid
• 用新的真实文章继续回归测试

数学公式

行内公式会和文字一起流动，例如注意力的缩放项 $\frac{QK^\top}{\sqrt{d_k}}$。

块级公式支持多行对齐：

$$ \begin{aligned} \operatorname{Attention}(Q,K,V) &= \operatorname{softmax}\left(\frac{QK^\top}{\sqrt{d_k}}\right)V \ K_{\text{cache}}^{(t)} &= [K_{\text{cache}}^{(t-1)}; K_t] \ V_{\text{cache}}^{(t)} &= [V_{\text{cache}}^{(t-1)}; V_t] \end{aligned} $$

矩阵也能正常显示：

$$ X = \begin{bmatrix} 1 & 0 & 1 \ 0 & 1 & 0 \ 1 & 1 & 1 \end{bmatrix} $$

Mermaid 流程与时序

所有 Mermaid 图表固定使用「中性」主题。每张图都可以在「图表」与「Code」之间切换：前者用于阅读，后者用于检查或复制原始 Mermaid 语法。

下面的流程图描述本地写作到发布的闭环：

flowchart LR
  A[Typora 写作] --> B{本地验证}
  B -->|通过| C[生成内容索引]
  B -->|失败| A
  C --> D[构建网站]
  D --> E[浏览器验收]
  E --> F[发布]

同一篇文章里可以继续放更复杂的时序图：

sequenceDiagram
  autonumber
  participant W as Writer
  participant M as Markdown
  participant S as Site
  participant R as Reader
  W->>M: 保存 .md 与媒体
  M->>S: 构建内容与目录
  S-->>W: 返回预览
  W->>S: 发布已验证版本
  R->>S: 阅读文章
  S-->>R: HTML + KaTeX + Mermaid

多语言代码高亮

同一种内容结构，在不同语言里应该保留各自可辨识的关键字、类型、字符串、注释与数字层级。

TypeScript

type Post<TMeta extends Record<string, unknown>> = {
  slug: string;
  meta: TMeta;
};

async function publish<TMeta extends Record<string, unknown>>(
  post: Post<TMeta>,
): Promise<string> {
  const response = await fetch(`/api/posts/${post.slug}`, {
    method: "POST",
    body: JSON.stringify(post.meta),
  });
  return response.ok ? "published" : "failed";
}

Python

from dataclasses import dataclass
from pathlib import Path

@dataclass(frozen=True)
class Article:
    title: str
    source: Path

def published_titles(articles: list[Article]) -> list[str]:
    return [article.title for article in articles if article.source.exists()]

Rust

#[derive(Debug)]
struct Entry<'a> {
    title: &'a str,
    pinned: bool,
}

fn pinned_titles(entries: &[Entry<'_>]) -> Vec<&str> {
    entries.iter()
        .filter(|entry| entry.pinned)
        .map(|entry| entry.title)
        .collect()
}

Go

func renderAll(ctx context.Context, slugs []string) <-chan Result {
	results := make(chan Result)
	go func() {
		defer close(results)
		for _, slug := range slugs {
			results <- render(ctx, slug)
		}
	}()
	return results
}

SQL

WITH ranked_posts AS (
  SELECT
    title,
    topic,
    ROW_NUMBER() OVER (PARTITION BY topic ORDER BY published_at DESC) AS rank
  FROM posts
  WHERE status = 'published'
)
SELECT title, topic
FROM ranked_posts
WHERE rank <= 3;

Swift

actor ReadingProgress {
    private var offsets: [URL: Double] = [:]

    func save(_ offset: Double, for article: URL) {
        offsets[article] = max(0, offset)
    }

    func restore(for article: URL) -> Double {
        offsets[article, default: 0]
    }
}

Diff、图片与原生 HTML

- const publishing = "copy and paste";
+ const publishing = "content as source";

最后用一个脚注说明这篇文章的角色：它既是示例，也是未来升级 Markdown 依赖时的回归测试。[^regression]

[^regression]: 页面构建测试会检查公式与示例内容，浏览器验收会检查 Mermaid 是否被转换为 SVG。

这一条随想故意把三张照片、一段声音、一段视频和一个链接放在一起，用来确认日常记录不需要被单一媒体类型限制。

好的界面不只是让事情更快发生，也应该帮助人知道什么值得发生。

界面在分配什么

每一个高亮、通知和默认选项，都在替用户分配注意力。它们看上去只是视觉决策，实际上却在参与判断。

摩擦不是敌人

有些摩擦应该被删掉，例如重复输入和无意义的确认；另一些摩擦则应该被保留，例如发布前的停顿、删除前的复核，以及阅读长文时清晰的段落边界。

type Friction = {
  cost: number;
  protectsIntent: boolean;
};

const shouldRemove = (friction: Friction) =>
  friction.cost > 0 && !friction.protectsIntent;

把节奏设计进去

我现在更愿意先问三个问题：

1. 用户来到这里时，最需要看见什么？
2. 哪些信息可以晚一点出现？
3. 这个流程应该在哪里自然结束？

这些问题没有让界面变得更复杂，反而让许多元素失去了存在的理由。

最后的判断

注意力不是取之不尽的资源。产品真正的克制，不是少用一种颜色，而是少向用户索取一次不必要的注意。

脚注也应该像在 Typora 中一样自然工作。^attention

验证真实路径

测试最小单元很重要，但用户真正经历的是一条完整路径。至少有一次验证应该从入口走到结果。

不隐藏边界

没有验证的部分要明确说出来。诚实的边界比虚假的完整更有价值。

留下下一步

一次发布应该让下一次开发更容易开始，而不是重新理解所有上下文。

文件就是作品

文章不应该只存在于某个编辑器的数据库里。标题、发布日期和主题放进 YAML front matter，正文保持标准 Markdown，图片则和文章一起归档。

发布只是一次编译

写作和发布可以分离。写作阶段只关心内容；网站读取文件，生成目录、搜索索引和 RSS。

• 在 Typora 中完成正文
• 提交 Markdown 与媒体资源
• 发布后继续修正

可迁移才有长期主义

真正的长期主义不是选中一个“永远不会倒闭”的平台，而是让迁移成本始终足够低。

唯一事实来源

先确定数据由谁拥有，再决定界面如何派生。临时交互状态可以留在视图，持久事实必须有明确边界。

乐观更新

乐观更新让操作显得即时，但失败时必须能够回滚，并且不能让选择状态丢失。

可恢复

真正可靠的状态不是永不失败，而是在失败以后仍然知道应该回到哪里。

什么是最小闭环

它必须包含触发、完成和反馈。只有按钮不算闭环，只有数据结构也不算。

把想法切成动作

以一个文件浏览器为例，第一步不是标签、搜索或批量操作，而是：

1. 创建文件夹；
2. 创建 Markdown 文件；
3. 刷新列表；
4. 自动选中新项目。

可观察的完成

闭环需要能被人看见，也能被测试验证。每次完成之后，都应该留下足够明确的证据。

下一步

当闭环成立，再进入命名、删除和上下文菜单。功能扩展不再是猜测，而是沿着已经成立的路径自然生长。

页码不等于位置

同一页里也有阅读进度。只记录页码，恢复后仍然可能让人失去上下文。

变化前先保存锚点

布局变化之前，保存视口中心所对应的文档坐标；布局完成以后，再把这个坐标映射回新的视口。

两条交互路径

侧栏开关是离散变化，分隔线拖拽是连续变化。它们应该共享“保持锚点”的原则，但不应该共享完全相同的更新频率。

Prefill 与 Decode

Prefill 一次处理完整提示词，Decode 则每次只生成一个新 token。

flowchart LR
  A[Prompt] --> B[Prefill]
  B --> C[KV Cache]
  C --> D[Decode one token]
  D --> C

缓存的是什么

过去 token 对应的 Key 和 Value 不会因为新 token 到来而变化，所以可以保存下来，只计算新位置的投影。

空间换时间

缓存减少计算，却增加显存占用。批量、序列长度与层数共同决定了这笔开销。

$$ \text{KV memory} \propto 2 \times L \times H \times T $$