From 2f6f499d38e7d4c3c648c9cf23fd2de7df25be62 Mon Sep 17 00:00:00 2001
From: Yuna-Celisse <29951517@qq.com>
Date: Sun, 25 Oct 2026 16:46:07 +0800
Subject: [PATCH] feat(editor): check Markdown and render Mermaid previews

---
 .vitepress/theme/EditPage.vue         | 273 +++++++++++++++++++++++-
 .vitepress/theme/editor/codemirror.ts |  50 ++++-
 .vitepress/theme/editor/preview.ts    |  86 ++++++++
 .vitepress/theme/style.css            |  45 ++++
 checks/editor-validation.test.ts      |  24 +++
 package.json                          |   1 +
 pnpm-lock.yaml                        |   3 +
 tutorial/manual/writing-documents.md  |  10 +-
 utils/markdown-validation.test.ts     |  78 +++++++
 utils/markdown-validation.ts          | 295 ++++++++++++++++++++++++++
 10 files changed, 860 insertions(+), 5 deletions(-)
 create mode 100644 checks/editor-validation.test.ts
 create mode 100644 utils/markdown-validation.test.ts
 create mode 100644 utils/markdown-validation.ts

diff --git a/.vitepress/theme/EditPage.vue b/.vitepress/theme/EditPage.vue
index 95444ef9..8f811bf0 100644
--- a/.vitepress/theme/EditPage.vue
+++ b/.vitepress/theme/EditPage.vue
@@ -1,10 +1,13 @@
 <script setup lang="ts">
 import type { Component } from 'vue'
