diff --git a/packages/web-pkg/package.json b/packages/web-pkg/package.json
index b45319f75a1..853b941411d 100644
--- a/packages/web-pkg/package.json
+++ b/packages/web-pkg/package.json
@@ -99,6 +99,7 @@
     "lodash-es": "^4.17.23",
     "lowlight": "^3.3.0",
     "luxon": "^3.7.2",
+    "marked": "catalog:tiptap",
     "oidc-client-ts": "^3.5.0",
     "p-queue": "^9.1.0",
     "password-sheriff": "^2.0.0",
diff --git a/packages/web-pkg/src/editor/components/CodeBlockComponent.vue b/packages/web-pkg/src/editor/components/CodeBlockComponent.vue
index fc9ee87478d..43d0d5fabd7 100644
--- a/packages/web-pkg/src/editor/components/CodeBlockComponent.vue
+++ b/packages/web-pkg/src/editor/components/CodeBlockComponent.vue
@@ -1,9 +1,10 @@
 <template>
   <node-view-wrapper class="code-block">
     <div class="text-editor-code-block-language" contenteditable="false">
+      <oc-icon name="code-box" size="xsmall" fill-type="line" />
       <select
         v-model="selectedLanguageValue"
-        class="text-editor-code-block-select font-mono"
+        class="text-editor-code-block-select"
         :aria-label="$gettext('Code language')"
         :disabled="isReadonly"
       >
@@ -78,6 +79,9 @@ const isReadonly = computed(() => props.editor.isEditable === false)
   position: absolute;
   right: 12px;
   top: 4px;