+import type { MarkdownIssue } from '../../utils/markdown-validation'
 import type { Me, PendingImage } from './editor/backend'
 import type { Format } from './editor/codemirror'
 import type { Destination } from './editor/destinations'
 import {
   Bold,
+  CircleAlert,
+  CircleCheck,
   Code2,
   Eye,
   FileDiff,
@@ -22,6 +25,7 @@ import {
 import { useData } from 'vitepress'
 import { computed, nextTick, onBeforeUnmount, onMounted, ref, watch } from 'vue'
 import { extractH1, splitFrontmatter } from '../../utils/markdown'
+import { lintMarkdown } from '../../utils/markdown-validation'
 import { reviewNoteFor, transcribedFrom } from './editor/archive'
 import { isSignedIn, signIn, signOut } from './editor/auth'
 import { load, localMode, submit as send, startedAt, taken, me as whoami } from './editor/backend'
@@ -66,8 +70,14 @@ let insertAt: ((snippet: string, caret?: number) => void) | undefined
 let showDiff: ((original: string | undefined) => void) | undefined
 let applyFormat: ((kind: Format) => void) | undefined
 let replaceAll: ((text: string) => void) | undefined
+let showIssues: ((issues: MarkdownIssue[]) => void) | undefined
+let revealIssue: ((issue: MarkdownIssue) => void) | undefined
 
 const diffing = ref(false)
+const markdownIssues = ref<MarkdownIssue[]>([])
+const checkingMarkdown = ref(false)
+const checkedMarkdown = ref(false)
+const checkProblem = ref('')
 
 const images = ref<PendingImage[]>([])
 const pendingUrls = new Map<string, string>()
@@ -102,6 +112,9 @@ const target = computed(() => destination.value
   ? { path: pathFor(destination.value, slug.value), route: routeFor(destination.value, slug.value) }
   : { path: page.value.filePath, route: '' })
 
+const isArchived = computed(() => destination.value?.id === 'archived'
+  || (!destination.value && page.value.filePath.startsWith('archived/')))
+
 const titled = computed(() => Boolean(extractH1(draft.value)?.trim()))
 const slugBad = computed(() => destination.value ? slugProblem(destination.value, slug.value) : '')
 
@@ -135,16 +148,42 @@ const contentBlocker = computed(() => {
   return ''
 })
 
+const checkSummary = computed(() => {
+  if (!changed.value)
+    return ''
+  if (checkingMarkdown.value)
+    return '正在检查 Markdown……'
+  if (checkProblem.value)
+    return 'Markdown 检查暂时不可用'
+  if (markdownIssues.value.length)
+    return `Markdown 有 ${markdownIssues.value.length} 处需要修正`
+  if (checkedMarkdown.value)
+    return 'Markdown 检查通过'
+  return ''
+})
+
+const syntaxBlocker = computed(() => {
+  if (!changed.value || checkProblem.value)
+    return ''
+  if (checkingMarkdown.value)
+    return '正在检查 Markdown 格式'
+  if (checkedMarkdown.value && markdownIssues.value.length)
+    return `Markdown 还有 ${markdownIssues.value.length} 处需要修正`
+  return ''
+})
+
 const blocker = computed(() => {
   if (contentBlocker.value)
     return contentBlocker.value
+  if (syntaxBlocker.value)
+    return syntaxBlocker.value
   if (!summary.value.trim())
     return destination.value ? '写一句话说明这一页讲什么' : '写一句话说明这次改了什么'
   return ''
 })
 
 const canSubmit = computed(() => !blocker.value && !slugIssue.value)
-const canOpenSave = computed(() => !contentBlocker.value && !slugIssue.value)
+const canOpenSave = computed(() => !contentBlocker.value && !syntaxBlocker.value && !slugIssue.value)
 
 const armedLead = computed(() => {
   return leaving.value ? '退出登录会放弃这些修改。' : '现在退出会放弃这些修改。'
@@ -180,6 +219,80 @@ watch([draft, summary, slug, images], () => {
   }, 400)
 }, { deep: true })
 
+let checkTimer: ReturnType<typeof setTimeout> | undefined
+let checkRun = 0
+
+function clearMarkdownCheck() {
+  clearTimeout(checkTimer)
+  checkTimer = undefined
+  checkRun++
+  markdownIssues.value = []
+  checkingMarkdown.value = false
+  checkedMarkdown.value = false
+  checkProblem.value = ''
+  showIssues?.([])
+}
+
+async function inspectMarkdown(): Promise<void> {
+  clearTimeout(checkTimer)
+  checkTimer = undefined
+  const source = draft.value
+  if (!changed.value || !source.trim()) {
+    clearMarkdownCheck()
+    return
+  }
+
+  const run = ++checkRun
+  checkingMarkdown.value = true
+  checkedMarkdown.value = false
+  checkProblem.value = ''
+  markdownIssues.value = []
+  showIssues?.([])
+
+  try {
+    const issues = await lintMarkdown(source, { archived: isArchived.value })
+    if (run !== checkRun)
+      return
+    markdownIssues.value = issues
+    checkedMarkdown.value = true
+    showIssues?.(issues)
+  }
+  catch (error) {
+    if (run !== checkRun)
+      return
+    checkProblem.value = error instanceof Error ? error.message : String(error)
+    checkedMarkdown.value = true
+    showIssues?.([])
+  }
+  finally {
+    if (run === checkRun)
+      checkingMarkdown.value = false
+  }
+}
+
+function scheduleMarkdownCheck() {
+  if (typeof window === 'undefined' || stage.value !== 'editing')
+    return
+  clearTimeout(checkTimer)
+  checkTimer = undefined
+  checkRun++
+  checkingMarkdown.value = false
+  checkedMarkdown.value = false
+  checkProblem.value = ''
+  markdownIssues.value = []
+  showIssues?.([])
+
+  if (!changed.value || !draft.value.trim()) {
+    checkingMarkdown.value = false
+    return
+  }
+
+  checkingMarkdown.value = true
+  checkTimer = setTimeout(() => void inspectMarkdown(), 450)
+}
+
+watch([draft, stage], scheduleMarkdownCheck, { immediate: true })
+
 function restore(key: string): boolean {
   const saved = recall(key)
   if (!saved || saved.draft === original.value)
@@ -217,12 +330,11 @@ watch([() => stage.value, host], async ([current, element]) => {
   if (current !== 'editing' || !element || editor)
     return
   await nextTick()
-  const { mountEditor } = await import('./editor/codemirror')
+  const { format, mountEditor, revealMarkdownIssue, setDiff, setMarkdownIssues } = await import('./editor/codemirror')
   const view = mountEditor(element, draft.value, value => (draft.value = value), () => {
     openSave()
   }, onFiles, destination.value && placeholderFor(destination.value))
   view.focus()
-  const { format, setDiff } = await import('./editor/codemirror')
   showDiff = original => setDiff(view, original)
   applyFormat = kind => format(view, kind)
   replaceAll = (text) => {
@@ -234,16 +346,29 @@ watch([() => stage.value, host], async ([current, element]) => {
     view.dispatch({ changes: { from: at, insert: snippet }, selection: { anchor: at + (caret ?? snippet.length) } })
     view.focus()
   }
+  showIssues = issues => setMarkdownIssues(view, issues)
+  revealIssue = issue => revealMarkdownIssue(view, issue)
+  showIssues(markdownIssues.value)
   editor = { destroy: () => view.destroy() }
 })
 
 function teardown() {
   editor?.destroy()
   editor = undefined
+  showIssues = undefined
+  revealIssue = undefined
+  clearMarkdownCheck()
   preview?.close()
   preview = undefined
 }
 
+async function jumpToIssue(issue: MarkdownIssue) {
+  if (stage.value === 'previewing')
+    backToEditing()
+  await nextTick()
+  revealIssue?.(issue)
+}
+
 function toggleDiff() {
   diffing.value = !diffing.value
   showDiff?.(diffing.value ? original.value : undefined)
@@ -326,6 +451,8 @@ async function insertImage() {
 }
 
 async function showPreview() {
+  if (stage.value === 'editing')
+    await inspectMarkdown()
   const { openPreview } = await import('./editor/preview')
   preview = await openPreview(draft.value, pendingUrls)
   if (preview)
@@ -393,6 +520,7 @@ watch(stage, async (current) => {
 onBeforeUnmount(() => document.documentElement.style.removeProperty('--vp-layout-top-height'))
 
 function reset() {
+  clearMarkdownCheck()
   restored.value = false
   images.value = []
   pendingUrls.clear()
@@ -740,6 +868,35 @@ function insertOutline() {
             <p v-else-if="changed && contentBlocker" class="nb-edit-why">
               {{ contentBlocker }}
             </p>
+            <div v-if="changed && stage !== 'submitting'" class="nb-edit-check" aria-live="polite">
+              <p v-if="checkingMarkdown" class="nb-edit-check-note">
+                正在检查 Markdown 格式……
+              </p>
+              <div v-else-if="checkProblem" class="nb-edit-check-problem">
+                <CircleAlert :size="17" :stroke-width="1.8" aria-hidden="true" />
+                <span>Markdown 检查暂时不可用，仍可预览和保存。</span>
+                <small>{{ checkProblem }}</small>
+              </div>
+              <template v-else-if="markdownIssues.length">
+                <p class="nb-edit-check-head">
+                  <CircleAlert :size="17" :stroke-width="1.8" aria-hidden="true" />
+                  修正下面 {{ markdownIssues.length }} 处问题后才能提交
+                </p>
+                <ol class="nb-edit-check-list">
+                  <li v-for="issue in markdownIssues" :key="`${issue.line}:${issue.column}:${issue.rule}`">
+                    <button type="button" :title="issue.detail || issue.message" @click="jumpToIssue(issue)">
+                      <span class="nb-edit-check-place">第 {{ issue.line }} 行</span>
+                      <span class="nb-edit-check-rule">{{ issue.rule }}</span>
+                      <span>{{ issue.message }}</span>
+                    </button>
+                  </li>
+                </ol>
+              </template>
+              <p v-else-if="checkedMarkdown" class="nb-edit-check-pass">
+                <CircleCheck :size="17" :stroke-width="1.8" aria-hidden="true" />
+                Markdown 检查通过
+              </p>
+            </div>
             <div ref="host" class="nb-edit-area" :class="{ 'is-busy': stage === 'submitting' }" />
             <input ref="picker" type="file" :accept="accepts" hidden @change="onPicked">
           </template>
@@ -852,6 +1009,13 @@ function insertOutline() {
             <Eye :size="18" :stroke-width="1.8" aria-hidden="true" />
             预览模式
           </span>
+          <span
+            v-if="checkSummary"
+            class="nb-preview-check"
+            :class="{ 'is-bad': markdownIssues.length, 'is-good': checkedMarkdown && !markdownIssues.length && !checkProblem }"
+          >
+            {{ checkSummary }}
+          </span>
           <button type="button" class="nb-edit-ghost" @click="backToEditing">
             继续编辑
           </button>
@@ -1251,6 +1415,24 @@ function insertOutline() {
   color: var(--vp-c-brand-1);
 }
 
+.nb-preview-check {
+  flex: none;
+  padding: 3px 8px;
+  border-radius: 999px;
+  background: var(--vp-c-bg);
+  font-size: 12px;
+  color: var(--vp-c-text-3);
+  white-space: nowrap;
+}
+
+.nb-preview-check.is-good {
+  color: var(--vp-c-success-1);
+}
+
+.nb-preview-check.is-bad {
+  color: var(--vp-c-danger-1);
+}
+
 .nb-edit-note {
   font-size: 13px;
   color: var(--vp-c-text-3);
@@ -1476,6 +1658,83 @@ function insertOutline() {
   padding: 34px 21px 0;
 }
 
+.nb-edit-check {
+  width: 100%;
+  max-width: var(--nb-measure);
+  margin: 0 auto;
+  padding: 0 21px 4px;
+  font-size: 13px;
+}
+
+.nb-edit-check-note {
+  color: var(--vp-c-text-3);
+}
+
+.nb-edit-check-head,
+.nb-edit-check-pass,
+.nb-edit-check-problem {
+  display: flex;
+  gap: 7px;
+  align-items: center;
+  color: var(--vp-c-danger-1);
+}
+
+.nb-edit-check-pass {
+  color: var(--vp-c-success-1);
+}
+
+.nb-edit-check-problem {
+  flex-wrap: wrap;
+  color: var(--vp-c-warning-1);
+}
+
+.nb-edit-check-problem small {
+  flex: 1 0 100%;
+  padding-left: 24px;
+  font-size: 12px;
+  color: var(--vp-c-text-3);
+}
+
+.nb-edit-check-list {
+  max-height: 14rem;
+  margin: 7px 0 4px;
+  padding: 0;
+  overflow-y: auto;
+  list-style: none;
+  border: 1px solid var(--vp-c-divider);
+  border-radius: 4px;
+}
+
+.nb-edit-check-list li + li {
+  border-top: 1px solid var(--vp-c-divider);
+}
+
+.nb-edit-check-list button {
+  display: flex;
+  gap: 7px;
+  align-items: baseline;
+  width: 100%;
+  padding: 7px 10px;
+  text-align: left;
+  color: var(--vp-c-text-2);
+}
+
+.nb-edit-check-list button:hover {
+  background: var(--vp-c-bg-soft);
+}
+
+.nb-edit-check-place,
+.nb-edit-check-rule {
+  flex: none;
+  font-family: var(--nb-mono);
+  font-size: 11px;
+  color: var(--vp-c-text-3);
+}
+
+.nb-edit-check-rule {
+  color: var(--vp-c-danger-1);
+}
+
 .nb-edit-why {
   width: 100%;
   max-width: var(--nb-measure);
@@ -1498,6 +1757,14 @@ function insertOutline() {
     padding: 13px 8px 0;
   }
 
+  .nb-preview-mode {
+    font-size: 14px;
+  }
+
+  .nb-preview-check {
+    display: none;
+  }
+
   .nb-edit-toolbar {
     flex-wrap: wrap;
     column-gap: 3px;
diff --git a/.vitepress/theme/editor/codemirror.ts b/.vitepress/theme/editor/codemirror.ts
index 7d587458..3fc5b485 100644
--- a/.vitepress/theme/editor/codemirror.ts
+++ b/.vitepress/theme/editor/codemirror.ts
@@ -1,9 +1,10 @@
 import type { Extension, Range } from '@codemirror/state'
 import type { DecorationSet, ViewUpdate } from '@codemirror/view'
+import type { MarkdownIssue } from '../../../utils/markdown-validation'
 import { defaultKeymap, history, historyKeymap, indentLess, indentMore } from '@codemirror/commands'
 import { markdown, markdownLanguage } from '@codemirror/lang-markdown'
 import { syntaxTree } from '@codemirror/language'
-import { Compartment, EditorSelection, EditorState, RangeSet } from '@codemirror/state'
+import { Compartment, EditorSelection, EditorState, RangeSet, StateEffect, StateField } from '@codemirror/state'
 import { Decoration, EditorView, keymap, placeholder, ViewPlugin } from '@codemirror/view'
 
 const HEADING = /^ATXHeading([1-6])$/
@@ -109,6 +110,50 @@ function styleDoc(state: EditorState): DecorationSet {
   return RangeSet.of(ranges, true)
 }
 
+function issueDecorations(state: EditorState, issues: MarkdownIssue[]): DecorationSet {
+  const ranges: Range<Decoration>[] = []
+  for (const problem of issues) {
+    if (!problem.line || problem.line > state.doc.lines)
+      continue
+    const line = state.doc.line(problem.line)
+    ranges.push(Decoration.line({ class: 'cm-nb-issue-line' }).range(line.from))
+    const start = Math.min(line.to, line.from + Math.max(0, problem.column - 1))
+    if (start < line.to)
+      ranges.push(Decoration.mark({ class: 'cm-nb-issue-text' }).range(start, Math.min(line.to, start + 1)))
+    else if (line.length)
+      ranges.push(Decoration.mark({ class: 'cm-nb-issue-text' }).range(line.to - 1, line.to))
+  }
+  return RangeSet.of(ranges, true)
+}
+
+const setIssues = StateEffect.define<MarkdownIssue[]>()
+
+const issueField = StateField.define<DecorationSet>({
+  create: () => Decoration.none,
+  update(decorations, transaction) {
+    for (const effect of transaction.effects) {
+      if (effect.is(setIssues))
+        return issueDecorations(transaction.state, effect.value)
+    }
+    return decorations.map(transaction.changes)
+  },
+  provide: field => EditorView.decorations.from(field),
+})
+
+export function setMarkdownIssues(view: EditorView, issues: MarkdownIssue[]): void {
+  view.dispatch({ effects: setIssues.of(issues) })
+}
+
+export function revealMarkdownIssue(view: EditorView, problem: MarkdownIssue): void {
+  const line = view.state.doc.line(Math.min(Math.max(1, problem.line), view.state.doc.lines))
+  const position = Math.min(line.to, line.from + Math.max(0, problem.column - 1))
+  view.dispatch({
+    selection: { anchor: position },
+    effects: EditorView.scrollIntoView(position, { y: 'center' }),
+  })
+  view.focus()
+}
+
 const liveStyling = ViewPlugin.fromClass(
   class {
     decorations: DecorationSet
@@ -155,6 +200,8 @@ const theme = EditorView.theme({
   '.cm-deletedChunk': { backgroundColor: 'color-mix(in srgb, var(--vp-c-danger-1) 12%, transparent)' },
   '.cm-changedLine': { backgroundColor: 'color-mix(in srgb, var(--vp-c-brand-1) 8%, transparent)' },
   '.cm-changedText': { backgroundColor: 'color-mix(in srgb, var(--vp-c-brand-1) 18%, transparent)' },
+  '.cm-nb-issue-line': { backgroundColor: 'color-mix(in srgb, var(--vp-c-danger-1) 7%, transparent)' },
+  '.cm-nb-issue-text': { textDecoration: 'underline wavy var(--vp-c-danger-1)', textUnderlineOffset: '3px' },
   '.cm-nb-code': {
     fontFamily: 'var(--nb-mono)',
     fontSize: '0.9em',
@@ -330,6 +377,7 @@ export function mountEditor(
     markdown({ base: markdownLanguage }),
     EditorView.lineWrapping,
     liveStyling,
+    issueField,
     diffing.of([]),
     theme,
     EditorView.updateListener.of((update) => {
diff --git a/.vitepress/theme/editor/preview.ts b/.vitepress/theme/editor/preview.ts
index fabc8da6..c95061d8 100644
--- a/.vitepress/theme/editor/preview.ts
+++ b/.vitepress/theme/editor/preview.ts
@@ -10,6 +10,85 @@ export interface Preview {
 }
 
 const DOC = '.vp-doc'
+const MERMAID = 'pre > code[class~="language-mermaid" i], pre > code[class~="language-mmd" i]'
+let previewNumber = 0
+
+function errorText(error: unknown): string {
+  const text = error instanceof Error ? error.message : String(error)
+  return text.split('\n')[0] ?? '无法解析图表'
+}
+
+function diagramError(source: HTMLPreElement, error: unknown): HTMLElement {
+  const box = document.createElement('div')
+  box.className = 'nb-mermaid-error'
+  box.setAttribute('role', 'alert')
+
+  const title = document.createElement('strong')
+  title.textContent = 'Mermaid 图表语法错误'
+  const detail = document.createElement('p')
+  detail.textContent = errorText(error)
+
+  const more = document.createElement('details')
+  const summary = document.createElement('summary')
+  summary.textContent = '查看图表源码'
+  const copy = source.cloneNode(true) as HTMLPreElement
+  copy.removeAttribute('aria-busy')
+  copy.classList.remove('nb-mermaid-source')
+  more.append(summary, copy)
+  box.append(title, detail, more)
+  return box
+}
+
+async function renderMermaid(
+  host: HTMLElement,
+  current: () => boolean,
+  number: number,
+): Promise<void> {
+  const blocks = [...host.querySelectorAll<HTMLElement>(MERMAID)]
+  if (!blocks.length)
+    return
+
+  const mermaid = (await import('mermaid')).default
+  if (!current())
+    return
+
+  mermaid.initialize({
+    startOnLoad: false,
+    securityLevel: 'loose',
+    theme: document.documentElement.classList.contains('dark') ? 'dark' : 'default',
+  })
+
+  for (const [index, code] of blocks.entries()) {
+    if (!current() || !code.isConnected)
+      return
+    const source = code.closest('pre') as HTMLPreElement | null
+    if (!source)
+      continue
+    source.classList.add('nb-mermaid-source')
+    source.setAttribute('aria-busy', 'true')
+
+    try {
+      const definition = code.textContent ?? ''
+      await mermaid.parse(definition)
+      if (!current() || !source.isConnected)
+        return
+      const { svg } = await mermaid.render(`nb-mermaid-${number}-${index}`, definition)
+      if (!current() || !source.isConnected)
+        return
+      const figure = document.createElement('figure')
+      figure.className = 'nb-mermaid'
+      figure.setAttribute('role', 'img')
+      figure.setAttribute('aria-label', 'Mermaid 图表')
+      figure.innerHTML = svg
+      source.replaceWith(figure)
+    }
+    catch (error) {
+      if (!current() || !source.isConnected)
+        return
+      source.replaceWith(diagramError(source, error))
+    }
+  }
+}
 
 export async function openPreview(
   markdown: string,
@@ -29,6 +108,9 @@ export async function openPreview(
   article.after(host)
   article.style.display = 'none'
 
+  const instance = ++previewNumber
+  let generation = 0
+  let closed = false
   let app: App | undefined
 
   // The built page already resolved ./assets/name.webp to a hashed URL.
@@ -43,6 +125,7 @@ export async function openPreview(
 
   const render = (source: string) => {
     app?.unmount()
+    const run = ++generation
     const html = previewSources(renderMarkdown(stripFrontmatter(source)), published, pending)
     const { code } = compile(`<div>${html}</div>`, {
       mode: 'function',
@@ -57,6 +140,7 @@ export async function openPreview(
       app.component(name, component)
     app.config.warnHandler = () => {}
     app.mount(host)
+    void renderMermaid(host, () => !closed && run === generation, instance * 1000 + run)
   }
 
   render(markdown)
@@ -65,6 +149,8 @@ export async function openPreview(
   return {
     update: render,
     close() {
+      closed = true
+      generation++
       app?.unmount()
       host.remove()
       article.style.display = ''
diff --git a/.vitepress/theme/style.css b/.vitepress/theme/style.css
index 54bfc54f..0de6ce03 100644
--- a/.vitepress/theme/style.css
+++ b/.vitepress/theme/style.css
@@ -1181,3 +1181,48 @@
     text-decoration: none;
   }
 }
+
+/* Mermaid is rendered in place of the editor preview's fenced source. */
+.vp-doc .nb-mermaid-source {
+  opacity: 0.55;
+}
+
+.vp-doc .nb-mermaid {
+  display: flex;
+  justify-content: center;
+  width: 100%;
+  margin: 2rem 0;
+  overflow-x: auto;
+}
+
+.vp-doc .nb-mermaid svg {
+  max-width: 100%;
+  height: auto;
+}
+
+.vp-doc .nb-mermaid-error {
+  margin: 1.5rem 0;
+  padding: 1rem;
+  border: 1px solid color-mix(in srgb, var(--vp-c-danger-1) 35%, var(--vp-c-divider));
+  border-radius: 6px;
+  background: color-mix(in srgb, var(--vp-c-danger-1) 6%, var(--vp-c-bg-soft));
+  font-size: 0.875rem;
+}
+
+.vp-doc .nb-mermaid-error strong {
+  color: var(--vp-c-danger-1);
+}
+
+.vp-doc .nb-mermaid-error p {
+  margin: 0.35rem 0 0.75rem;
+  color: var(--vp-c-text-2);
+}
+
+.vp-doc .nb-mermaid-error details pre {
+  margin: 0.5rem 0 0;
+}
+
+.vp-doc .nb-mermaid-error summary {
+  cursor: pointer;
+  color: var(--vp-c-text-2);
+}
diff --git a/checks/editor-validation.test.ts b/checks/editor-validation.test.ts
new file mode 100644
index 00000000..ff9d4f09
--- /dev/null
+++ b/checks/editor-validation.test.ts
@@ -0,0 +1,24 @@
+import { describe, expect, it } from 'vitest'
+import { splitFrontmatter } from '../utils/markdown'
+import { lintMarkdown } from '../utils/markdown-validation'
+import { listDocs } from './content-contract'
+
+describe('editor Markdown validation', () => {
+  it('accepts every current page body', async () => {
+    const failures: string[] = []
+
+    for (const doc of listDocs()) {
+      const issues = await lintMarkdown(splitFrontmatter(doc.content).body, {
+        archived: doc.category === 'archived',
+        mermaid: false,
+      })
+      if (issues.length) {
+        failures.push(`${doc.relativePath}: ${issues
+          .map(problem => `${problem.line}:${problem.column} ${problem.rule}`)
+          .join(', ')}`)
+      }
+    }
+
+    expect(failures).toEqual([])
+  }, 30_000)
+})
diff --git a/package.json b/package.json
index 10abf0a7..2a0201df 100644
--- a/package.json
+++ b/package.json
@@ -51,6 +51,7 @@
     "markdown-it": "^14.3.1",
     "markdown-it-anchor": "^9.2.1",
     "markdown-it-container": "^4.0.0",
+    "markdownlint": "0.38.0",
     "markdownlint-cli2": "^0.18.1",
     "mermaid": "^11.16.1",
     "postcss": "^8.5.26",
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 41fd53fd..d6f609e8 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -108,6 +108,9 @@ importers:
       markdown-it-container:
         specifier: ^4.0.0
         version: 4.0.0
+      markdownlint:
+        specifier: 0.38.0
+        version: 0.38.0
       markdownlint-cli2:
         specifier: ^0.18.1
         version: 0.18.1
diff --git a/tutorial/manual/writing-documents.md b/tutorial/manual/writing-documents.md
index f6148bad..d5af85dc 100644
--- a/tutorial/manual/writing-documents.md
+++ b/tutorial/manual/writing-documents.md
@@ -33,11 +33,19 @@ maintainers:
 
 ## 第三步：修改
 
-单击“在本页编辑”，打开编辑框。左边编辑，右边实时预览。
+单击“在本页编辑”，打开编辑框。
 
 - 用 Markdown 语法编写。常用语法见 [Markdown](/tutorial/markdown)。
+- 编辑器会自动检查 Markdown。发现问题时，编辑框上方会列出规则、行号和修改提示；修正前不能提交。
 - 要插入图片，把图片拖进编辑框。系统自动把图片转为 WebP 格式并保存。
 - 页面开头两行 `---` 之间是元信息。如果你不清楚每一项的作用，不要修改它们。
+- 需要画流程图时，用标注为 `mermaid` 的代码块。单击“预览”后，它会像正式页面一样渲染成图表。
+
+```mermaid
+flowchart LR
+  A[编辑] --> B[预览]
+  B --> C[提交]
+```
 
 如果你不能确定某个事实，写清楚缺少什么，不要编造。归档页有专用的标记，见[编者按标记](/tutorial/vitepress#本站的编者按标记)。
 
diff --git a/utils/markdown-validation.test.ts b/utils/markdown-validation.test.ts
new file mode 100644
index 00000000..0e86414f
--- /dev/null
+++ b/utils/markdown-validation.test.ts
@@ -0,0 +1,78 @@
+import { describe, expect, it } from 'vitest'
+import { lintMarkdown } from './markdown-validation'
+
+describe('markdown validation', () => {
+  it('accepts formatting that the submit path fixes automatically', async () => {
+    expect(await lintMarkdown('# Title  \n\n\nBody')).toEqual([])
+  })
+
+  it('reports markdownlint rules with their line and column', async () => {
+    const issues = await lintMarkdown('#Title\n\nBody\n')
+
+    expect(issues).toContainEqual(expect.objectContaining({
+      line: 1,
+      column: 1,
+      rule: 'MD018',
+      message: '井号后需要空格',
+    }))
+  })
+
+  it('rejects an unclosed fenced code block', async () => {
+    const issues = await lintMarkdown('# Title\n\n```text\ncode\n')
+
+    expect(issues).toContainEqual(expect.objectContaining({
+      line: 3,
+      rule: 'FENCE',
+    }))
+  })
+
+  it('rejects an unclosed container', async () => {
+    const issues = await lintMarkdown('# Title\n\n::: tip\nText\n')
+
+    expect(issues).toContainEqual(expect.objectContaining({
+      line: 3,
+      rule: 'CONTAINER',
+    }))
+  })
+
+  it('applies the archived directory overrides', async () => {
+    const source = '# Title\n\n## Same\n\nOne.\n\n## Same\n\nTwo.\n'
+    const active = await lintMarkdown(source, { mermaid: false })
+    const archived = await lintMarkdown(source, { archived: true, mermaid: false })
+
+    expect(active.some(problem => problem.rule === 'MD024')).toBe(true)
+    expect(archived.some(problem => problem.rule === 'MD024')).toBe(false)
+  })
+
+  it('validates Mermaid syntax at the source line', async () => {
+    const issues = await lintMarkdown([
+      '# Title',
+      '',
+      '```mermaid',
+      'graph TD',
+      'A-->[',
+      '```',
+      '',
+    ].join('\n'))
+
+    expect(issues).toContainEqual(expect.objectContaining({
+      line: 5,
+      rule: 'MERMAID',
+      message: 'Mermaid 图表语法错误',
+    }))
+  })
+
+  it('accepts a valid Mermaid diagram', async () => {
+    const issues = await lintMarkdown([
+      '# Title',
+      '',
+      '```mermaid',
+      'graph TD',
+      'A-->B',
+      '```',
+      '',
+    ].join('\n'))
+
+    expect(issues).toEqual([])
+  })
+})
diff --git a/utils/markdown-validation.ts b/utils/markdown-validation.ts
new file mode 100644
index 00000000..2c3e16e3
--- /dev/null
+++ b/utils/markdown-validation.ts
@@ -0,0 +1,295 @@
+import type { Configuration, LintError } from 'markdownlint'
+
+export const MARKDOWNLINT_CONFIG = {
+  MD013: false,
+  MD033: false,
+  MD041: false,
+  MD049: false,
+} satisfies Configuration
+
+// The nearest config above a page wins. archived/.markdownlint.jsonc adds
+// these overrides because scanned records keep their original structure.
+const ARCHIVED_CONFIG = {
+  ...MARKDOWNLINT_CONFIG,
+  MD001: false,
+  MD004: false,
+  MD022: false,
+  MD024: false,
+  MD025: false,
+  MD028: false,
+  MD029: false,
+  MD051: false,
+} satisfies Configuration
+
+export interface MarkdownValidationOptions {
+  archived?: boolean
+  mermaid?: boolean
+}
+
+export interface MarkdownIssue {
+  line: number
+  column: number
+  rule: string
+  message: string
+  detail?: string
+}
+
+interface Fence {
+  char: '`' | '~'
+  length: number
+  line: number
+  info: string
+  content: string[]
+  closed: boolean
+}
+
+interface MermaidBlock {
+  line: number
+  content: string
+}
+
+interface Marker {
+  char: '`' | '~' | ':'
+  length: number
+  info: string
+}
+
+function marker(text: string, chars: ReadonlyArray<Marker['char']>): Marker | undefined {
+  const indent = text.match(/^ {0,3}/)?.[0].length ?? 0
+  const body = text.slice(indent)
+  const char = body[0]
+  if (!char || !chars.includes(char as Marker['char']))
+    return undefined
+
+  let length = 0
+  while (body[length] === char)
+    length++
+  if (length < 3)
+    return undefined
+  return { char: char as Marker['char'], length, info: body.slice(length).trim() }
+}
+
+const RULE_MESSAGES: Record<string, string> = {
+  MD001: '标题层级一次只能增加一级',
+  MD003: '标题写法不一致',
+  MD004: '无序列表使用的符号不一致',
+  MD005: '同级列表项的缩进不一致',
+  MD007: '嵌套列表的缩进不正确',
+  MD009: '行尾有多余空格',
+  MD010: '使用了制表符，请换成空格',
+  MD012: '连续空行太多',
+  MD018: '井号后需要空格',
+  MD019: '标题的井号后只能有一个空格',
+  MD020: '闭合式标题前后需要空格',
+  MD021: '闭合式标题内只能有一个空格',
+  MD022: '标题前后需要空行',
+  MD023: '标题前不能有缩进',
+  MD024: '有内容相同的标题',
+  MD025: '一页只能有一个一级标题',
+  MD026: '标题末尾不能有标点',
+  MD027: '引用符号后只能有一个空格',
+  MD028: '引用块之间不能直接留空行',
+  MD029: '有序列表的编号不一致',
+  MD030: '列表标记后只能有一个空格',
+  MD031: '代码块前后需要空行',
+  MD032: '列表前后需要空行',
+  MD033: '这里不允许直接写 HTML',
+  MD034: '裸网址需要写成链接或放进尖括号',
+  MD035: '分隔线的写法不一致',
+  MD036: '不要用强调代替标题',
+  MD037: '强调标记内部不能多出空格',
+  MD038: '行内代码标记内部不能多出空格',
+  MD039: '链接文字两边不能多出空格',
+  MD040: '代码块需要标明语言',
+  MD041: '第一行应该是一级标题',
+  MD042: '链接地址不能为空',
+  MD043: '标题结构不符合约定',
+  MD044: '专有名词的大小写不一致',
+  MD045: '图片缺少替代文字',
+  MD046: '代码块风格不一致',
+  MD047: '文件末尾只能有一个换行',
+  MD048: '代码围栏的符号不一致',
+  MD049: '强调符号的风格不一致',
+  MD050: '加粗符号的风格不一致',
+  MD051: '站内链接的锚点不存在',
+  MD052: '引用链接或图片没有对应定义',
+  MD053: '链接定义没有被使用',
+  MD054: '链接或图片的写法不一致',
+  MD055: '表格行格式不一致',
+  MD056: '表格列数不一致',
+  MD058: '表格前后需要空行',
+  MERMAID: 'Mermaid 图表语法错误',
+  FENCE: '代码块没有关闭',
+  CONTAINER: '容器标记没有配对',
+}
+
+function issue(line: number, column: number, rule: string, detail?: string): MarkdownIssue {
+  const value: MarkdownIssue = {
+    line: Math.max(1, line),
+    column: Math.max(1, column),
+    rule,
+    message: RULE_MESSAGES[rule] ?? rule,
+  }
+  if (detail?.trim())
+    value.detail = detail.trim()
+  return value
+}
+
+function inspectFences(source: string): { blocks: Fence[], issues: MarkdownIssue[] } {
+  const lines = source.split('\n')
+  const blocks: Fence[] = []
+  const issues: MarkdownIssue[] = []
+  let open: Fence | undefined
+
+  for (let index = 0; index < lines.length; index++) {
+    const text = lines[index]
+    if (!open) {
+      const match = marker(text, ['`', '~'])
+      if (!match || (match.char === '`' && match.info.includes('`')))
+        continue
+      open = {
+        char: match.char,
+        length: match.length,
+        line: index + 1,
+        info: match.info,
+        content: [],
+        closed: false,
+      }
+      continue
+    }
+
+    const close = marker(text, [open.char])
+    if (close && !close.info && close.length >= open.length) {
+      blocks.push({ ...open, closed: true })
+      open = undefined
+    }
+    else {
+      open.content.push(text)
+    }
+  }
+
+  if (open) {
+    blocks.push(open)
+    issues.push(issue(open.line, 1, 'FENCE', `请补上 ${open.char.repeat(open.length)} 结束标记`))
+  }
+
+  return { blocks, issues }
+}
+
+function inspectContainers(source: string, fences: Fence[]): MarkdownIssue[] {
+  const fenced = new Set<number>()
+  for (const fence of fences) {
+    for (let line = fence.line; line <= fence.line + fence.content.length + (fence.closed ? 1 : 0); line++)
+      fenced.add(line)
+  }
+
+  const issues: MarkdownIssue[] = []
+  const open: Array<{ length: number, line: number }> = []
+
+  source.split('\n').forEach((text, index) => {
+    const line = index + 1
+    if (fenced.has(line))
+      return
+    const match = marker(text, [':'])
+    if (!match)
+      return
+    if (match.info) {
+      open.push({ length: match.length, line })
+      return
+    }
+
+    let found = -1
+    for (let at = open.length - 1; at >= 0; at--) {
+      if (open[at].length <= match.length) {
+        found = at
+        break
+      }
+    }
+    if (found === -1)
+      issues.push(issue(line, 1, 'CONTAINER', '这一行 ::: 没有对应开头'))
+    else
+      open.splice(found, 1)
+  })
+
+  for (const entry of open)
+    issues.push(issue(entry.line, 1, 'CONTAINER', '请补上 ::: 结束标记'))
+
+  return issues
+}
+
+function markdownlintIssue(error: LintError): MarkdownIssue {
+  const rule = error.ruleNames[0] ?? 'MARKDOWNLINT'
+  const column = error.errorRange?.[0] ?? 1
+  return issue(
+    error.lineNumber,
+    column,
+    rule,
+    error.errorDetail || error.errorContext || undefined,
+  )
+}
+
+function mermaidLine(error: unknown): { line: number, column: number } | undefined {
+  const hash = (error as { hash?: { loc?: { first_line?: number, first_column?: number } } }).hash
+  const line = hash?.loc?.first_line
+  const column = hash?.loc?.first_column
+  if (!line)
+    return undefined
+  return { line, column: column ?? 1 }
+}
+
+async function inspectMermaid(blocks: MermaidBlock[]): Promise<MarkdownIssue[]> {
+  if (!blocks.length)
+    return []
+
+  const mermaid = (await import('mermaid')).default
+  mermaid.initialize({ startOnLoad: false, securityLevel: 'loose' })
+  const issues: MarkdownIssue[] = []
+
+  for (const block of blocks) {
+    try {
+      await mermaid.parse(block.content)
+    }
+    catch (error) {
+      const at = mermaidLine(error)
+      issues.push(issue(
+        block.line + (at?.line ?? 1) - 1,
+        at?.column ?? 1,
+        'MERMAID',
+        error instanceof Error ? error.message.split('\n')[0] : String(error),
+      ))
+    }
+  }
+
+  return issues
+}
+
+// The submit path fixes these before opening a pull request, so flagging them
+// would point at a line that is about to disappear and block a valid draft.
+const AUTO_FIXED = new Set(['MD009', 'MD012', 'MD047'])
+
+export async function lintMarkdown(source: string, options: MarkdownValidationOptions = {}): Promise<MarkdownIssue[]> {
+  const { blocks, issues: fenceIssues } = inspectFences(source)
+  const containerIssues = inspectContainers(source, blocks)
+
+  const { lint } = await import('markdownlint/promise')
+  const results = await lint({
+    strings: { draft: source },
+    config: options.archived ? ARCHIVED_CONFIG : MARKDOWNLINT_CONFIG,
+    resultVersion: 3,
+  })
+
+  const mermaid = options.mermaid === false
+    ? []
+    : blocks
+        .filter(block => block.closed && /^(?:mermaid|mmd)(?:\s|$)/i.test(block.info))
+        .map(block => ({ line: block.line + 1, content: block.content.join('\n') }))
+
+  return [
+    ...(results.draft ?? [])
+      .filter(error => !AUTO_FIXED.has(error.ruleNames[0] ?? ''))
+      .map(markdownlintIssue),
+    ...fenceIssues,
+    ...containerIssues,
+    ...await inspectMermaid(mermaid),
+  ].sort((left, right) => left.line - right.line || left.column - right.column || left.rule.localeCompare(right.rule))
+}