+  display: inline-flex;
+  align-items: center;
+  color: var(--oc-role-on-surface-variant);
 }
 
 .text-editor-code-block-select:focus {
@@ -87,10 +91,15 @@ const isReadonly = computed(() => props.editor.isEditable === false)
 
 .text-editor-code-block-select {
   text-align: right;
+  text-align-last: right;
+  field-sizing: content;
+  width: auto;
+  min-width: 0;
   font-size: 12px;
+  font-family: inherit;
   border: 0;
   background: transparent;
-  color: var(--oc-role-on-surface);
+  color: inherit;
 }
 
 .text-editor-code-block-select:disabled {
diff --git a/packages/web-pkg/src/editor/components/FrontmatterComponent.vue b/packages/web-pkg/src/editor/components/FrontmatterComponent.vue
new file mode 100644
index 00000000000..d6d55530340
--- /dev/null
+++ b/packages/web-pkg/src/editor/components/FrontmatterComponent.vue
@@ -0,0 +1,50 @@
+<template>
+  <node-view-wrapper class="text-editor-frontmatter">
+    <span class="text-editor-frontmatter-label" contenteditable="false">
+      <oc-icon name="file-list-2" size="xsmall" fill-type="line" />
+      {{ $gettext('Frontmatter') }}
+    </span>
+    <span :id="hintId" class="sr-only">
+      {{
+        $gettext(
+          'Press Shift+Enter or press Enter three times in a row to exit the frontmatter block.'
+        )
+      }}
+    </span>
+    <pre
+      class="text-editor-frontmatter-content font-mono"
+      role="textbox"
+      :aria-describedby="hintId"
+      aria-multiline="true"
+    ><node-view-content /></pre>
+  </node-view-wrapper>
+</template>
+
+<script setup lang="ts">
+import { NodeViewContent, nodeViewProps, NodeViewWrapper } from '@tiptap/vue-3'
+import { useGettext } from 'vue3-gettext'
+import { v4 as uuidV4 } from 'uuid'
+
+defineProps(nodeViewProps)
+const { $gettext } = useGettext()
+const hintId = `frontmatter-hint-${uuidV4()}`
+</script>
+
+<style scoped>
+.text-editor-frontmatter-label {
+  position: absolute;
+  right: 8px;
+  top: 4px;
+  display: inline-flex;
+  align-items: center;
+  gap: 0.25rem;
+  font-size: 12px;
+  color: var(--oc-role-on-surface-variant);
+  user-select: none;
+}
+
+.text-editor-frontmatter-content {
+  white-space: pre-wrap;
+  word-break: break-word;
+}
+</style>
diff --git a/packages/web-pkg/src/editor/components/TextEditorContent.vue b/packages/web-pkg/src/editor/components/TextEditorContent.vue
index 1f56e2d6955..a6dfff7d0f6 100644
--- a/packages/web-pkg/src/editor/components/TextEditorContent.vue
+++ b/packages/web-pkg/src/editor/components/TextEditorContent.vue
@@ -11,7 +11,10 @@
       :editor="textEditor.editor.value"
       @node-change="onDragHandleNodeChange"
     >
-      <div class="flex items-center gap-1 mr-1 mt-[0.125rem]">
+      <div
+        v-show="isDraggable"
+        class="drag-handle-controls flex items-center gap-1 mr-1 mt-[0.125rem]"
+      >
         <oc-button
           v-if="hasSlashCommands"
           appearance="raw"
@@ -59,6 +62,7 @@ import {
 } from 'vue'
 import { EditorContent } from '@tiptap/vue-3'
 import { DragHandle } from '@tiptap/extension-drag-handle-vue-3'
+import type { Node as ProseMirrorNode } from '@tiptap/pm/model'
 import { useGettext } from 'vue3-gettext'
 import { storeToRefs } from 'pinia'
 import TextEditorTableBubbleMenu from './TextEditorTableBubbleMenu.vue'
@@ -82,10 +86,21 @@ const textEditor = editor || inject<TextEditorInstance>('textEditor')!
 const sourceContent = ref('')
 const sourceModeTextareaRef = useTemplateRef<HTMLTextAreaElement>('sourceModeTextarea')
 const currentDragHandleNodePos = ref<number | null>(null)
+const isFrontmatterNode = ref(false)
 const isDarkTheme = computed(() => unref(currentTheme)?.isDark)
 const hljsThemeStyleElement = ref<HTMLLinkElement | null>(null)
 
 const isSourceMode = computed(() => unref(textEditor.state.sourceMode))
+
+const isDraggable = computed(() => {
+  // Frontmatter is pinned to the top of the document and cannot be moved, so
+  // neither hover handle has anything to offer there.
+  if (unref(isFrontmatterNode)) {
+    return false
+  }
+
+  return true
+})
 const zoomFactor = computed(() => {
   return `${(unref(textEditor.state.editorZoom) || 100) / 100}`
 })
@@ -111,8 +126,9 @@ const onSourceInput = (event: Event) => {
   }
 }
 
-const onDragHandleNodeChange = ({ pos }: { pos: number }) => {
+const onDragHandleNodeChange = ({ node, pos }: { node: ProseMirrorNode | null; pos: number }) => {
   currentDragHandleNodePos.value = pos
+  isFrontmatterNode.value = node?.type.name === 'frontmatter'
 }
 
 const openSlashMenu = () => {
diff --git a/packages/web-pkg/src/editor/composables/strategies/markdown.ts b/packages/web-pkg/src/editor/composables/strategies/markdown.ts
index 099875879b0..99237975647 100644
--- a/packages/web-pkg/src/editor/composables/strategies/markdown.ts
+++ b/packages/web-pkg/src/editor/composables/strategies/markdown.ts
@@ -1,25 +1,41 @@
 import type { Extension, JSONContent } from '@tiptap/core'
 import type { Node as ProseMirrorNode } from '@tiptap/pm/model'
 import StarterKit from '@tiptap/starter-kit'
+import Document from '@tiptap/extension-document'
 import { Markdown, MarkdownManager } from '@tiptap/markdown'
+import { Marked } from 'marked'
+import type { marked as markedDefault } from 'marked'
 import Image from '@tiptap/extension-image'
 import FindAndReplace from '@tiptap/extension-find-and-replace'
 import { Table, TableRow, TableCell, TableHeader } from '@tiptap/extension-table'
 import TaskList from '@tiptap/extension-task-list'
 import TaskItem from '@tiptap/extension-task-item'
 import { useGettext } from 'vue3-gettext'
-import { EditorActionGroup, useEditorActions } from '../useEditorActions'
+import { EditorAction, EditorActionGroup, useEditorActions } from '../useEditorActions'
 import { TextEditorState } from '../../types'
 import {
   createCodeBlockLowlight,
   createLinkExtension,
-  imageFileHandlerExtension
+  Frontmatter,
+  imageFileHandlerExtension,
+  registerFrontmatterTokenizer
 } from '../../extensions'
 import { ContentTypeStrategy, ExtensionsOptions } from './types'
 
 export const useStrategyMarkdown = (editorState: TextEditorState): ContentTypeStrategy => {
   const { $gettext } = useGettext()
 
+  // Every `MarkdownManager` appends its extensions' tokenizers to the marked
+  // instance it is given and never removes them. Left to the default, that is a
+  // process wide singleton which grows with every editor opened and keeps each
+  // manager it ever saw alive. Holding our own instance bounds both to the
+  // lifetime of this strategy.
+  // Cast because tiptap types the option as the default export, which carries a
+  // `getDefaults` helper a plain instance lacks. The manager never calls it: it
+  // only touches `use`, `setOptions`, `Lexer`, `lexer` and `defaults`.
+  const marked = new Marked() as unknown as typeof markedDefault
+  registerFrontmatterTokenizer(marked)
+
   const editorContentType = () => {
     return 'markdown'
   }
@@ -30,7 +46,7 @@ export const useStrategyMarkdown = (editorState: TextEditorState): ContentTypeSt
   // never change for a given strategy.
   let markdownManager: MarkdownManager | null = null
   const serialize = (doc: ProseMirrorNode): string => {
-    markdownManager ??= new MarkdownManager({ extensions: extensions() })
+    markdownManager ??= new MarkdownManager({ marked, extensions: extensions() })
     return markdownManager.serialize(doc.toJSON())
   }
 
@@ -76,10 +92,18 @@ export const useStrategyMarkdown = (editorState: TextEditorState): ContentTypeSt
       StarterKit.configure({
         link: false,
         codeBlock: false,
+        document: false,
         undoRedo: options?.yjs ? false : undefined
       }),
+      // Frontmatter is metadata about the document, it only ever belongs at the
+      // top. Spelled as an alternation rather than `frontmatter? block+` so that
+      // a document holding nothing but metadata is valid too. `block+` has to
+      // come first: ProseMirror fills an empty document from the leading
+      // alternative, and that must be a paragraph rather than a metadata block.
+      Document.extend({ content: 'block+ | (frontmatter block*)' }),
+      Frontmatter,
       createCodeBlockLowlight(),
-      Markdown,
+      Markdown.configure({ marked }),
       createLinkExtension(),
       Table.configure({ resizable: false }),
       TableRow,
@@ -116,6 +140,7 @@ export const useStrategyMarkdown = (editorState: TextEditorState): ContentTypeSt
     horizontalRule,
     link,
     menuEmoji,
+    frontmatter,
     image,
     menuSearchAndReplace,
     imageUrl,
@@ -131,8 +156,46 @@ export const useStrategyMarkdown = (editorState: TextEditorState): ContentTypeSt
     toggleHeaderRow,
     deleteTable
   } = useEditorActions(editorState)
+  /**
+   * Actions that still make sense while the caret sits in the frontmatter block.
+   * Everything else formats or inserts content, and the block holds raw metadata
+   * text that none of it applies to.
+   *
+   * This is an allowlist on purpose: an action added later is restricted until
+   * someone decides it belongs here.
+   */
+  const actionsAllowedInFrontmatter = new Set([
+    'undo',
+    'redo',
+    'menu-zoom',
+    'zoom-in',
+    'zoom-out',
+    'zoom-reset',
+    'source-mode',
+    'menu-search-and-replace',
+    'print',
+    'frontmatter',
+    'menu-emoji'
+  ])
+
+  const restrictInFrontmatter = (action: EditorAction): EditorAction => {
+    const childActions = action.childActions?.map(restrictInFrontmatter)
+
+    if (actionsAllowedInFrontmatter.has(action.id)) {
+      return childActions ? { ...action, childActions } : action
+    }
+
+    const { isEnabled } = action
+
+    return {
+      ...action,
+      ...(childActions && { childActions }),
+      isEnabled: (editor) => !editor.isActive('frontmatter') && (isEnabled?.(editor) ?? true)
+    }
+  }
+
   const editorActionGroups = (): EditorActionGroup[] => {
-    return [
+    const groups: EditorActionGroup[] = [
       {
         id: 'navigation',
         title: $gettext('Navigation'),
@@ -184,7 +247,8 @@ export const useStrategyMarkdown = (editorState: TextEditorState): ContentTypeSt
           deleteColumn(),
           deleteTable(),
           menuEmoji(),
-          horizontalRule()
+          horizontalRule(),
+          frontmatter()
         ]
       },
       {
@@ -198,6 +262,11 @@ export const useStrategyMarkdown = (editorState: TextEditorState): ContentTypeSt
         actions: [print()]
       }
     ]
+
+    return groups.map((group) => ({
+      ...group,
+      actions: group.actions.map(restrictInFrontmatter)
+    }))
   }
 
   return {
diff --git a/packages/web-pkg/src/editor/composables/useEditorActions.ts b/packages/web-pkg/src/editor/composables/useEditorActions.ts
index 0183e6a14e3..89aebdc499e 100644
--- a/packages/web-pkg/src/editor/composables/useEditorActions.ts
+++ b/packages/web-pkg/src/editor/composables/useEditorActions.ts
@@ -816,6 +816,48 @@ export function useEditorActions(state: TextEditorState) {
     isActive: () => false
   })
 
+  // Frontmatter actions
+  const hasFrontmatter = (editor: Editor) => {
+    return editor.state.doc.firstChild?.type.name === 'frontmatter'
+  }
+
+  const toggleFrontmatter = (editor: Editor, range?: Range) => {
+    // The slash query is not content the user wants to keep, drop it either way.
+    if (range) {
+      editor.chain().focus().deleteRange(range).run()
+    }
+
+    if (!hasFrontmatter(editor)) {
+      editor.chain().focus().setFrontmatter().run()
+      return
+    }
+
+    // Only one block can exist, so there is nothing to add. Take the user to it
+    // instead, landing where another key would go.
+    if (!editor.isActive('frontmatter')) {
+      const endOfMetadata = editor.state.doc.firstChild!.nodeSize - 1
+      editor.chain().focus().setTextSelection(endOfMetadata).run()
+      return
+    }
+
+    // Unwrapping only drops the fences, the metadata stays in the document as
+    // content, so there is nothing to confirm.
+    editor.chain().focus().unsetFrontmatter().run()
+  }
+
+  const frontmatter = (): EditorAction => ({
+    id: 'frontmatter',
+    title: $gettext('Frontmatter'),
+    description: $gettext('Document metadata'),
+    icon: 'file-list-2',
+    iconFillType: 'line',
+    keywords: ['frontmatter', 'metadata', 'yaml'],
+    showInSlashCommands: false,
+    toolbarAction: (editor) => toggleFrontmatter(editor),
+    slashCommandAction: ({ editor, range }) => toggleFrontmatter(editor, range),
+    isActive: (editor) => editor.isActive('frontmatter')
+  })
+
   // Table actions
   const createTable = (): EditorAction => ({
     id: 'table',
@@ -1045,6 +1087,7 @@ export function useEditorActions(state: TextEditorState) {
     imageUpload,
     imageCloud,
     horizontalRule,
+    frontmatter,
     // Table
     createTable,
     addRowBefore,
diff --git a/packages/web-pkg/src/editor/extensions/codeBlockLowlight.ts b/packages/web-pkg/src/editor/extensions/codeBlockLowlight.ts
index c3333ae1e08..1ea0489a534 100644
--- a/packages/web-pkg/src/editor/extensions/codeBlockLowlight.ts
+++ b/packages/web-pkg/src/editor/extensions/codeBlockLowlight.ts
@@ -1,9 +1,7 @@
 import CodeBlockLowlight from '@tiptap/extension-code-block-lowlight'
 import { VueNodeViewRenderer } from '@tiptap/vue-3'
-import { common, createLowlight } from 'lowlight'
 import CodeBlockComponent from '../components/CodeBlockComponent.vue'
-
-const lowlight = createLowlight(common)
+import { lowlight } from './lowlight'
 
 export function createCodeBlockLowlight() {
   return CodeBlockLowlight.extend({
diff --git a/packages/web-pkg/src/editor/extensions/frontmatter.ts b/packages/web-pkg/src/editor/extensions/frontmatter.ts
new file mode 100644
index 00000000000..4e9f9224eb2
--- /dev/null
+++ b/packages/web-pkg/src/editor/extensions/frontmatter.ts
@@ -0,0 +1,289 @@
+import { commands as coreCommands, Node, mergeAttributes } from '@tiptap/core'
+import type { CommandProps, JSONContent, MarkdownToken } from '@tiptap/core'
+import type { marked } from 'marked'
+import { TextSelection } from '@tiptap/pm/state'
+import { VueNodeViewRenderer } from '@tiptap/vue-3'
+import FrontmatterComponent from '../components/FrontmatterComponent.vue'
+import { frontmatterHighlightPlugin } from './frontmatterHighlight'
+
+declare module '@tiptap/core' {
+  interface Commands<ReturnType> {
+    frontmatter: {
+      /** Add an empty frontmatter block at the top of the document. */
+      setFrontmatter: () => ReturnType
+      /** Drop the fences, keeping the metadata as ordinary content. */
+      unsetFrontmatter: () => ReturnType
+    }
+  }
+}
+
+/**
+ * Matches a frontmatter block: `---`, the raw metadata, and a closing `---`.
+ * The metadata is captured verbatim, we never interpret it as YAML.
+ */
+const frontmatterPattern = /^---[ \t]*\r?\n([\s\S]*?)(?:\r?\n)?---[ \t]*(?:\r?\n|$)/
+
+/**
+ * Registers the frontmatter tokenizer on a marked instance.
+ *
+ * Registered with marked directly rather than through the node's
+ * `markdownTokenizer` hook, because that hook drops the lexer before calling us
+ * and the lexer carries the one signal that matters here.
+ *
+ * Marked lexes the inside of a blockquote with a fresh token array, so "nothing
+ * tokenized yet" is true in there too. A frontmatter node inside a container is
+ * invalid under the document schema, and since `Node.fromJSON` does not
+ * validate, it survives until a path that does (the DOM parser, y-prosemirror)
+ * prunes it, taking the surrounding content with it.
+ *
+ * Only the top level pass is handed the lexer's own token list, so comparing the
+ * two tells us where we are. `state.top` looks like the right flag but is not:
+ * marked sets it to true for blockquote contents as well.
+ *
+ * Takes the instance as an argument instead of reaching for marked's singleton:
+ * every `MarkdownManager` appends its tokenizers to whichever instance it is
+ * given and never removes them, so the singleton would grow for as long as the
+ * tab is open and hold on to every manager it ever saw.
+ */
+export function registerFrontmatterTokenizer(instance: typeof marked): void {
+  instance.use({
+    extensions: [
+      {
+        name: 'frontmatter',
+        level: 'block',
+        start: (src: string) => (src.startsWith('---') ? 0 : -1),
+        tokenizer(src, tokens) {
+          // Frontmatter opens the document, nothing else.
+          if (tokens !== this.lexer.tokens || tokens.length) {
+            return undefined
+          }
+
+          const match = frontmatterPattern.exec(src)
+          if (!match) {
+            return undefined
+          }
+
+          return { type: 'frontmatter', raw: match[0], text: match[1], tokens: [] }
+        }
+      }
+    ]
+  })
+}
+
+/**
+ * Frontmatter is metadata, not prose. Marked has no rule for it, so without
+ * this node the opening `---` lexes as a thematic break and the metadata turns
+ * into paragraphs and headings, which destroys it on the next save.
+ *
+ * The node keeps the metadata as plain, unformatted text and hands it back
+ * between its fences untouched. It behaves like a code block: editable, but
+ * nothing the editor does to it can change more than the characters the user
+ * typed.
+ */
+export const Frontmatter = Node.create({
+  name: 'frontmatter',
+  // Deliberately not in the `block` group: the document content expression names
+  // this type explicitly in its single leading slot, so staying out of `block`
+  // is what makes a second block anywhere else impossible.
+  content: 'text*',
+  marks: '',
+  code: true,
+  defining: true,
+  isolating: true,
+
+  parseHTML() {
+    return [{ tag: 'pre[data-frontmatter]', preserveWhitespace: 'full' as const }]
+  },
+
+  renderHTML({ HTMLAttributes }) {
+    return ['pre', mergeAttributes(HTMLAttributes, { 'data-frontmatter': '' }), ['code', 0]]
+  },
+
+  addNodeView() {
+    return VueNodeViewRenderer(FrontmatterComponent)
+  },
+
+  addProseMirrorPlugins() {
+    return [frontmatterHighlightPlugin(this.name)]
+  },
+
+  addCommands() {
+    // Toolbar and slash entries are gated by the strategy, but extensions bind
+    // their shortcuts straight into ProseMirror keymaps, so those keys stay live
+    // and would turn the metadata into a heading or a list. Every block
+    // conversion funnels through these few primitives, so guarding them covers
+    // all of the shortcuts at once, including extensions added later.
+    const refuseInside = <Args extends unknown[]>(
+      command: (...args: Args) => (props: CommandProps) => boolean
+    ) => {
+      return (...args: Args) =>
+        (props: CommandProps): boolean => {
+          if (props.editor.isActive(this.name)) {
+            return false
+          }
+
+          return command(...args)(props)
+        }
+    }
+
+    return {
+      setNode: refuseInside(coreCommands.setNode),
+      toggleNode: refuseInside(coreCommands.toggleNode),
+      toggleList: refuseInside(coreCommands.toggleList),
+      wrapIn: refuseInside(coreCommands.wrapIn),
+      toggleWrap: refuseInside(coreCommands.toggleWrap),
+
+      setFrontmatter:
+        () =>
+        ({ state, tr, dispatch }) => {
+          // The schema has room for exactly one block, at the top, so bail out
+          // cleanly and let `can()` report the toggle state.
+          if (state.doc.firstChild?.type === this.type) {
+            return false
+          }
+
+          if (dispatch) {
+            tr.insert(0, this.type.create())
+            tr.setSelection(TextSelection.create(tr.doc, 1)).scrollIntoView()
+          }
+
+          return true
+        },
+
+      unsetFrontmatter:
+        () =>
+        ({ state, tr, dispatch }) => {
+          const firstChild = state.doc.firstChild
+
+          if (firstChild?.type !== this.type) {
+            return false
+          }
+
+          if (dispatch) {
+            // Drop the fences and keep the metadata as content. Without them it
+            // is ordinary markdown, so hand it back through the parser: what the
+            // editor shows now is what a reload would show.
+            const parsed = this.editor.markdown.parse(firstChild.textContent)
+            const content = (parsed.content ?? []).map((node) => state.schema.nodeFromJSON(node))
+
+            tr.replaceWith(
+              0,
+              firstChild.nodeSize,
+              // An empty block carries nothing to unwrap, but the document still
+              // needs a block to be valid when it held nothing else.
+              content.length || state.doc.childCount > 1
+                ? content
+                : state.schema.nodes.paragraph.create()
+            )
+          }
+
+          return true
+        }
+    }
+  },
+
+  addKeyboardShortcuts() {
+    // The fences cannot be dissolved into prose, so this boundary can never be
+    // joined. Leaving the keys unhandled hands them to the browser, which
+    // deletes across the node view natively and takes the whole block with it.
+    // Handling them moves the caret across the boundary instead.
+    const frontmatterEndPos = (): number | null => {
+      const firstChild = this.editor.state.doc.firstChild
+
+      return firstChild?.type === this.type ? firstChild.nodeSize - 1 : null
+    }
+
+    const moveCaretTo = (pos: number) => {
+      return this.editor.commands.setTextSelection(pos)
+    }
+
+    const stepBackIntoFrontmatter = () => {
+      const end = frontmatterEndPos()
+      const { empty, $from } = this.editor.state.selection
+
+      if (end === null || !empty || $from.depth !== 1 || $from.parentOffset !== 0) {
+        return false
+      }
+
+      // Anything nested (a list item, a table cell) still has its own block to
+      // collapse first, so only a top level block sits right at the boundary.
+      return $from.before(1) === end + 1 && moveCaretTo(end)
+    }
+
+    // A gap cursor in front of the block is the one spot where deleting forward
+    // would select the whole node instead of a character, so step inside.
+    const stepIntoFrontmatterStart = () => {
+      const { empty, $from } = this.editor.state.selection
+
+      if (!empty || $from.pos !== 0 || this.editor.state.doc.firstChild?.type !== this.type) {
+        return false
+      }
+
+      return moveCaretTo(1)
+    }
+
+    const stepForwardIntoBody = () => {
+      const end = frontmatterEndPos()
+      const { empty, $from } = this.editor.state.selection
+
+      if (end === null || !empty || $from.pos !== end) {
+        return false
+      }
+
+      const startOfBody = end + 2
+
+      return startOfBody <= this.editor.state.doc.content.size && moveCaretTo(startOfBody)
+    }
+
+    const stepForwardAcrossBoundary = () => {
+      return stepIntoFrontmatterStart() || stepForwardIntoBody()
+    }
+
+    // Match code block behaviour: on the third Enter at the end of the block,
+    // drop the two typed blank lines and move to a regular text block.
+    const exitOnTripleEnter = () => {
+      const { empty, $from } = this.editor.state.selection
+
+      if (!empty || $from.parent.type !== this.type) {
+        return false
+      }
+
+      const isAtEnd = $from.parentOffset === $from.parent.nodeSize - 2
+      const endsWithDoubleNewline = $from.parent.textContent.endsWith('\n\n')
+
+      if (!isAtEnd || !endsWithDoubleNewline) {
+        return false
+      }
+
+      return this.editor
+        .chain()
+        .command(({ tr }) => {
+          tr.delete($from.pos - 2, $from.pos)
+          return true
+        })
+        .exitCode()
+        .run()
+    }
+
+    return {
+      Enter: exitOnTripleEnter,
+      Backspace: stepBackIntoFrontmatter,
+      'Mod-Backspace': stepBackIntoFrontmatter,
+      Delete: stepForwardAcrossBoundary,
+      'Mod-Delete': stepForwardAcrossBoundary
+    }
+  },
+
+  parseMarkdown: (token: MarkdownToken) => {
+    const text = (token as { text?: string }).text ?? ''
+
+    return { type: 'frontmatter', content: text ? [{ type: 'text', text }] : [] }
+  },
+
+  renderMarkdown: (node: JSONContent) => {
+    const text = (node.content ?? []).map((child) => child.text ?? '').join('')
+    // The markdown manager adds the block separator itself, adding trailing
+    // newlines here would grow a run of blank lines on every save.
+    return text ? `---\n${text}\n---` : '---\n---'
+  }
+})
diff --git a/packages/web-pkg/src/editor/extensions/frontmatterHighlight.ts b/packages/web-pkg/src/editor/extensions/frontmatterHighlight.ts
new file mode 100644
index 00000000000..ba831e4c49d
--- /dev/null
+++ b/packages/web-pkg/src/editor/extensions/frontmatterHighlight.ts
@@ -0,0 +1,88 @@
+import type { Node as ProseMirrorNode } from '@tiptap/pm/model'
+import { Plugin, PluginKey } from '@tiptap/pm/state'
+import { Decoration, DecorationSet } from '@tiptap/pm/view'
+import { lowlight } from './lowlight'
+
+export const frontmatterHighlightKey = new PluginKey<DecorationSet>('frontmatterHighlight')
+
+/**
+ * Frontmatter delimited by `---` is yaml by universal convention, so there is
+ * nothing to detect. Toml (`+++`) and json (`{}`) frontmatter never reach this
+ * node, the tokenizer only matches `---`.
+ */
+const frontmatterLanguage = 'yaml'
+
+/** A node of the hast tree lowlight returns. */
+type HighlightNode = ReturnType<typeof lowlight.highlight>['children'][number]
+
+type HighlightRun = { text: string; classes: string[] }
+
+function classNamesOf(node: Extract<HighlightNode, { type: 'element' }>): string[] {
+  const className = node.properties?.className
+
+  return Array.isArray(className) ? className.map(String) : []
+}
+
+/** Flatten the highlight tree into the runs of text that share a class list. */
+function toRuns(nodes: readonly HighlightNode[], inherited: string[] = []): HighlightRun[] {
+  return nodes.flatMap((node) => {
+    if (node.type === 'element') {
+      return toRuns(node.children, [...inherited, ...classNamesOf(node)])
+    }
+
+    return node.type === 'text' ? [{ text: node.value, classes: inherited }] : []
+  })
+}
+
+function buildDecorations(doc: ProseMirrorNode, nodeName: string): DecorationSet {
+  const block = doc.firstChild
+
+  if (block?.type.name !== nodeName) {
+    return DecorationSet.empty
+  }
+
+  const decorations: Decoration[] = []
+  // The block is always the document's first child, so its text starts at 1.
+  let from = 1
+
+  // `highlight` never throws on malformed input, it falls back to best effort
+  // tokens. Metadata is invalid yaml on most keystrokes, so that matters.
+  for (const run of toRuns(lowlight.highlight(frontmatterLanguage, block.textContent).children)) {
+    const to = from + run.text.length
+
+    if (run.classes.length) {
+      decorations.push(Decoration.inline(from, to, { class: run.classes.join(' ') }))
+    }
+
+    from = to
+  }
+
+  return DecorationSet.create(doc, decorations)
+}
+
+/**
+ * Renders the frontmatter block as highlighted yaml.
+ *
+ * The decorations are rebuilt on every document change rather than only when
+ * the block itself changed: there is at most one block holding a few hundred
+ * characters, which is far cheaper than the bookkeeping needed to tell whether
+ * it was the part that changed.
+ */
+export function frontmatterHighlightPlugin(nodeName: string): Plugin {
+  return new Plugin({
+    key: frontmatterHighlightKey,
+    state: {
+      init: (_, state) => buildDecorations(state.doc, nodeName),
+      apply: (transaction, decorations) => {
+        return transaction.docChanged
+          ? buildDecorations(transaction.doc, nodeName)
+          : decorations.map(transaction.mapping, transaction.doc)
+      }
+    },
+    props: {
+      decorations(state) {
+        return frontmatterHighlightKey.getState(state)
+      }
+    }
+  })
+}
diff --git a/packages/web-pkg/src/editor/extensions/index.ts b/packages/web-pkg/src/editor/extensions/index.ts
index 3ab1cb0fe8a..a9adbde8cda 100644
--- a/packages/web-pkg/src/editor/extensions/index.ts
+++ b/packages/web-pkg/src/editor/extensions/index.ts
@@ -1,4 +1,6 @@
 export * from './codeBlockLowlight'
+export * from './frontmatter'
+export * from './frontmatterHighlight'
 export * from './imageFileHandler'
 export * from './link'
 export * from './slashCommands'
diff --git a/packages/web-pkg/src/editor/extensions/lowlight.ts b/packages/web-pkg/src/editor/extensions/lowlight.ts
new file mode 100644
index 00000000000..32f3660dae8
--- /dev/null
+++ b/packages/web-pkg/src/editor/extensions/lowlight.ts
@@ -0,0 +1,7 @@
+import { common, createLowlight } from 'lowlight'
+
+/**
+ * One registry for the whole editor. Registering the common grammars is not
+ * free, and both the code block and the frontmatter block highlight against it.
+ */
+export const lowlight = createLowlight(common)
diff --git a/packages/web-pkg/src/editor/styles/text-editor.css b/packages/web-pkg/src/editor/styles/text-editor.css
index 3ae877498c8..00232b015f7 100644
--- a/packages/web-pkg/src/editor/styles/text-editor.css
+++ b/packages/web-pkg/src/editor/styles/text-editor.css
@@ -160,6 +160,26 @@
   position: relative;
 }
 
+/* Frontmatter styles */
+.text-editor-content .ProseMirror .text-editor-frontmatter {
+  position: relative;
+  margin: 0 0 1.5rem;
+  padding: 8px 12px;
+  border: 1px dashed var(--oc-role-outline-variant);
+  border-radius: 6px;
+  background: var(--oc-role-surface-container-high);
+  color: var(--oc-role-on-surface-variant);
+  font-size: calc(13px * var(--text-editor-zoom-factor));
+}
+
+.text-editor-content .ProseMirror .text-editor-frontmatter pre {
+  background: none;
+  border-radius: 0;
+  padding: 0;
+  margin: 0;
+  font-size: inherit;
+}
+
 /* Table styles */
 .text-editor-content .ProseMirror table {
   border-collapse: collapse;
diff --git a/packages/web-pkg/tests/unit/editor/components/FrontmatterComponent.spec.ts b/packages/web-pkg/tests/unit/editor/components/FrontmatterComponent.spec.ts
new file mode 100644
index 00000000000..d92494e8462
--- /dev/null
+++ b/packages/web-pkg/tests/unit/editor/components/FrontmatterComponent.spec.ts
@@ -0,0 +1,66 @@
+import { mount } from '@vue/test-utils'
+import { createGettext } from 'vue3-gettext'
+import FrontmatterComponent from '../../../../src/editor/components/FrontmatterComponent.vue'
+
+// The component renders no prop values, but VueNodeViewRenderer requires the
+// full node view prop contract, so satisfy it here to keep the mount warning free.
+const nodeViewProps = {
+  editor: {},
+  node: {},
+  decorations: [],
+  selected: false,
+  extension: {},
+  getPos: () => 0,
+  updateAttributes: (): void => undefined,
+  deleteNode: (): void => undefined,
+  view: {},
+  innerDecorations: {},
+  HTMLAttributes: {}
+} as any
+
+function mountComponent() {
+  return mount(FrontmatterComponent, {
+    props: nodeViewProps,
+    global: {
+      plugins: [createGettext({ translations: {}, silent: true })],
+      renderStubDefaultSlot: true,
+      stubs: {
+        NodeViewWrapper: { template: '<div v-bind="$attrs"><slot /></div>' },
+        NodeViewContent: { template: '<div class="node-view-content" />' },
+        'oc-icon': true
+      }
+    }
+  })
+}
+
+describe('FrontmatterComponent', () => {
+  it('hosts the editable node content', () => {
+    const wrapper = mountComponent()
+    expect(wrapper.find('.text-editor-frontmatter-content .node-view-content').exists()).toBe(true)
+  })
+
+  it('labels the block as frontmatter', () => {
+    const wrapper = mountComponent()
+    expect(wrapper.find('.text-editor-frontmatter-label').text()).toBe('Frontmatter')
+  })
+
+  it('keeps the label out of the editable text', () => {
+    const wrapper = mountComponent()
+    expect(wrapper.find('.text-editor-frontmatter-label').attributes('contenteditable')).toBe(
+      'false'
+    )
+  })
+
+  it('adds a screen reader hint for leaving the block', () => {
+    const wrapper = mountComponent()
+    const hint = wrapper.find('.sr-only')
+    const content = wrapper.find('.text-editor-frontmatter-content')
+
+    expect(hint.text()).toBe(
+      'Press Shift+Enter or press Enter three times in a row to exit the frontmatter block.'
+    )
+    expect(content.attributes('role')).toBe('textbox')
+    expect(content.attributes('aria-multiline')).toBe('true')
+    expect(content.attributes('aria-describedby')).toBe(hint.attributes('id'))
+  })
+})
diff --git a/packages/web-pkg/tests/unit/editor/components/TextEditorContent.spec.ts b/packages/web-pkg/tests/unit/editor/components/TextEditorContent.spec.ts
index a077b175f62..d87f27fad14 100644
--- a/packages/web-pkg/tests/unit/editor/components/TextEditorContent.spec.ts
+++ b/packages/web-pkg/tests/unit/editor/components/TextEditorContent.spec.ts
@@ -174,6 +174,24 @@ describe('TextEditorContent', () => {
     expect(wrapperWithout.find('.drag-handle-plus-button').exists()).toBe(false)
   })
 
+  it('hides the drag handle controls on the frontmatter block', async () => {
+    const { wrapper } = mountEditorContent({ hasSlashCommands: true })
+    const dragHandle = wrapper.findComponent({ name: 'DragHandle' })
+    const controlsStyle = () => wrapper.find('.drag-handle-controls').attributes('style') ?? ''
+
+    dragHandle.vm.$emit('node-change', { pos: 0, node: { type: { name: 'paragraph' } } })
+    await nextTick()
+    expect(controlsStyle()).not.toContain('display: none')
+
+    dragHandle.vm.$emit('node-change', { pos: 0, node: { type: { name: 'frontmatter' } } })
+    await nextTick()
+    expect(controlsStyle()).toContain('display: none')
+
+    dragHandle.vm.$emit('node-change', { pos: 0, node: null })
+    await nextTick()
+    expect(controlsStyle()).not.toContain('display: none')
+  })
+
   it('opens slash menu when plus button is clicked', async () => {
     const { wrapper, chain, run } = mountEditorContent({ hasSlashCommands: true })
 
diff --git a/packages/web-pkg/tests/unit/editor/composables/helpers.ts b/packages/web-pkg/tests/unit/editor/composables/helpers.ts
index 44351daa65f..d3309cfd0af 100644
--- a/packages/web-pkg/tests/unit/editor/composables/helpers.ts
+++ b/packages/web-pkg/tests/unit/editor/composables/helpers.ts
@@ -24,6 +24,10 @@ interface MockEditorOptions {
   canRedo?: boolean
   attributes?: Record<string, Record<string, unknown>>
   runResult?: boolean
+  /** Node type name of `state.doc.firstChild`, or undefined for an empty document. */
+  firstChildType?: string
+  /** `nodeSize` of `state.doc.firstChild`. */
+  firstChildSize?: number
 }
 
 export function createMockEditor(options: MockEditorOptions = {}) {
@@ -32,7 +36,9 @@ export function createMockEditor(options: MockEditorOptions = {}) {
     canUndo = false,
     canRedo = false,
     attributes = {},
-    runResult = true
+    runResult = true,
+    firstChildType,
+    firstChildSize = 16
   } = options
 
   const run = vi.fn().mockReturnValue(runResult)
@@ -80,7 +86,10 @@ export function createMockEditor(options: MockEditorOptions = {}) {
       'setImage',
       'insertContent',
       'command',
-      'toggleHeaderRow'
+      'toggleHeaderRow',
+      'setFrontmatter',
+      'unsetFrontmatter',
+      'setTextSelection'
     ]
     for (const method of methods) {
       chain[method] = vi.fn().mockReturnValue(chain)
@@ -107,7 +116,10 @@ export function createMockEditor(options: MockEditorOptions = {}) {
         $anchor: { before: () => 0 }
       },
       doc: {
-        nodeAt: (): any => null
+        nodeAt: (): any => null,
+        firstChild: firstChildType
+          ? { type: { name: firstChildType }, nodeSize: firstChildSize }
+          : null
       }
     },
     _chain: chainInstance,
diff --git a/packages/web-pkg/tests/unit/editor/composables/useEditorActions.spec.ts b/packages/web-pkg/tests/unit/editor/composables/useEditorActions.spec.ts
index a365f0ae2f3..373603f4e6e 100644
--- a/packages/web-pkg/tests/unit/editor/composables/useEditorActions.spec.ts
+++ b/packages/web-pkg/tests/unit/editor/composables/useEditorActions.spec.ts
@@ -693,6 +693,88 @@ describe('useEditorActions', () => {
     })
   })
 
+  describe('frontmatter', () => {
+    it('isActive only when the caret sits inside the frontmatter block', () => {
+      const inside = createMockEditor({
+        firstChildType: 'frontmatter',
+        isActive: (type) => type === 'frontmatter'
+      })
+      expect(actions.frontmatter().isActive!(inside)).toBe(true)
+
+      // The document has a frontmatter block, but the caret is elsewhere.
+      const outside = createMockEditor({ firstChildType: 'frontmatter' })
+      expect(actions.frontmatter().isActive!(outside)).toBe(false)
+
+      expect(actions.frontmatter().isActive!(createMockEditor())).toBe(false)
+    })
+
+    it('is hidden from slash commands', () => {
+      expect(actions.frontmatter().showInSlashCommands).toBe(false)
+    })
+
+    it('toolbarAction adds the block without asking when there is none', () => {
+      const editor = createMockEditor({ firstChildType: 'heading' })
+      actions.frontmatter().toolbarAction!(editor)
+
+      expect(editor._chain.setFrontmatter).toHaveBeenCalled()
+      expect(editor._chain.run).toHaveBeenCalled()
+      expect(useModals().modals).toHaveLength(0)
+    })
+
+    it('toolbarAction unwraps the block without asking when the caret is inside it', () => {
+      const editor = createMockEditor({
+        firstChildType: 'frontmatter',
+        isActive: (type) => type === 'frontmatter'
+      })
+      actions.frontmatter().toolbarAction!(editor)
+
+      expect(editor._chain.unsetFrontmatter).toHaveBeenCalled()
+      expect(editor._chain.run).toHaveBeenCalled()
+      expect(useModals().modals).toHaveLength(0)
+    })
+
+    it('toolbarAction moves the caret into the block instead of offering to delete it', () => {
+      const editor = createMockEditor({ firstChildType: 'frontmatter', firstChildSize: 16 })
+      actions.frontmatter().toolbarAction!(editor)
+
+      // End of the metadata, ready for another key.
+      expect(editor._chain.setTextSelection).toHaveBeenCalledWith(15)
+      expect(editor._chain.unsetFrontmatter).not.toHaveBeenCalled()
+      expect(editor._chain.setFrontmatter).not.toHaveBeenCalled()
+      expect(useModals().modals).toHaveLength(0)
+    })
+
+    it('slashCommandAction moves the caret into the block when one exists', () => {
+      const editor = createMockEditor({ firstChildType: 'frontmatter', firstChildSize: 16 })
+      actions.frontmatter().slashCommandAction!({ editor, range: mockRange })
+
+      expect(editor._chain.deleteRange).toHaveBeenCalledWith(mockRange)
+      expect(editor._chain.setTextSelection).toHaveBeenCalledWith(15)
+      expect(useModals().modals).toHaveLength(0)
+    })
+
+    it('slashCommandAction adds the block after removing the query', () => {
+      const editor = createMockEditor({ firstChildType: 'heading' })
+      actions.frontmatter().slashCommandAction!({ editor, range: mockRange })
+
+      expect(editor._chain.deleteRange).toHaveBeenCalledWith(mockRange)
+      expect(editor._chain.setFrontmatter).toHaveBeenCalled()
+      expect(useModals().modals).toHaveLength(0)
+    })
+
+    it('slashCommandAction unwraps the block when the caret is inside it', () => {
+      const editor = createMockEditor({
+        firstChildType: 'frontmatter',
+        isActive: (type) => type === 'frontmatter'
+      })
+      actions.frontmatter().slashCommandAction!({ editor, range: mockRange })
+
+      expect(editor._chain.deleteRange).toHaveBeenCalledWith(mockRange)
+      expect(editor._chain.unsetFrontmatter).toHaveBeenCalled()
+      expect(useModals().modals).toHaveLength(0)
+    })
+  })
+
   describe('imageUrl', () => {
     it('toolbarAction dispatches a modal with input', () => {
       const editor = createMockEditor()
diff --git a/packages/web-pkg/tests/unit/editor/extensions/frontmatter.spec.ts b/packages/web-pkg/tests/unit/editor/extensions/frontmatter.spec.ts
new file mode 100644
index 00000000000..52d0be03c64
--- /dev/null
+++ b/packages/web-pkg/tests/unit/editor/extensions/frontmatter.spec.ts
@@ -0,0 +1,748 @@
+import { ref } from 'vue'
+import { Editor } from '@tiptap/vue-3'
+import { GapCursor } from '@tiptap/pm/gapcursor'
+import * as Y from 'yjs'
+import { Collaboration } from '@tiptap/extension-collaboration'
+import { DEFAULT_YDOC_FRAGMENT } from '../../../../src/editor/types'
+import { createTestingPinia } from '@opencloud-eu/web-test-helpers'
+import { useStrategyMarkdown } from '../../../../src/editor/composables/strategies/markdown'
+import type { TextEditorLinkPanelRequest, TextEditorState } from '../../../../src/editor/types'
+import type { ContentTypeStrategy } from '../../../../src/editor/composables/strategies/types'
+
+vi.mock('vue3-gettext', () => ({
+  useGettext: () => ({ $gettext: (text: string) => text })
+}))
+
+function createStrategy(): ContentTypeStrategy {
+  const state: TextEditorState = {
+    sourceMode: ref(false),
+    linkPanel: ref<TextEditorLinkPanelRequest | null>(null),
+    editorZoom: ref(100)
+  }
+  return useStrategyMarkdown(state)
+}
+
+function createEditor(strategy: ContentTypeStrategy, content: string): Editor {
+  return new Editor({
+    extensions: strategy.extensions(),
+    content: strategy.deserialize(content),
+    contentType: 'markdown'
+  })
+}
+
+function roundtrip(content: string): string {
+  const strategy = createStrategy()
+  const editor = createEditor(strategy, content)
+  const markdown = strategy.serialize(editor.state.doc)
+  editor.destroy()
+  return markdown
+}
+
+// `editor.commands.keyboardShortcut()` replays only the captured steps, so a
+// shortcut that merely moves the caret is dropped. Dispatch a real keydown the
+// way the browser does instead.
+function pressKey(editor: Editor, key: string, withMod = false): boolean {
+  const event = new KeyboardEvent('keydown', {
+    key,
+    ctrlKey: withMod,
+    bubbles: true,
+    cancelable: true
+  })
+
+  return (
+    editor.view.someProp('handleKeyDown', (handler) => handler(editor.view, event) === true) ??
+    false
+  )
+}
+
+// Tiptap appends a trailing empty paragraph on the first transaction, which is
+// unrelated to frontmatter and shows up as trailing newlines in the markdown.
+function serializeBody(strategy: ContentTypeStrategy, editor: Editor): string {
+  return strategy.serialize(editor.state.doc).trimEnd()
+}
+
+/** Node types of a live document, minus the trailing empty paragraph. */
+function typesOf(editor: Editor): string[] {
+  const types = editor.state.doc.children.map((node) => node.type.name)
+  const last = editor.state.doc.lastChild
+
+  return last?.type.name === 'paragraph' && last.content.size === 0 ? types.slice(0, -1) : types
+}
+
+function nodeTypes(content: string): string[] {
+  const strategy = createStrategy()
+  const editor = createEditor(strategy, content)
+  const types = editor.state.doc.children.map((node) => node.type.name)
+  editor.destroy()
+  return types
+}
+
+describe('frontmatter', () => {
+  beforeEach(() => {
+    createTestingPinia()
+  })
+
+  describe('parsing', () => {
+    it('parses leading frontmatter into a single frontmatter node', () => {
+      expect(nodeTypes('---\ntitle: My note\n---\n\n# Heading\n')).toEqual([
+        'frontmatter',
+        'heading'
+      ])
+    })
+
+    it('keeps the raw frontmatter text verbatim', () => {
+      const strategy = createStrategy()
+      const editor = createEditor(strategy, '---\ntags:\n  - a\n  - b\n---\n\n# Heading\n')
+      expect(editor.state.doc.firstChild?.textContent).toBe('tags:\n  - a\n  - b')
+      editor.destroy()
+    })
+
+    it('keeps a thematic break inside the document a horizontal rule', () => {
+      expect(nodeTypes('# Heading\n\n---\n\nSome text.\n')).toEqual([
+        'heading',
+        'horizontalRule',
+        'paragraph'
+      ])
+    })
+
+    it('keeps a thematic break at the start of the document a horizontal rule', () => {
+      expect(nodeTypes('---\n\n# Heading\n')).toEqual(['horizontalRule', 'heading'])
+    })
+
+    it('does not parse frontmatter that starts below the first line', () => {
+      expect(nodeTypes('# Heading\n\n---\ntitle: My note\n---\n')).not.toContain('frontmatter')
+    })
+  })
+
+  describe('serialization', () => {
+    it.each([
+      ['single key', '---\ntitle: My note\n---\n\n# Heading\n\nSome text.'],
+      ['nested keys', '---\ntitle: My note\ntags:\n  - a\n  - b\ndraft: true\n---\n\n# Heading'],
+      ['without body', '---\ntitle: My note\n---'],
+      ['empty', '---\n---\n\n# Heading']
+    ])('round-trips frontmatter with %s', (_name, content) => {
+      expect(roundtrip(content)).toBe(content)
+    })
+
+    it('leaves a document without frontmatter untouched', () => {
+      const content = '# Heading\n\nSome text.'
+      expect(roundtrip(content)).toBe(content)
+    })
+  })
+
+  describe('editing', () => {
+    it('allows typing inside the frontmatter block', () => {
+      const strategy = createStrategy()
+      const editor = createEditor(strategy, '---\ntitle: My note\n---\n\n# Heading')
+      editor.commands.setTextSelection(1)
+      editor.commands.insertContent('X')
+      expect(serializeBody(strategy, editor)).toBe('---\nXtitle: My note\n---\n\n# Heading')
+      editor.destroy()
+    })
+
+    it('keeps an emoji inserted into the metadata verbatim', () => {
+      const strategy = createStrategy()
+      const editor = createEditor(strategy, '---\ntitle: \n---\n\n# Heading')
+      editor.commands.setTextSelection(8)
+      editor.commands.insertContent('🚀')
+
+      expect(editor.state.doc.firstChild?.textContent).toBe('title: 🚀')
+      expect(serializeBody(strategy, editor)).toBe('---\ntitle: 🚀\n---\n\n# Heading')
+      editor.destroy()
+    })
+
+    it('keeps typed frontmatter as plain text without marks', () => {
+      const strategy = createStrategy()
+      const editor = createEditor(strategy, '---\ntitle: My note\n---\n\n# Heading')
+      editor.commands.setTextSelection({ from: 1, to: 6 })
+      editor.commands.toggleBold()
+      expect(serializeBody(strategy, editor)).toBe('---\ntitle: My note\n---\n\n# Heading')
+      editor.destroy()
+    })
+  })
+
+  describe('commands', () => {
+    it('inserts an empty block at the top of the document', () => {
+      const strategy = createStrategy()
+      const editor = createEditor(strategy, '# Heading\n\nSome text.')
+
+      expect(editor.commands.setFrontmatter()).toBe(true)
+      expect(editor.state.doc.firstChild?.type.name).toBe('frontmatter')
+      expect(editor.state.doc.firstChild?.textContent).toBe('')
+      expect(serializeBody(strategy, editor)).toBe('---\n---\n\n# Heading\n\nSome text.')
+      editor.destroy()
+    })
+
+    it('puts the caret inside the inserted block', () => {
+      const strategy = createStrategy()
+      const editor = createEditor(strategy, '# Heading')
+      editor.commands.setFrontmatter()
+
+      expect(editor.state.selection.$from.parent.type.name).toBe('frontmatter')
+      editor.destroy()
+    })
+
+    it('does not insert a second block', () => {
+      const strategy = createStrategy()
+      const editor = createEditor(strategy, '---\ntitle: My note\n---\n\n# Heading')
+
+      expect(editor.commands.setFrontmatter()).toBe(false)
+      expect(serializeBody(strategy, editor)).toBe('---\ntitle: My note\n---\n\n# Heading')
+      editor.destroy()
+    })
+
+    // Unwrapping drops the fences and keeps the metadata as content, so nothing
+    // is lost and no confirmation is needed.
+    it('unwraps a single key into a paragraph', () => {
+      const strategy = createStrategy()
+      const editor = createEditor(strategy, '---\ntitle: My note\n---\n\n# Heading')
+
+      expect(editor.commands.unsetFrontmatter()).toBe(true)
+      expect(typesOf(editor)).toEqual(['paragraph', 'heading'])
+      expect(serializeBody(strategy, editor)).toBe('title: My note\n\n# Heading')
+      editor.destroy()
+    })
+
+    it('unwraps multi line metadata into what it means as markdown', () => {
+      const strategy = createStrategy()
+      const editor = createEditor(
+        strategy,
+        '---\ntitle: My note\ntags:\n  - a\n  - b\n---\n\n# Heading'
+      )
+
+      expect(editor.commands.unsetFrontmatter()).toBe(true)
+      expect(typesOf(editor)).toEqual(['paragraph', 'bulletList', 'heading'])
+      expect(serializeBody(strategy, editor)).toBe('title: My note\ntags:\n\n- a\n- b\n\n# Heading')
+      editor.destroy()
+    })
+
+    it('leaves a usable document when unwrapping an empty block', () => {
+      const strategy = createStrategy()
+      const editor = createEditor(strategy, '---\n---\n\n# Heading')
+
+      expect(editor.commands.unsetFrontmatter()).toBe(true)
+      expect(editor.state.doc.children.map((node) => node.type.name)).not.toContain('frontmatter')
+      expect(serializeBody(strategy, editor)).toBe('# Heading')
+      editor.destroy()
+    })
+
+    it('leaves a usable document when the block is all there is', () => {
+      const strategy = createStrategy()
+      const editor = createEditor(strategy, '---\n---')
+
+      expect(editor.commands.unsetFrontmatter()).toBe(true)
+      expect(editor.state.doc.childCount).toBeGreaterThan(0)
+      expect(editor.state.doc.children.map((node) => node.type.name)).not.toContain('frontmatter')
+      editor.destroy()
+    })
+
+    it('does not unwrap anything when there is no frontmatter', () => {
+      const strategy = createStrategy()
+      const editor = createEditor(strategy, '# Heading\n\nSome text.')
+
+      expect(editor.commands.unsetFrontmatter()).toBe(false)
+      expect(serializeBody(strategy, editor)).toBe('# Heading\n\nSome text.')
+      editor.destroy()
+    })
+
+    it.each([
+      ['without frontmatter', '# Heading', true, false],
+      ['with frontmatter', '---\ntitle: My note\n---\n\n# Heading', false, true]
+    ])('reports what it can do %s', (_name, content, canSet, canUnset) => {
+      const strategy = createStrategy()
+      const editor = createEditor(strategy, content)
+
+      expect(editor.can().setFrontmatter()).toBe(canSet)
+      expect(editor.can().unsetFrontmatter()).toBe(canUnset)
+      editor.destroy()
+    })
+  })
+
+  // The frontmatter fences cannot be dissolved into prose, so the block boundary
+  // must never be joined. Leaving those keys unhandled lets the browser delete
+  // across the node view natively, which takes the whole block with it.
+  describe('block boundary', () => {
+    function boundaryEditor() {
+      const strategy = createStrategy()
+      const editor = createEditor(strategy, '---\ntitle: My note\n---\n\n# Heading\n\nSome text.')
+      const frontmatterSize = editor.state.doc.firstChild!.nodeSize
+
+      return {
+        strategy,
+        editor,
+        startOfFrontmatter: 1,
+        endOfFrontmatter: frontmatterSize - 1,
+        startOfBody: frontmatterSize + 1
+      }
+    }
+
+    // The only way to sit in front of the very first block.
+    function placeGapCursorAtStart(editor: Editor) {
+      editor.view.dispatch(editor.state.tr.setSelection(new GapCursor(editor.state.doc.resolve(0))))
+    }
+
+    it.each([
+      ['Backspace', false],
+      ['Mod-Backspace', true]
+    ])('moves the caret into the frontmatter on %s at the start of the body', (_name, withMod) => {
+      const { strategy, editor, endOfFrontmatter, startOfBody } = boundaryEditor()
+      editor.commands.setTextSelection(startOfBody)
+
+      expect(pressKey(editor, 'Backspace', withMod)).toBe(true)
+      expect(editor.state.selection.$from.parent.type.name).toBe('frontmatter')
+      expect(editor.state.selection.from).toBe(endOfFrontmatter)
+      expect(serializeBody(strategy, editor)).toBe(
+        '---\ntitle: My note\n---\n\n# Heading\n\nSome text.'
+      )
+      editor.destroy()
+    })
+
+    it.each([
+      ['Delete', false],
+      ['Mod-Delete', true]
+    ])('moves the caret into the frontmatter on %s in front of it', (_name, withMod) => {
+      const { strategy, editor, startOfFrontmatter } = boundaryEditor()
+      placeGapCursorAtStart(editor)
+
+      expect(pressKey(editor, 'Delete', withMod)).toBe(true)
+      expect(editor.state.selection.$from.parent.type.name).toBe('frontmatter')
+      expect(editor.state.selection.from).toBe(startOfFrontmatter)
+      expect(serializeBody(strategy, editor)).toBe(
+        '---\ntitle: My note\n---\n\n# Heading\n\nSome text.'
+      )
+      editor.destroy()
+    })
+
+    it('moves the caret into the body on Delete at the end of the frontmatter', () => {
+      const { strategy, editor, endOfFrontmatter, startOfBody } = boundaryEditor()
+      editor.commands.setTextSelection(endOfFrontmatter)
+
+      expect(pressKey(editor, 'Delete')).toBe(true)
+      expect(editor.state.selection.$from.parent.type.name).toBe('heading')
+      expect(editor.state.selection.from).toBe(startOfBody)
+      expect(serializeBody(strategy, editor)).toBe(
+        '---\ntitle: My note\n---\n\n# Heading\n\nSome text.'
+      )
+      editor.destroy()
+    })
+
+    // Away from the boundary the key must stay unhandled so the browser keeps
+    // doing the ordinary character deletion.
+    it('leaves Backspace to the browser inside the body', () => {
+      const { editor, startOfBody } = boundaryEditor()
+      editor.commands.setTextSelection(startOfBody + 1)
+
+      expect(pressKey(editor, 'Backspace')).toBe(false)
+      editor.destroy()
+    })
+
+    it('leaves Delete to the browser inside the frontmatter', () => {
+      const { editor, endOfFrontmatter } = boundaryEditor()
+      editor.commands.setTextSelection(endOfFrontmatter - 1)
+
+      expect(pressKey(editor, 'Delete')).toBe(false)
+      editor.destroy()
+    })
+  })
+
+  describe('triple Enter', () => {
+    it('drops the two typed blank lines and exits the block on the third Enter', () => {
+      const strategy = createStrategy()
+      const editor = createEditor(strategy, '---\ntitle: My note\n---\n\n# Heading')
+      const metadata = editor.state.doc.firstChild!.textContent
+      const endOfFrontmatter = editor.state.doc.firstChild!.nodeSize - 1
+
+      editor.commands.setTextSelection(endOfFrontmatter)
+
+      expect(pressKey(editor, 'Enter')).toBe(true)
+      expect(pressKey(editor, 'Enter')).toBe(true)
+      expect(editor.state.doc.firstChild?.textContent).toBe(`${metadata}\n\n`)
+      expect(editor.state.selection.$from.parent.type.name).toBe('frontmatter')
+
+      expect(pressKey(editor, 'Enter')).toBe(true)
+      expect(editor.state.doc.firstChild?.textContent).toBe(metadata)
+      expect(editor.state.selection.$from.parent.type.name).toBe('paragraph')
+      expect(typesOf(editor)).toEqual(['frontmatter', 'paragraph', 'heading'])
+      editor.destroy()
+    })
+  })
+
+  // Source mode replaces the whole document on every keystroke, so a guard that
+  // rejects transactions would silently discard everything the user types there.
+  describe('document replacement', () => {
+    function replaceContent(content: string, next: string) {
+      const strategy = createStrategy()
+      const editor = createEditor(strategy, content)
+      editor.commands.setContent(next, { contentType: 'markdown', emitUpdate: true })
+      const markdown = serializeBody(strategy, editor)
+      editor.destroy()
+      return markdown
+    }
+
+    it.each([
+      ['edits the body', '---\ntitle: My note\n---\n\n# Changed'],
+      ['edits the frontmatter', '---\ntitle: Changed\n---\n\n# Heading'],
+      ['removes the frontmatter', '# Heading\n\nSome text.']
+    ])('applies a replacement that %s', (_name, next) => {
+      expect(replaceContent('---\ntitle: My note\n---\n\n# Heading', next)).toBe(next)
+    })
+
+    it('applies a replacement that breaks the opening fence', () => {
+      const strategy = createStrategy()
+      const editor = createEditor(strategy, '---\ntitle: My note\n---\n\n# Heading')
+      editor.commands.setContent('X---\ntitle: My note\n---\n\n# Heading', {
+        contentType: 'markdown',
+        emitUpdate: true
+      })
+      expect(editor.state.doc.children.map((node) => node.type.name)).not.toContain('frontmatter')
+      expect(editor.state.doc.textContent).toContain('X---')
+      editor.destroy()
+    })
+  })
+
+  // `group: 'block'` would let the `block+` half of the document content
+  // expression match frontmatter too, so a second block could be pasted into the
+  // body and would serialise to fences that re-lex as a rule plus a heading.
+  describe('uniqueness', () => {
+    const frontmatterHtml = '<pre data-frontmatter=""><code>title: B</code></pre>'
+
+    it('is not part of the block group', () => {
+      const strategy = createStrategy()
+      const editor = createEditor(strategy, '# Heading')
+      expect(editor.state.schema.nodes.frontmatter.spec.group).toBeUndefined()
+      editor.destroy()
+    })
+
+    it('refuses a second block pasted into the body', () => {
+      const strategy = createStrategy()
+      const editor = createEditor(strategy, '---\ntitle: A\n---\n\n# Heading')
+      editor.commands.setTextSelection(editor.state.doc.content.size - 1)
+      editor.commands.insertContent(frontmatterHtml)
+
+      expect(
+        editor.state.doc.children.filter((node) => node.type.name === 'frontmatter')
+      ).toHaveLength(1)
+      expect(editor.state.doc.firstChild?.textContent).toBe('title: A')
+      editor.destroy()
+    })
+
+    it('keeps a single block when content carries several', () => {
+      const strategy = createStrategy()
+      const editor = createEditor(strategy, '# Heading')
+      editor.commands.setContent(
+        `<pre data-frontmatter=""><code>title: A</code></pre><h1>H</h1>${frontmatterHtml}`,
+        { contentType: 'html' }
+      )
+
+      expect(
+        editor.state.doc.children.filter((node) => node.type.name === 'frontmatter')
+      ).toHaveLength(1)
+      editor.destroy()
+    })
+  })
+
+  // Two peers can each add a frontmatter block before their edits meet. The CRDT
+  // merges below the schema layer, so the result has to be checked, not assumed.
+  describe('collaboration', () => {
+    function boundEditor(strategy: ContentTypeStrategy, ydoc: Y.Doc): Editor {
+      return new Editor({
+        element: document.createElement('div'),
+        extensions: [
+          ...strategy.extensions({ yjs: true }),
+          Collaboration.configure({ document: ydoc, field: DEFAULT_YDOC_FRAGMENT })
+        ]
+      })
+    }
+
+    function sync(from: Y.Doc, to: Y.Doc) {
+      Y.applyUpdate(to, Y.encodeStateAsUpdate(from, Y.encodeStateVector(to)))
+    }
+
+    /** Two peers holding the same seed content, ready to diverge. */
+    function peers(seed: string) {
+      const strategy = createStrategy()
+      const docA = new Y.Doc()
+      const docB = new Y.Doc()
+      const a = boundEditor(strategy, docA)
+      a.commands.setContent(seed, { contentType: 'markdown' })
+      sync(docA, docB)
+
+      return {
+        strategy,
+        a,
+        b: boundEditor(strategy, docB),
+        reconnect: () => {
+          sync(docA, docB)
+          sync(docB, docA)
+        }
+      }
+    }
+
+    function frontmatterBlocks(editor: Editor) {
+      return editor.state.doc.children.filter((node) => node.type.name === 'frontmatter')
+    }
+
+    it('converges on a single block when both peers add one', () => {
+      const { strategy, a, b, reconnect } = peers('# Heading\n\nSome text.')
+      a.commands.setFrontmatter()
+      a.commands.insertContent('title: from A')
+      b.commands.setFrontmatter()
+      b.commands.insertContent('title: from B')
+
+      reconnect()
+
+      expect(frontmatterBlocks(a)).toHaveLength(1)
+      expect(frontmatterBlocks(b)).toHaveLength(1)
+      expect(strategy.serialize(a.state.doc)).toBe(strategy.serialize(b.state.doc))
+      a.destroy()
+      b.destroy()
+    })
+
+    // The losing block is demoted to a paragraph rather than dropped, so the
+    // metadata stays visible in the document and the result survives a reload.
+    it('keeps the losing metadata in the body and reloads unchanged', () => {
+      const { strategy, a, b, reconnect } = peers('# Heading')
+      a.commands.setFrontmatter()
+      a.commands.insertContent('title: from A')
+      b.commands.setFrontmatter()
+      b.commands.insertContent('title: from B')
+
+      reconnect()
+
+      const merged = strategy.serialize(a.state.doc)
+      expect(merged).toContain('title: from A')
+      expect(merged).toContain('title: from B')
+
+      const reloaded = createEditor(strategy, merged)
+      expect(strategy.serialize(reloaded.state.doc)).toBe(merged)
+      reloaded.destroy()
+      a.destroy()
+      b.destroy()
+    })
+
+    it('merges concurrent edits of the same metadata character by character', () => {
+      const { strategy, a, b, reconnect } = peers('---\ntitle: \n---\n\n# Heading')
+      a.commands.setTextSelection(8)
+      a.commands.insertContent('A')
+      b.commands.setTextSelection(8)
+      b.commands.insertContent('B')
+
+      reconnect()
+
+      expect(frontmatterBlocks(a)).toHaveLength(1)
+      expect(a.state.doc.firstChild?.textContent).toContain('A')
+      expect(a.state.doc.firstChild?.textContent).toContain('B')
+      expect(strategy.serialize(a.state.doc)).toBe(strategy.serialize(b.state.doc))
+      a.destroy()
+      b.destroy()
+    })
+
+    it('lets a removal win over a concurrent metadata edit', () => {
+      const { strategy, a, b, reconnect } = peers('---\ntitle: keep\n---\n\n# Heading')
+      a.commands.unsetFrontmatter()
+      b.commands.setTextSelection(12)
+      b.commands.insertContent('!')
+
+      reconnect()
+
+      expect(frontmatterBlocks(a)).toHaveLength(0)
+      expect(strategy.serialize(a.state.doc)).toBe(strategy.serialize(b.state.doc))
+      a.destroy()
+      b.destroy()
+    })
+  })
+
+  // Toolbar and slash entries are gated by the strategy, but extensions bind
+  // their shortcuts straight into ProseMirror keymaps, so the keys stay live
+  // regardless. Anything that restructures the block turns the metadata into
+  // prose and loses the fences.
+  describe('keyboard shortcuts', () => {
+    /** Every shortcut the editor's extensions register, as far as they expose one. */
+    function registeredShortcuts(editor: Editor): string[] {
+      const keys = new Set<string>()
+
+      for (const extension of editor.extensionManager.extensions) {
+        const addKeyboardShortcuts = (extension.config as { addKeyboardShortcuts?: () => object })
+          .addKeyboardShortcuts
+
+        if (!addKeyboardShortcuts) {
+          continue
+        }
+
+        try {
+          const context = { editor, options: extension.options, name: extension.name }
+          Object.keys(addKeyboardShortcuts.call(context)).forEach((key) => keys.add(key))
+        } catch {
+          // Some shortcuts need a node type we cannot build here, skip those.
+        }
+      }
+
+      return [...keys].filter((key) => key.includes('-'))
+    }
+
+    it('leaves the block intact for every registered shortcut', () => {
+      const strategy = createStrategy()
+      const probe = createEditor(strategy, '---\na: 1\n---\n\n# Heading')
+      const shortcuts = registeredShortcuts(probe)
+      probe.destroy()
+
+      expect(shortcuts.length).toBeGreaterThan(5)
+
+      const damaged: string[] = []
+      for (const shortcut of shortcuts) {
+        const editor = createEditor(createStrategy(), '---\na: 1\n---\n\n# Heading')
+        editor.commands.setTextSelection(2)
+        editor.commands.keyboardShortcut(shortcut)
+
+        const first = editor.state.doc.firstChild
+        if (first?.type.name !== 'frontmatter' || first.textContent !== 'a: 1') {
+          damaged.push(`${shortcut} -> ${first?.type.name}`)
+        }
+        editor.destroy()
+      }
+
+      expect(damaged).toEqual([])
+    })
+
+    it('still applies shortcuts outside the block', () => {
+      const strategy = createStrategy()
+      const editor = createEditor(strategy, '---\na: 1\n---\n\nplain')
+      editor.commands.setTextSelection(editor.state.doc.content.size - 2)
+      editor.commands.keyboardShortcut('Mod-Alt-1')
+
+      expect(serializeBody(strategy, editor)).toContain('# plain')
+      editor.destroy()
+    })
+  })
+
+  // Content reaches the block through more than the keyboard. These pin the
+  // schema level protections that keep the other routes harmless: `text*` and
+  // `marks: ''` admit nothing but plain text, and `code: true` stops input rules
+  // from firing inside it.
+  describe('other input paths', () => {
+    function editorWithCaretInMetadata() {
+      const strategy = createStrategy()
+      const editor = createEditor(strategy, '---\na: 1\n---\n\n# Heading')
+      editor.commands.setTextSelection(2)
+
+      return { strategy, editor }
+    }
+
+    it.each(['# ', '## ', '- ', '1. ', '> ', '```', '[ ] '])(
+      'types %j literally instead of running the input rule',
+      (typed) => {
+        const strategy = createStrategy()
+        const editor = createEditor(strategy, '---\na: 1\n---\n\n# Heading')
+        editor.commands.insertContentAt(1, typed, { applyInputRules: true })
+
+        expect(editor.state.doc.firstChild?.type.name).toBe('frontmatter')
+        expect(editor.state.doc.firstChild?.textContent).toBe(`${typed}a: 1`)
+        editor.destroy()
+      }
+    )
+
+    it.each([
+      ['a heading', '<h1>x</h1>'],
+      ['a list', '<ul><li>x</li></ul>'],
+      ['a quote', '<blockquote><p>x</p></blockquote>'],
+      ['a table', '<table><tr><td>x</td></tr></table>'],
+      ['an image', '<img src="data:image/png;base64,iVBORw0KGgo=" />']
+    ])('keeps the block plain text when pasting %s', (_name, html) => {
+      const { editor } = editorWithCaretInMetadata()
+      editor.commands.insertContent(html)
+
+      expect(editor.state.doc.firstChild?.type.name).toBe('frontmatter')
+      expect(() => editor.state.doc.check()).not.toThrow()
+      editor.destroy()
+    })
+
+    // The image file handler inserts at the drop position, which can land here.
+    it('refuses an image dropped onto the block', () => {
+      const { strategy, editor } = editorWithCaretInMetadata()
+      editor
+        .chain()
+        .insertContentAt(2, { type: 'image', attrs: { src: 'data:image/png;base64,x' } })
+        .run()
+
+      expect(editor.state.doc.firstChild?.childCount).toBe(1)
+      expect(editor.state.doc.firstChild?.textContent).toBe('a: 1')
+      expect(serializeBody(strategy, editor)).toBe('---\na: 1\n---\n\n# Heading')
+      editor.destroy()
+    })
+  })
+
+  // marked lexes the inside of a blockquote or list item with a fresh token
+  // array, so "nothing tokenized yet" is true in there too. A frontmatter node
+  // in a container is schema invalid, and whatever prunes it later takes the
+  // surrounding content with it.
+  describe('nested containers', () => {
+    function frontmatterNodes(editor: Editor) {
+      const found: string[] = []
+      editor.state.doc.descendants((node) => {
+        if (node.type.name === 'frontmatter') {
+          found.push(node.textContent)
+        }
+        return true
+      })
+
+      return found
+    }
+
+    it.each([
+      ['blockquote', '> ---\n> a: 1\n> ---\n\nFoo'],
+      ['list item', '- ---\n  a: 1\n  ---\n\nFoo']
+    ])('does not read fences inside a %s as frontmatter', (_name, content) => {
+      const strategy = createStrategy()
+      const editor = createEditor(strategy, content)
+
+      expect(frontmatterNodes(editor)).toEqual([])
+      expect(editor.state.doc.textContent).toContain('Foo')
+      expect(editor.state.doc.textContent).toContain('a: 1')
+      editor.destroy()
+    })
+
+    // A node the schema does not allow survives `Node.fromJSON`, which does not
+    // validate, and is only destroyed later by a path that does. Checking the
+    // document catches it at the source instead of via one of its symptoms.
+    it('produces a document that satisfies the schema', () => {
+      const strategy = createStrategy()
+      const editor = createEditor(strategy, '> ---\n> a: 1\n> ---\n\nFoo')
+
+      expect(() => editor.state.doc.check()).not.toThrow()
+      editor.destroy()
+    })
+
+    it('still reads fences at the top of the document as frontmatter', () => {
+      const strategy = createStrategy()
+      const editor = createEditor(strategy, '---\na: 1\n---\n\nFoo')
+
+      expect(frontmatterNodes(editor)).toEqual(['a: 1'])
+      editor.destroy()
+    })
+  })
+
+  describe('schema', () => {
+    // A document may legitimately hold nothing but metadata. `frontmatter? block+`
+    // would demand a block after it, and the resulting invalid document is only
+    // destroyed later, by whichever path enforces the schema first.
+    it.each([
+      ['metadata only', '---\na: 1\n---'],
+      ['empty metadata only', '---\n---'],
+      ['metadata and body', '---\na: 1\n---\n\n# Heading'],
+      ['body only', '# Heading']
+    ])('accepts a document with %s', (_name, content) => {
+      const strategy = createStrategy()
+      const editor = createEditor(strategy, content)
+
+      expect(() => editor.state.doc.check()).not.toThrow()
+      editor.destroy()
+    })
+
+    it('allows frontmatter only as the first block', () => {
+      const strategy = createStrategy()
+      const editor = createEditor(strategy, '# Heading\n')
+      expect(editor.state.schema.nodes.doc.spec.content).toBe('block+ | (frontmatter block*)')
+      editor.destroy()
+    })
+  })
+})
diff --git a/packages/web-pkg/tests/unit/editor/extensions/frontmatterHighlight.spec.ts b/packages/web-pkg/tests/unit/editor/extensions/frontmatterHighlight.spec.ts
new file mode 100644
index 00000000000..6d0331afe9f
--- /dev/null
+++ b/packages/web-pkg/tests/unit/editor/extensions/frontmatterHighlight.spec.ts
@@ -0,0 +1,104 @@
+import { ref } from 'vue'
+import { Editor } from '@tiptap/vue-3'
+import { createTestingPinia } from '@opencloud-eu/web-test-helpers'
+import { useStrategyMarkdown } from '../../../../src/editor/composables/strategies/markdown'
+import { frontmatterHighlightKey } from '../../../../src/editor/extensions/frontmatterHighlight'
+import type { TextEditorLinkPanelRequest, TextEditorState } from '../../../../src/editor/types'
+import type { ContentTypeStrategy } from '../../../../src/editor/composables/strategies/types'
+
+vi.mock('vue3-gettext', () => ({
+  useGettext: () => ({ $gettext: (text: string) => text })
+}))
+
+function createStrategy(): ContentTypeStrategy {
+  const state: TextEditorState = {
+    sourceMode: ref(false),
+    linkPanel: ref<TextEditorLinkPanelRequest | null>(null),
+    editorZoom: ref(100)
+  }
+  return useStrategyMarkdown(state)
+}
+
+function createEditor(strategy: ContentTypeStrategy, content: string): Editor {
+  return new Editor({
+    extensions: strategy.extensions(),
+    content: strategy.deserialize(content),
+    contentType: 'markdown'
+  })
+}
+
+/** The highlighted runs, as `[text, class]` pairs in document order. */
+function tokens(editor: Editor): [string, string][] {
+  const decorations = frontmatterHighlightKey.getState(editor.state)
+  if (!decorations) {
+    return []
+  }
+
+  return decorations
+    .find()
+    .map((decoration) => [
+      editor.state.doc.textBetween(decoration.from, decoration.to),
+      (decoration as unknown as { type: { attrs: { class: string } } }).type.attrs.class
+    ])
+}
+
+describe('frontmatterHighlight', () => {
+  beforeEach(() => {
+    createTestingPinia()
+  })
+
+  it('highlights keys and values as yaml', () => {
+    const editor = createEditor(createStrategy(), '---\ntitle: My note\n---\n\n# Heading')
+
+    expect(tokens(editor)).toContainEqual(['title:', 'hljs-attr'])
+    expect(tokens(editor).some(([, className]) => className === 'hljs-string')).toBe(true)
+    editor.destroy()
+  })
+
+  it('highlights list values and literals', () => {
+    const editor = createEditor(
+      createStrategy(),
+      '---\ntags:\n  - a\ndraft: true\n---\n\n# Heading'
+    )
+    const classes = tokens(editor).map(([, className]) => className)
+
+    expect(classes).toContain('hljs-bullet')
+    expect(classes).toContain('hljs-literal')
+    editor.destroy()
+  })
+
+  it('highlights nothing when the document has no frontmatter', () => {
+    const editor = createEditor(createStrategy(), '# Heading\n\nSome text.')
+
+    expect(tokens(editor)).toEqual([])
+    editor.destroy()
+  })
+
+  // Metadata is invalid yaml on most keystrokes, so this is the common case.
+  it('highlights invalid yaml without throwing', () => {
+    const editor = createEditor(createStrategy(), '---\ntitle: [unclosed\n---\n\n# Heading')
+
+    expect(() => tokens(editor)).not.toThrow()
+    expect(tokens(editor)).toContainEqual(['title:', 'hljs-attr'])
+    editor.destroy()
+  })
+
+  it('follows edits to the metadata', () => {
+    const editor = createEditor(createStrategy(), '---\ntitle: My note\n---\n\n# Heading')
+    editor.commands.setTextSelection(1)
+    editor.commands.insertContent('draft: true\n')
+
+    expect(tokens(editor)).toContainEqual(['draft:', 'hljs-attr'])
+    editor.destroy()
+  })
+
+  it('leaves the markdown untouched', () => {
+    const strategy = createStrategy()
+    const content = '---\ntitle: My note\ntags:\n  - a\n---\n\n# Heading'
+    const editor = createEditor(strategy, content)
+
+    expect(tokens(editor).length).toBeGreaterThan(0)
+    expect(strategy.serialize(editor.state.doc)).toBe(content)
+    editor.destroy()
+  })
+})
diff --git a/packages/web-pkg/tests/unit/editor/extensions/frontmatterParsing.spec.ts b/packages/web-pkg/tests/unit/editor/extensions/frontmatterParsing.spec.ts
new file mode 100644
index 00000000000..24cec0e7a46
--- /dev/null
+++ b/packages/web-pkg/tests/unit/editor/extensions/frontmatterParsing.spec.ts
@@ -0,0 +1,205 @@
+import { ref } from 'vue'
+import { Editor } from '@tiptap/vue-3'
+import { createTestingPinia } from '@opencloud-eu/web-test-helpers'
+import { useStrategyMarkdown } from '../../../../src/editor/composables/strategies/markdown'
+import type { TextEditorLinkPanelRequest, TextEditorState } from '../../../../src/editor/types'
+import type { ContentTypeStrategy } from '../../../../src/editor/composables/strategies/types'
+
+vi.mock('vue3-gettext', () => ({
+  useGettext: () => ({ $gettext: (text: string) => text })
+}))
+
+function createStrategy(): ContentTypeStrategy {
+  const state: TextEditorState = {
+    sourceMode: ref(false),
+    linkPanel: ref<TextEditorLinkPanelRequest | null>(null),
+    editorZoom: ref(100)
+  }
+  return useStrategyMarkdown(state)
+}
+
+function createEditor(strategy: ContentTypeStrategy, content: string): Editor {
+  return new Editor({
+    extensions: strategy.extensions(),
+    content: strategy.deserialize(content),
+    contentType: 'markdown'
+  })
+}
+
+function frontmatterDepths(editor: Editor): number[] {
+  const depths: number[] = []
+  editor.state.doc.descendants((node, _pos, parent) => {
+    if (node.type.name === 'frontmatter') {
+      depths.push(parent?.type.name === 'doc' ? 0 : 1)
+    }
+    return true
+  })
+
+  return depths
+}
+
+/**
+ * Fences that open a document are metadata, fences anywhere else are not. Every
+ * case here is a place `---` can legitimately appear, plus the containers that
+ * lex their contents with their own token list.
+ *
+ * `blocksAtTop` is how many frontmatter blocks the document should end up with.
+ * `keeps` are strings that must survive parsing, so that a rejected node can
+ * never take surrounding content with it.
+ */
+const documents: { name: string; markdown: string; blocksAtTop: number; keeps: string[] }[] = [
+  {
+    name: 'fenced code block',
+    markdown: '# H\n\n```\n---\na: 1\n---\n```',
+    blocksAtTop: 0,
+    keeps: ['a: 1']
+  },
+  {
+    name: 'tilde fenced code',
+    markdown: '# H\n\n~~~\n---\na: 1\n---\n~~~',
+    blocksAtTop: 0,
+    keeps: ['a: 1']
+  },
+  {
+    name: 'fenced code opening the document',
+    markdown: '```\n---\na: 1\n---\n```',
+    blocksAtTop: 0,
+    keeps: ['a: 1']
+  },
+  {
+    name: 'indented code block',
+    markdown: '# H\n\n    ---\n    a: 1\n    ---',
+    blocksAtTop: 0,
+    keeps: ['a: 1']
+  },
+  {
+    name: 'blockquote',
+    markdown: '> ---\n> a: 1\n> ---\n\nFoo',
+    blocksAtTop: 0,
+    keeps: ['a: 1', 'Foo']
+  },
+  {
+    name: 'nested blockquote',
+    markdown: '> > ---\n> > a: 1\n> > ---\n\nFoo',
+    blocksAtTop: 0,
+    keeps: ['a: 1', 'Foo']
+  },
+  { name: 'list item', markdown: '- ---\n  a: 1\n  ---\n\nFoo', blocksAtTop: 0, keeps: ['Foo'] },
+  { name: 'table', markdown: '| a |\n|---|\n| --- |\n\nFoo', blocksAtTop: 0, keeps: ['Foo'] },
+  { name: 'html block', markdown: '<div>\n---\n</div>\n\nFoo', blocksAtTop: 0, keeps: ['Foo'] },
+  {
+    name: 'setext heading',
+    markdown: 'Title\n---\n\nFoo',
+    blocksAtTop: 0,
+    keeps: ['Title', 'Foo']
+  },
+  {
+    name: 'thematic break opening the document',
+    markdown: '---\n\nFoo',
+    blocksAtTop: 0,
+    keeps: ['Foo']
+  },
+  {
+    name: 'blank line before the fences',
+    markdown: '\n---\na: 1\n---\n\nFoo',
+    blocksAtTop: 0,
+    keeps: ['Foo']
+  },
+  { name: 'empty document', markdown: '', blocksAtTop: 0, keeps: [] },
+  {
+    name: 'metadata then list',
+    markdown: '---\na: 1\n---\n\n- x\n- y',
+    blocksAtTop: 1,
+    keeps: ['x', 'y']
+  },
+  {
+    name: 'metadata then table',
+    markdown: '---\na: 1\n---\n\n| a |\n|---|\n| b |',
+    blocksAtTop: 1,
+    keeps: ['b']
+  },
+  {
+    name: 'metadata then blockquote',
+    markdown: '---\na: 1\n---\n\n> quoted',
+    blocksAtTop: 1,
+    keeps: ['quoted']
+  },
+  {
+    name: 'metadata then fenced code',
+    markdown: '---\na: 1\n---\n\n```\n---\n```',
+    blocksAtTop: 1,
+    keeps: []
+  },
+  {
+    name: 'metadata holding fence characters',
+    markdown: '---\ncode: "```"\n---\n\nFoo',
+    blocksAtTop: 1,
+    keeps: ['Foo']
+  },
+  {
+    name: 'metadata holding dashes',
+    markdown: '---\na: "---"\n---\n\nFoo',
+    blocksAtTop: 1,
+    keeps: ['Foo']
+  },
+  {
+    name: 'crlf line endings',
+    markdown: '---\r\na: 1\r\n---\r\n\r\nFoo',
+    blocksAtTop: 1,
+    keeps: ['Foo']
+  },
+  {
+    name: 'trailing spaces on the fences',
+    markdown: '---  \na: 1\n---  \n\nFoo',
+    blocksAtTop: 1,
+    keeps: ['Foo']
+  },
+  { name: 'metadata only', markdown: '---\na: 1\n---', blocksAtTop: 1, keeps: [] },
+  { name: 'empty metadata only', markdown: '---\n---', blocksAtTop: 1, keeps: [] },
+  {
+    name: 'thematic break in the body',
+    markdown: '---\na: 1\n---\n\nFoo\n\n---\n\nBar',
+    blocksAtTop: 1,
+    keeps: ['Foo', 'Bar']
+  }
+]
+
+describe('frontmatter parsing', () => {
+  beforeEach(() => {
+    createTestingPinia()
+  })
+
+  // A node the schema rejects survives `Node.fromJSON`, which does not validate,
+  // and is destroyed later by a path that does, taking its neighbours with it.
+  // Checking the document catches that at the source.
+  it.each(documents.map((entry) => [entry.name, entry] as const))(
+    'parses %s into a valid document',
+    (_name, entry) => {
+      const editor = createEditor(createStrategy(), entry.markdown)
+
+      expect(() => editor.state.doc.check()).not.toThrow()
+      editor.destroy()
+    }
+  )
+
+  it.each(documents.map((entry) => [entry.name, entry] as const))(
+    'reads the fences in %s correctly',
+    (_name, entry) => {
+      const editor = createEditor(createStrategy(), entry.markdown)
+
+      expect(frontmatterDepths(editor)).toEqual(Array(entry.blocksAtTop).fill(0))
+      editor.destroy()
+    }
+  )
+
+  it.each(
+    documents.filter((entry) => entry.keeps.length).map((entry) => [entry.name, entry] as const)
+  )('keeps the surrounding content of %s', (_name, entry) => {
+    const editor = createEditor(createStrategy(), entry.markdown)
+
+    for (const kept of entry.keeps) {
+      expect(editor.state.doc.textContent).toContain(kept)
+    }
+    editor.destroy()
+  })
+})
diff --git a/packages/web-pkg/tests/unit/editor/strategies/markdown.spec.ts b/packages/web-pkg/tests/unit/editor/strategies/markdown.spec.ts
index 089053e744b..05c25dadf72 100644
--- a/packages/web-pkg/tests/unit/editor/strategies/markdown.spec.ts
+++ b/packages/web-pkg/tests/unit/editor/strategies/markdown.spec.ts
@@ -8,6 +8,8 @@ vi.mock('vue3-gettext', () => ({
 }))
 
 import { useStrategyMarkdown } from '../../../../src/editor/composables/strategies/markdown'
+import { createMockEditor } from '../composables/helpers'
+import type { EditorAction } from '../../../../src/editor/composables/useEditorActions'
 import { createTestingPinia } from '@opencloud-eu/web-test-helpers'
 
 function createStrategy() {
@@ -88,6 +90,80 @@ describe('useStrategyMarkdown', () => {
     })
   })
 
+  // Inside the frontmatter block the document is raw metadata text, so anything
+  // that formats or inserts content has nothing to act on.
+  describe('actions inside the frontmatter block', () => {
+    const allowed = [
+      'undo',
+      'redo',
+      'menu-zoom',
+      'source-mode',
+      'frontmatter',
+      'menu-emoji',
+      'menu-search-and-replace',
+      'print'
+    ]
+
+    function flatten(actions: EditorAction[]): EditorAction[] {
+      return actions.flatMap((action) => [action, ...flatten(action.childActions ?? [])])
+    }
+
+    function allActions() {
+      return flatten(
+        createStrategy()
+          .editorActionGroups()
+          .flatMap(({ actions }) => actions)
+      )
+    }
+
+    function editorIn(nodeName: string) {
+      return createMockEditor({
+        canUndo: true,
+        canRedo: true,
+        isActive: (type) => type === nodeName
+      })
+    }
+
+    it('enables only navigation, view and frontmatter actions', () => {
+      const editor = editorIn('frontmatter')
+      const enabled = createStrategy()
+        .editorActionGroups()
+        .flatMap(({ actions }) => actions)
+        .filter((action) => action.isEnabled?.(editor) ?? true)
+        .map(({ id }) => id)
+
+      expect(enabled.sort()).toEqual([...allowed].sort())
+    })
+
+    it('disables nested actions as well', () => {
+      const editor = editorIn('frontmatter')
+      const enabled = allActions()
+        .filter((action) => action.isEnabled?.(editor) ?? true)
+        .map(({ id }) => id)
+
+      expect(enabled.filter((id) => !allowed.includes(id) && !id.startsWith('zoom-'))).toEqual([])
+    })
+
+    it('offers no slash entries in the frontmatter block', () => {
+      const editor = editorIn('frontmatter')
+      const slashItems = allActions()
+        .filter((action) => action.showInSlashCommands !== false)
+        .filter((action) => action.isEnabled?.(editor) ?? true)
+        .map(({ id }) => id)
+
+      expect(slashItems).toEqual([])
+    })
+
+    it('leaves everything enabled outside the block', () => {
+      const editor = editorIn('paragraph')
+      const enabled = allActions()
+        .filter((action) => action.isEnabled?.(editor) ?? true)
+        .map(({ id }) => id)
+
+      expect(enabled).toEqual(expect.arrayContaining(['bold', 'link', 'image', 'table']))
+    })
+  })
+
   describe('editorActionGroups', () => {
     it('does not include underline action but includes image actions', () => {
       const strategy = createStrategy()
@@ -108,6 +184,23 @@ describe('useStrategyMarkdown', () => {
       expect(link.showInSlashCommands).not.toBe(false)
     })
 
+    it('offers the frontmatter toggle in the insert group but not in the slash menu', () => {
+      const strategy = createStrategy()
+      const insertIds =
+        strategy
+          .editorActionGroups()
+          .find(({ id }) => id === 'insert')
+          ?.actions.map(({ id }) => id) ?? []
+      expect(insertIds.at(-1)).toBe('frontmatter')
+
+      const frontmatter = strategy
+        .editorActionGroups()
+        .flatMap(({ actions }) => actions)
+        .find(({ id }) => id === 'frontmatter')!
+      expect(frontmatter.slashCommandAction).toBeTypeOf('function')
+      expect(frontmatter.showInSlashCommands).toBe(false)
+    })
+
     it('includes source mode toggle', () => {
       const strategy = createStrategy()
       const allIds = strategy.editorActionGroups().flatMap((g) => g.actions.map((a) => a.id))
diff --git a/packages/web-pkg/tests/unit/editor/strategies/markdownMarkedInstance.spec.ts b/packages/web-pkg/tests/unit/editor/strategies/markdownMarkedInstance.spec.ts
new file mode 100644
index 00000000000..2e283acdb1e
--- /dev/null
+++ b/packages/web-pkg/tests/unit/editor/strategies/markdownMarkedInstance.spec.ts
@@ -0,0 +1,84 @@
+import { ref } from 'vue'
+import { Editor } from '@tiptap/vue-3'
+import { MarkdownManager } from '@tiptap/markdown'
+import { createTestingPinia } from '@opencloud-eu/web-test-helpers'
+import { useStrategyMarkdown } from '../../../../src/editor/composables/strategies/markdown'
+import type { TextEditorLinkPanelRequest, TextEditorState } from '../../../../src/editor/types'
+
+vi.mock('vue3-gettext', () => ({
+  useGettext: () => ({ $gettext: (text: string) => text })
+}))
+
+function createStrategy() {
+  const state: TextEditorState = {
+    sourceMode: ref(false),
+    linkPanel: ref<TextEditorLinkPanelRequest | null>(null),
+    editorZoom: ref(100)
+  }
+  return useStrategyMarkdown(state)
+}
+
+/**
+ * How many block tokenizers marked's process wide singleton carries. Every
+ * `MarkdownManager` appends its extensions' tokenizers to whichever instance it
+ * is given and never removes them, so anything registered here accumulates for
+ * the lifetime of the tab and keeps its manager reachable.
+ */
+function singletonTokenizerCount(): number {
+  const instance = new MarkdownManager({ extensions: [] }).instance as unknown as {
+    defaults?: { extensions?: { block?: unknown[] } }
+  }
+
+  return instance.defaults?.extensions?.block?.length ?? 0
+}
+
+describe('markdown strategy marked instance', () => {
+  beforeEach(() => {
+    createTestingPinia()
+  })
+
+  it('never registers tokenizers on the marked singleton', () => {
+    const before = singletonTokenizerCount()
+
+    for (let round = 0; round < 5; round++) {
+      const strategy = createStrategy()
+      const editor = new Editor({
+        extensions: strategy.extensions(),
+        content: '---\na: 1\n---\n\nFoo',
+        contentType: 'markdown'
+      })
+      // Also builds the strategy's own manager.
+      strategy.serialize(editor.state.doc)
+      editor.destroy()
+    }
+
+    expect(singletonTokenizerCount()).toBe(before)
+  })
+
+  it('still parses frontmatter with its own instance', () => {
+    const strategy = createStrategy()
+    const editor = new Editor({
+      extensions: strategy.extensions(),
+      content: '---\na: 1\n---\n\nFoo',
+      contentType: 'markdown'
+    })
+
+    expect(editor.state.doc.firstChild?.type.name).toBe('frontmatter')
+    expect(strategy.serialize(editor.state.doc)).toBe('---\na: 1\n---\n\nFoo')
+    editor.destroy()
+  })
+
+  it('gives each strategy its own instance', () => {
+    const first = createStrategy()
+    const second = createStrategy()
+    const markedOf = (strategy: ReturnType<typeof createStrategy>) =>
+      (
+        strategy.extensions().find(({ name }) => name === 'markdown') as unknown as {
+          options: { marked: unknown }
+        }
+      ).options.marked
+
+    expect(markedOf(first)).toBeDefined()
+    expect(markedOf(first)).not.toBe(markedOf(second))
+  })
+})
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index dd1c5805a38..57272437642 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -96,6 +96,9 @@ catalogs:
     '@tiptap/y-tiptap':
       specifier: ^3.0.9
       version: 3.0.9
+    marked:
+      specifier: ^17.0.1
+      version: 17.0.6
 
 overrides:
   epubjs>@xmldom/xmldom: ^0.9.10
@@ -1086,6 +1089,9 @@ importers:
       luxon:
         specifier: ^3.7.2
         version: 3.7.2
+      marked:
+        specifier: catalog:tiptap
+        version: 17.0.6
       oidc-client-ts:
         specifier: ^3.5.0
         version: 3.5.0
diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yaml
index 2266d62f035..8e9776afa1c 100644
--- a/pnpm-workspace.yaml
+++ b/pnpm-workspace.yaml
@@ -36,6 +36,9 @@ catalogs:
     '@tiptap/suggestion': ^3.30.3
     '@tiptap/vue-3': ^3.30.3
     '@tiptap/y-tiptap': ^3.0.9
+    # Kept in step with what @tiptap/markdown resolves, so the editor and the
+    # strategy share one marked instance instead of ending up with two copies.
+    marked: ^17.0.1
 
 autoInstallPeers: true
 sharedWorkspaceLockfile: true